Return to gcc.texinfo CVS log

Up to [GCC 1.x] / gcc

Annotation of gcc/gcc.texinfo, revision 1.1

1.1     ! root        1: \input texinfo  @c -*-texinfo-*-
        !             2: 
        !             3: @settitle Using and Porting GNU CC
        !             4: @setfilename gcc.info
        !             5: 
        !             6: @ifinfo
        !             7: This file documents the use and the internals of the GNU compiler.
        !             8: 
        !             9: Copyright (C) 1988 Free Software Foundation, Inc.
        !            10: 
        !            11: Permission is granted to make and distribute verbatim copies of
        !            12: this manual provided the copyright notice and this permission notice
        !            13: are preserved on all copies.
        !            14: 
        !            15: @ignore
        !            16: Permission is granted to process this file through Tex and print the
        !            17: results, provided the printed document carries copying permission
        !            18: notice identical to this one except for the removal of this paragraph
        !            19: (this paragraph not being relevant to the printed manual).
        !            20: 
        !            21: @end ignore
        !            22: Permission is granted to copy and distribute modified versions of this
        !            23: manual under the conditions for verbatim copying, provided also that the
        !            24: section entitled ``GNU CC General Public License'' is included exactly as
        !            25: in the original, and provided that the entire resulting derived work is
        !            26: distributed under the terms of a permission notice identical to this one.
        !            27: 
        !            28: Permission is granted to copy and distribute translations of this manual
        !            29: into another language, under the above conditions for modified versions,
        !            30: except that the section entitled ``GNU CC General Public License'' and
        !            31: this permission notice may be included in translations approved by the
        !            32: Free Software Foundation instead of in the original English.
        !            33: @end ifinfo
        !            34: 
        !            35: @setchapternewpage odd
        !            36: 
        !            37: @titlepage
        !            38: @center @titlefont{Using and Porting GNU CC}
        !            39: @sp 2
        !            40: @center Richard M. Stallman
        !            41: @sp 3
        !            42: @center last updated 3 October 1988
        !            43: @sp 1
        !            44: @center for version 1.29
        !            45: @page
        !            46: @vskip 0pt plus 1filll
        !            47: Copyright @copyright{} 1988 Free Software Foundation, Inc.
        !            48: 
        !            49: Permission is granted to make and distribute verbatim copies of
        !            50: this manual provided the copyright notice and this permission notice
        !            51: are preserved on all copies.
        !            52: 
        !            53: Permission is granted to copy and distribute modified versions of this
        !            54: manual under the conditions for verbatim copying, provided also that the
        !            55: section entitled ``GNU CC General Public License'' is included exactly as
        !            56: in the original, and provided that the entire resulting derived work is
        !            57: distributed under the terms of a permission notice identical to this one.
        !            58: 
        !            59: Permission is granted to copy and distribute translations of this manual
        !            60: into another language, under the above conditions for modified versions,
        !            61: except that the section entitled ``GNU CC General Public License'' and
        !            62: this permission notice may be included in translations approved by the
        !            63: Free Software Foundation instead of in the original English.
        !            64: @end titlepage
        !            65: @page
        !            66: 
        !            67: @ifinfo
        !            68: @node Top, Copying,, (DIR)
        !            69: @ichapter Introduction
        !            70: 
        !            71: This manual documents how to run, install and port the GNU C compiler, as
        !            72: well as its new features and incompatibilities, and how to report bugs.
        !            73: 
        !            74: @end ifinfo
        !            75: @menu
        !            76: * Copying::         GNU CC General Public License says
        !            77:                      how you can copy and share GNU CC.
        !            78: * Contributors::    People who have contributed to GNU CC.
        !            79: * Options::         Command options supported by @samp{gcc}.
        !            80: * Installation::    How to configure, compile and install GNU CC.
        !            81: * Trouble::         If you have trouble installing GNU CC.
        !            82: * Incompatibilities:: Incompatibilities of GNU CC.
        !            83: * Extensions::      GNU extensions to the C language.
        !            84: * Bugs::            How to report bugs (if you want to get them fixed).
        !            85: * Portability::     Goals of GNU CC's portability features.
        !            86: * Interface::       Function-call interface of GNU CC output.
        !            87: * Passes::          Order of passes, what they do, and what each file is for.
        !            88: * RTL::             The intermediate representation that most passes work on.
        !            89: * Machine Desc::    How to write machine description instruction patterns.
        !            90: * Machine Macros::  How to write the machine description C macros.
        !            91: @end menu
        !            92: 
        !            93: @node Copying, Contributors, Top, Top
        !            94: @unnumbered GNU CC GENERAL PUBLIC LICENSE
        !            95: @center (Clarified 11 Feb 1988)
        !            96: 
        !            97:   The license agreements of most software companies keep you at the
        !            98: mercy of those companies.  By contrast, our general public license is
        !            99: intended to give everyone the right to share GNU CC.  To make sure that
        !           100: you get the rights we want you to have, we need to make restrictions
        !           101: that forbid anyone to deny you these rights or to ask you to surrender
        !           102: the rights.  Hence this license agreement.
        !           103: 
        !           104:   Specifically, we want to make sure that you have the right to give
        !           105: away copies of GNU CC, that you receive source code or else can get it
        !           106: if you want it, that you can change GNU CC or use pieces of it in new
        !           107: free programs, and that you know you can do these things.
        !           108: 
        !           109:   To make sure that everyone has such rights, we have to forbid you to
        !           110: deprive anyone else of these rights.  For example, if you distribute
        !           111: copies of GNU CC, you must give the recipients all the rights that you
        !           112: have.  You must make sure that they, too, receive or can get the
        !           113: source code.  And you must tell them their rights.
        !           114: 
        !           115:   Also, for our own protection, we must make certain that everyone
        !           116: finds out that there is no warranty for GNU CC.  If GNU CC is modified by
        !           117: someone else and passed on, we want its recipients to know that what
        !           118: they have is not what we distributed, so that any problems introduced
        !           119: by others will not reflect on our reputation.
        !           120: 
        !           121:   Therefore we (Richard Stallman and the Free Software Foundation,
        !           122: Inc.) make the following terms which say what you must do to be
        !           123: allowed to distribute or change GNU CC.
        !           124: 
        !           125: @unnumberedsec COPYING POLICIES
        !           126: 
        !           127: @enumerate
        !           128: @item
        !           129: You may copy and distribute verbatim copies of GNU CC source code as
        !           130: you receive it, in any medium, provided that you conspicuously and
        !           131: appropriately publish on each copy a valid copyright notice
        !           132: ``Copyright @copyright{} 1988 Free Software Foundation, Inc.'' (or
        !           133: with whatever year is appropriate); keep intact the notices on all
        !           134: files that refer to this License Agreement and to the absence of any
        !           135: warranty; and give any other recipients of the GNU CC program a copy
        !           136: of this License Agreement along with the program.  You may charge a
        !           137: distribution fee for the physical act of transferring a copy.
        !           138: 
        !           139: @item
        !           140: You may modify your copy or copies of GNU CC or any portion of it,
        !           141: and copy and distribute such modifications under the terms of
        !           142: Paragraph 1 above, provided that you also do the following:
        !           143: 
        !           144: @itemize @bullet
        !           145: @item
        !           146: cause the modified files to carry prominent notices stating
        !           147: that you changed the files and the date of any change; and
        !           148: 
        !           149: @item
        !           150: cause the whole of any work that you distribute or publish, that
        !           151: in whole or in part contains or is a derivative of GNU CC or any
        !           152: part thereof, to be licensed at no charge to all third parties on
        !           153: terms identical to those contained in this License Agreement
        !           154: (except that you may choose to grant more extensive warranty
        !           155: protection to some or all third parties, at your option).
        !           156: 
        !           157: @item
        !           158: You may charge a distribution fee for the physical act of
        !           159: transferring a copy, and you may at your option offer warranty
        !           160: protection in exchange for a fee.
        !           161: @end itemize
        !           162: 
        !           163: Mere aggregation of another unrelated program with this program (or its
        !           164: derivative) on a volume of a storage or distribution medium does not bring
        !           165: the other program under the scope of these terms.
        !           166: 
        !           167: @item
        !           168: You may copy and distribute GNU CC (or a portion or derivative of it,
        !           169: under Paragraph 2) in object code or executable form under the terms
        !           170: of Paragraphs 1 and 2 above provided that you also do one of the
        !           171: following:
        !           172: 
        !           173: @itemize @bullet
        !           174: @item
        !           175: accompany it with the complete corresponding machine-readable
        !           176: source code, which must be distributed under the terms of
        !           177: Paragraphs 1 and 2 above; or,
        !           178: 
        !           179: @item
        !           180: accompany it with a written offer, valid for at least three
        !           181: years, to give any third party free (except for a nominal
        !           182: shipping charge) a complete machine-readable copy of the
        !           183: corresponding source code, to be distributed under the terms of
        !           184: Paragraphs 1 and 2 above; or,
        !           185: 
        !           186: @item
        !           187: accompany it with the information you received as to where the
        !           188: corresponding source code may be obtained.  (This alternative is
        !           189: allowed only for noncommercial distribution and only if you
        !           190: received the program in object code or executable form alone.)
        !           191: @end itemize
        !           192: 
        !           193: For an executable file, complete source code means all the source code
        !           194: for all modules it contains; but, as a special exception, it need not
        !           195: include source code for modules which are standard libraries that
        !           196: accompany the operating system on which the executable file runs.
        !           197: 
        !           198: @item
        !           199: You may not copy, sublicense, distribute or transfer GNU CC except as
        !           200: expressly provided under this License Agreement.  Any attempt
        !           201: otherwise to copy, sublicense, distribute or transfer GNU CC is void
        !           202: and your rights to use the program under this License agreement shall
        !           203: be automatically terminated.  However, parties who have received
        !           204: computer software programs from you with this License Agreement will
        !           205: not have their licenses terminated so long as such parties remain in
        !           206: full compliance.
        !           207: 
        !           208: @item
        !           209: If you wish to incorporate parts of GNU CC into other free programs
        !           210: whose distribution conditions are different, write to the Free Software
        !           211: Foundation at 675 Mass Ave, Cambridge, MA 02139.  We have not yet worked
        !           212: out a simple rule that can be stated here, but we will often permit this.
        !           213: We will be guided by the two goals of preserving the free status of all
        !           214: derivatives of our free software and of promoting the sharing and reuse of
        !           215: software.
        !           216: @end enumerate
        !           217: 
        !           218: Your comments and suggestions about our licensing policies and our
        !           219: software are welcome!  Please contact the Free Software Foundation, Inc.,
        !           220: 675 Mass Ave, Cambridge, MA 02139, or call (617) 876-3296.
        !           221: 
        !           222: @unnumberedsec NO WARRANTY
        !           223: 
        !           224:   BECAUSE GNU CC IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO
        !           225: WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.  EXCEPT
        !           226: WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC,
        !           227: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU CC "AS IS" WITHOUT
        !           228: WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
        !           229: LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
        !           230: A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND
        !           231: PERFORMANCE OF GNU CC IS WITH YOU.  SHOULD GNU CC PROVE DEFECTIVE, YOU
        !           232: ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
        !           233: 
        !           234:  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL RICHARD M.
        !           235: STALLMAN, THE FREE SOFTWARE FOUNDATION, INC., AND/OR ANY OTHER PARTY
        !           236: WHO MAY MODIFY AND REDISTRIBUTE GNU CC AS PERMITTED ABOVE, BE LIABLE TO
        !           237: YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
        !           238: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
        !           239: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
        !           240: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
        !           241: FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) GNU CC, EVEN
        !           242: IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR
        !           243: ANY CLAIM BY ANY OTHER PARTY.
        !           244: 
        !           245: @node Contributors, Options, Copying, Top
        !           246: @unnumbered Contributors to GNU CC
        !           247: 
        !           248: In addition to Richard Stallman, several people have written parts
        !           249: of GNU CC.
        !           250: 
        !           251: @itemize @bullet
        !           252: @item
        !           253: The idea of using RTL and some of the optimization ideas came from the
        !           254: U. of Arizona Portable Optimizer, written by Jack Davidson and
        !           255: Christopher Fraser.  See ``Register Allocation and Exhaustive Peephole
        !           256: Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
        !           257: 857-866.
        !           258: 
        !           259: @item
        !           260: Paul Rubin wrote most of the preprocessor.
        !           261: 
        !           262: @item
        !           263: Leonard Tower wrote parts of the parser, RTL generator, RTL
        !           264: definitions, and of the Vax machine description.
        !           265: 
        !           266: @item
        !           267: Ted Lemon wrote parts of the RTL reader and printer.
        !           268: 
        !           269: @item
        !           270: Jim Wilson implemented loop strength reduction and some other
        !           271: loop optimizations.
        !           272: 
        !           273: @item
        !           274: Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
        !           275: the support for the SONY NEWS machine.
        !           276: 
        !           277: @item
        !           278: Charles LaBrec contributed the support for the Integrated Solutions
        !           279: 68020 system.
        !           280: 
        !           281: @item
        !           282: Michael Tiemann of MCC wrote most of the description of the National
        !           283: Semiconductor 32000 series cpu.  He also wrote the code for inline
        !           284: function integration and for the SPARC cpu and Motorola 88000 cpu
        !           285: and part of the Sun FPA support.
        !           286: 
        !           287: @item
        !           288: Jan Stein of the Chalmers Computer Society provided support for
        !           289: Genix, as well as part of the 32000 machine description.
        !           290: 
        !           291: @item
        !           292: Randy Smith finished the Sun FPA support.
        !           293: 
        !           294: @item
        !           295: Robert Brown implemented the support for Encore 32000 systems.
        !           296: 
        !           297: @item
        !           298: David Kashtan of SRI adapted GNU CC to the Vomit-Making System.
        !           299: 
        !           300: @item
        !           301: Alex Crain provided changes for the 3b1.
        !           302: 
        !           303: @item
        !           304: Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for
        !           305: the 9000 series 300.
        !           306: 
        !           307: @item
        !           308: William Schelter did most of the work on the Intel 80386 support.
        !           309: @end itemize
        !           310: 
        !           311: @node Options, Installation, Contributors, Top
        !           312: @chapter GNU CC Command Options
        !           313: 
        !           314: The GNU C compiler uses a command syntax much like the Unix C compiler.
        !           315: The @code{gcc} program accepts options and file names as operands.
        !           316: Multiple single-letter options may @emph{not} be grouped: @samp{-dr} is
        !           317: very different from @samp{-d -r}.
        !           318: 
        !           319: When you invoke GNU CC, it normally does preprocessing, compilation,
        !           320: assembly and linking.  File names which end in @samp{.c} are taken as C
        !           321: source to be preprocessed and compiled; compiler output files plus any
        !           322: input files with names ending in @samp{.s} are assembled; then the
        !           323: resulting object files, plus any other input files, are linked together to
        !           324: produce an executable.
        !           325: 
        !           326: Command options allow you to stop this process at an intermediate stage.
        !           327: For example, the @samp{-c} option says not to run the linker.  Then the
        !           328: output consists of object files output by the assembler.
        !           329: 
        !           330: Other command options are passed on to one stage.  Some options control
        !           331: the preprocessor and others the compiler itself.  Yet other options
        !           332: control the assembler and linker; these are not documented here because the
        !           333: GNU assembler and linker are not yet released.
        !           334: 
        !           335: Here are the options to control the overall compilation process, including
        !           336: those that say whether to link, whether to assemble, and so on.
        !           337: 
        !           338: @table @samp
        !           339: @item -o @var{file}
        !           340: Place output in file @var{file}.  This applies regardless to whatever
        !           341: sort of output is being produced, whether it be an executable file,
        !           342: an object file, an assembler file or preprocessed C code.
        !           343: 
        !           344: If @samp{-o} is not specified, the default is to put an executable file
        !           345: in @file{a.out}, the object file @file{@var{source}.c} in
        !           346: @file{@var{source}.o}, an assembler file in @file{@var{source}.s}, and
        !           347: preprocessed C on standard output.@refill
        !           348: 
        !           349: @item -c
        !           350: Compile or assemble the source files, but do not link.  Produce object
        !           351: files with names made by replacing @samp{.c} or @samp{.s} with
        !           352: @samp{.o} at the end of the input file names.  Do nothing at all for
        !           353: object files specified as input.
        !           354: 
        !           355: @item -S
        !           356: Compile into assembler code but do not assemble.  The assembler output
        !           357: file name is made by replacing @samp{.c} with @samp{.s} at the end of
        !           358: the input file name.  Do nothing at all for assembler source files or
        !           359: object files specified as input.
        !           360: 
        !           361: @item -E
        !           362: Run only the C preprocessor.  Preprocess all the C source files
        !           363: specified and output the results to standard output.
        !           364: 
        !           365: @item -v
        !           366: Compiler driver program prints the commands it executes as it runs
        !           367: the preprocessor, compiler proper, assembler and linker.  Some of
        !           368: these are directed to print their own version numbers.
        !           369: 
        !           370: @item -B@var{prefix}
        !           371: Compiler driver program tries @var{prefix} as a prefix for each
        !           372: program it tries to run.  These programs are @file{cpp}, @file{cc1},
        !           373: @file{as} and @file{ld}.
        !           374: 
        !           375: For each subprogram to be run, the compiler driver first tries the
        !           376: @samp{-B} prefix, if any.  If that name is not found, or if @samp{-B}
        !           377: was not specified, the driver tries two standard prefixes, which are
        !           378: @file{/usr/lib/gcc-} and @file{/usr/local/lib/gcc-}.  If neither of
        !           379: those results in a file name that is found, the unmodified program
        !           380: name is searched for using the directories specified in your
        !           381: @samp{PATH} environment variable.
        !           382: 
        !           383: The run-time support file @file{gnulib} is also searched for using
        !           384: the @samp{-B} prefix, if needed.  If it is not found there, the two
        !           385: standard prefixes above are tried, and that is all.  The file is left
        !           386: out of the link if it is not found by those means.  Most of the time,
        !           387: on most machines, you can do without it.
        !           388: @end table
        !           389: 
        !           390: These options control the details of C compilation itself.
        !           391: 
        !           392: @table @samp
        !           393: @item -ansi
        !           394: Support all ANSI standard C programs.
        !           395: 
        !           396: This turns off certain features of GNU C that are incompatible with
        !           397: ANSI C, such as the @code{asm}, @code{inline} and @code{typeof}
        !           398: keywords, and predefined macros such as @code{unix} and @code{vax}
        !           399: that identify the type of system you are using.  It also enables the
        !           400: undesirable and rarely used ANSI trigraph feature.
        !           401: 
        !           402: The @samp{-ansi} option does not cause non-ANSI programs to be
        !           403: rejected gratuitously.  For that, @samp{-pedantic} is required in
        !           404: addition to @samp{-ansi}.
        !           405: 
        !           406: The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
        !           407: option is used.  Some header files may notice this macro and refrain
        !           408: from declaring certain functions or defining certain macros that the
        !           409: ANSI standard doesn't call for; this is to avoid interfering with
        !           410: any programs that might use these names for other things.
        !           411: 
        !           412: @item -traditional
        !           413: Attempt to support some aspects of traditional C compilers.
        !           414: Specifically:
        !           415: 
        !           416: @itemize @bullet
        !           417: @item
        !           418: All @code{extern} declarations take effect globally even if they
        !           419: are written inside of a function definition.  This includes implicit
        !           420: declarations of functions.
        !           421: 
        !           422: @item
        !           423: The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
        !           424: and @code{volatile} are not recognized.@refill
        !           425: 
        !           426: @item
        !           427: Comparisons between pointers and integers are always allowed.
        !           428: 
        !           429: @item
        !           430: Integer types @code{unsigned short} and @code{unsigned char} promote
        !           431: to @code{unsigned int}.
        !           432: 
        !           433: @item
        !           434: Out-of-range floating point literals are not an error.
        !           435: 
        !           436: @item
        !           437: In the preprocessor, comments convert to nothing at all, rather than
        !           438: to a space.  This allows traditional token concatenation.
        !           439: 
        !           440: @item
        !           441: In the preprocessor, macro arguments are recognized within string
        !           442: constants in a macro definition (and their values are stringified,
        !           443: though without additional quote marks, when they appear in such a
        !           444: context).  The preprocessor always considers a string constant to end
        !           445: at a newline.
        !           446: 
        !           447: @item
        !           448: The predefined macro @code{__STDC__} is not defined when you use
        !           449: @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
        !           450: which @code{__GNUC__} indicates are not affected by
        !           451: @samp{-traditional}).  If you need to write header files that work
        !           452: differently depending on whether @samp{-traditional} is in use, by
        !           453: testing both of these predefined macros you can distinguish four
        !           454: situations: GNU C, traditional GNU C, other ANSI C compilers, and
        !           455: other old C compilers.
        !           456: @end itemize
        !           457: 
        !           458: @item -O
        !           459: Optimize.  Optimizing compilation takes somewhat more time, and a lot
        !           460: more memory for a large function.
        !           461: 
        !           462: Without @samp{-O}, the compiler's goal is to reduce the cost of
        !           463: compilation and to make debugging produce the expected results.
        !           464: Statements are independent: if you stop the program with a breakpoint
        !           465: between statements, you can then assign a new value to any variable or
        !           466: change the program counter to any other statement in the function and
        !           467: get exactly the results you would expect from the source code.
        !           468: 
        !           469: Without @samp{-O}, only variables declared @code{register} are
        !           470: allocated in registers.  The resulting compiled code is a little worse
        !           471: than produced by PCC without @samp{-O}.
        !           472: 
        !           473: With @samp{-O}, the compiler tries to reduce code size and execution
        !           474: time.
        !           475: 
        !           476: Some of the @samp{-f} options described below turn specific kinds of
        !           477: optimization on or off.
        !           478: 
        !           479: @item -g
        !           480: Produce debugging information in the operating system's native format
        !           481: (for DBX or SDB).  GDB also can work with this debugging information.
        !           482: 
        !           483: Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
        !           484: @samp{-O}.  The shortcuts taken by optimized code may occasionally
        !           485: produce surprising results: some variables you declared may not exist
        !           486: at all; flow of control may briefly move where you did not expect it;
        !           487: some statements may not be executed because they compute constant
        !           488: results or their values were already at hand; some statements may
        !           489: execute in different places because they were moved out of loops.
        !           490: Nevertheless it proves possible to debug optimized output.  This makes
        !           491: it reasonable to use the optimizer for programs that might have bugs.
        !           492: 
        !           493: @item -gg
        !           494: Produce debugging information in GDB's own format.  This requires the
        !           495: GNU assembler and linker in order to work.
        !           496: 
        !           497: This feature will probably be eliminated.  It was intended to enable
        !           498: GDB to read the symbol table faster, but it doesn't result in enough
        !           499: of a speedup to be worth the larger object files and executables.  We
        !           500: are working on other ways of making GDB start faster, which work with
        !           501: DBX format debugging information and could be made to work with SDB
        !           502: format.
        !           503: 
        !           504: @item -w
        !           505: Inhibit all warning messages.
        !           506: 
        !           507: @item -W
        !           508: Print extra warning messages for these events:
        !           509: 
        !           510: @itemize @bullet
        !           511: @item
        !           512: An automatic variable is used without first being initialized.
        !           513: 
        !           514: These warnings are possible only in optimizing compilation,
        !           515: because they require data flow information that is computed only
        !           516: when optimizing.  They occur only for variables that are
        !           517: candidates for register allocation.  Therefore, they do not occur
        !           518: for a variable that is declared @code{volatile}, or whose address
        !           519: is taken, or whose size is other than 1, 2, 4 or 8 bytes.  Also,
        !           520: they do not occur for structures, unions or arrays, even when
        !           521: they are in registers.
        !           522: 
        !           523: Note that there may be no warning about a variable that is used
        !           524: only to compute a value that itself is never used, because such
        !           525: computations may be deleted by the flow analysis pass before the
        !           526: warnings are printed.
        !           527: 
        !           528: These warnings are made optional because GNU CC is not smart
        !           529: enough to see all the reasons why the code might be correct
        !           530: despite appearing to have an error.  Here is one example of how
        !           531: this can happen:
        !           532: 
        !           533: @example
        !           534: @{
        !           535:   int x;
        !           536:   switch (y)
        !           537:     @{
        !           538:     case 1: x = 1;
        !           539:       break;
        !           540:     case 2: x = 4;
        !           541:       break;
        !           542:     case 3: x = 5;
        !           543:     @}
        !           544:   foo (x);
        !           545: @}
        !           546: @end example
        !           547: 
        !           548: @noindent
        !           549: If the value of @code{y} is always 1, 2 or 3, then @code{x} is
        !           550: always initialized, but GNU CC doesn't know this.  Here is
        !           551: another common case:
        !           552: 
        !           553: @example
        !           554: @{
        !           555:   int save_y;
        !           556:   if (change_y) save_y = y, y = new_y;
        !           557:   @dots{}
        !           558:   if (change_y) y = save_y;
        !           559: @}
        !           560: @end example
        !           561: 
        !           562: @noindent
        !           563: This has no bug because @code{save_y} is used only if it is set.
        !           564: 
        !           565: @item
        !           566: A nonvolatile automatic variable might be changed by a call to
        !           567: @code{longjmp}.  These warnings as well are possible only in
        !           568: optimizing compilation.
        !           569: 
        !           570: The compiler sees only the calls to @code{setjmp}.  It cannot know
        !           571: where @code{longjmp} will be called; in fact, a signal handler could
        !           572: call it at any point in the code.  As a result, you may get a warning
        !           573: even when there is in fact no problem because @code{longjmp} cannot
        !           574: in fact be called at the place which would cause a problem.
        !           575: 
        !           576: @item
        !           577: A function can return either with or without a value.  (Falling
        !           578: off the end of the function body is considered returning without
        !           579: a value.)  For example, this function would inspire such a
        !           580: warning:
        !           581: 
        !           582: @example
        !           583: foo (a)
        !           584: @{
        !           585:   if (a > 0)
        !           586:     return a;
        !           587: @}
        !           588: @end example
        !           589: 
        !           590: Spurious warnings can occur because GNU CC does not realize that
        !           591: certain functions (including @code{abort} and @code{longjmp})
        !           592: will never return.
        !           593: @end itemize
        !           594: 
        !           595: In the future, other useful warnings may also be enabled by this
        !           596: option.
        !           597: 
        !           598: @item -Wimplicit
        !           599: Warn whenever a function is implicitly declared.
        !           600: 
        !           601: @item -Wreturn-type
        !           602: Warn whenever a function is defined with a return-type that defaults
        !           603: to @code{int}.  Also warn about any @code{return} statement with no
        !           604: return-value in a function whose return-type is not @code{void}.
        !           605: 
        !           606: @item -Wunused
        !           607: Warn whenever a local variable is unused aside from its declaration.
        !           608: 
        !           609: @item -Wcomment
        !           610: Warn whenever a comment-start sequence @samp{/*} appears in a comment.
        !           611: 
        !           612: @item -Wall
        !           613: All of the above @samp{-W} options combined.
        !           614: 
        !           615: @item -Wwrite-strings
        !           616: Give string constants the type @code{const char[@var{length}]} so that
        !           617: copying the address of one into a non-@code{const} @code{char *}
        !           618: pointer will get a warning.  These warnings will help you find at
        !           619: compile time code that can try to write into a string constant, but
        !           620: only if you have been very careful about using @code{const} in
        !           621: declarations and prototypes.  Otherwise, it will just be a nuisance;
        !           622: this is why we did not make @samp{-Wall} request these warnings.
        !           623: 
        !           624: @item -p
        !           625: Generate extra code to write profile information suitable for the
        !           626: analysis program @code{prof}.
        !           627: 
        !           628: @item -pg
        !           629: Generate extra code to write profile information suitable for the
        !           630: analysis program @code{gprof}.
        !           631: 
        !           632: @item -l@var{library}
        !           633: Search a standard list of directories for a library named
        !           634: @var{library}, which is actually a file named
        !           635: @file{lib@var{library}.a}.  The linker uses this file as if it
        !           636: had been specified precisely by name.
        !           637: 
        !           638: The directories searched include several standard system directories
        !           639: plus any that you specify with @samp{-L}.
        !           640: 
        !           641: Normally the files found this way are library files---archive files
        !           642: whose members are object files.  The linker handles an archive file by
        !           643: scanning through it for members which define symbols that have so far
        !           644: been referenced but not defined.  But if the file that is found is an
        !           645: ordinary object file, it is linked in the usual fashion.  The only
        !           646: difference between using an @samp{-l} option and specifying a file name
        !           647: is that @samp{-l} searches several directories.
        !           648: 
        !           649: @item -L@var{dir}
        !           650: Add directory @var{dir} to the list of directories to be searched
        !           651: for @samp{-l}.
        !           652: 
        !           653: @item -nostdlib
        !           654: Don't use the standard system libraries and startup files when
        !           655: linking.  Only the files you specify (plus @file{gnulib}) will be
        !           656: passed to the linker.
        !           657: 
        !           658: @item -m@var{machinespec}
        !           659: Machine-dependent option specifying something about the type of target
        !           660: machine.  These options are defined by the macro
        !           661: @code{TARGET_SWITCHES} in the machine description.  The default for
        !           662: the options is also defined by that macro, which enables you to change
        !           663: the defaults.@refill
        !           664: 
        !           665: These are the @samp{-m} options defined in the 68000 machine
        !           666: description:
        !           667: 
        !           668: @table @samp
        !           669: @item -m68020
        !           670: @itemx -mc68020
        !           671: Generate output for a 68020 (rather than a 68000).  This is the
        !           672: default if you use the unmodified sources.
        !           673: 
        !           674: @item -m68000
        !           675: @item -mc68000
        !           676: Generate output for a 68000 (rather than a 68020).
        !           677: 
        !           678: @item -m68881
        !           679: Generate output containing 68881 instructions for floating point.
        !           680: This is the default if you use the unmodified sources.
        !           681: 
        !           682: @item -mfpa
        !           683: Generate output containing Sun FPA instructions for floating point.
        !           684: 
        !           685: @item -msoft-float
        !           686: Generate output containing library calls for floating point.
        !           687: 
        !           688: @item -mshort
        !           689: Consider type @code{int} to be 16 bits wide, like @code{short int}.
        !           690: 
        !           691: @item -mnobitfield
        !           692: Do not use the bit-field instructions.  @samp{-m68000} implies
        !           693: @samp{-mnobitfield}.
        !           694: 
        !           695: @item -mbitfield
        !           696: Do use the bit-field instructions.  @samp{-m68020} implies
        !           697: @samp{-mbitfield}.  This is the default if you use the unmodified
        !           698: sources.
        !           699: 
        !           700: @item -mrtd
        !           701: Use a different function-calling convention, in which functions
        !           702: that take a fixed number of arguments return with the @code{rtd}
        !           703: instruction, which pops their arguments while returning.  This
        !           704: saves one instruction in the caller since there is no need to pop
        !           705: the arguments there.
        !           706: 
        !           707: This calling convention is incompatible with the one normally
        !           708: used on Unix, so you cannot use it if you need to call libraries
        !           709: compiled with the Unix compiler.
        !           710: 
        !           711: Also, you must provide function prototypes for all functions that
        !           712: take variable numbers of arguments (including @code{printf});
        !           713: otherwise incorrect code will be generated for calls to those
        !           714: functions.
        !           715: 
        !           716: In addition, seriously incorrect code will result if you call a
        !           717: function with too many arguments.  (Normally, extra arguments are
        !           718: harmlessly ignored.)
        !           719: 
        !           720: The @code{rtd} instruction is supported by the 68010 and 68020
        !           721: processors, but not by the 68000.
        !           722: @end table
        !           723: 
        !           724: These @samp{-m} options are defined in the Vax machine description:
        !           725: 
        !           726: @table @samp
        !           727: @item -munix
        !           728: Do not output certain jump instructions (@code{aobleq} and so on)
        !           729: that the Unix assembler for the Vax cannot handle across long
        !           730: ranges.
        !           731: 
        !           732: @item -mgnu
        !           733: Do output those jump instructions, on the assumption that you
        !           734: will assemble with the GNU assembler.
        !           735: 
        !           736: @item -mg
        !           737: Output code for g-format floating point numbers instead of d-format.
        !           738: @end table
        !           739: 
        !           740: @item -f@var{flag}
        !           741: Specify machine-independent flags.  These are the flags:
        !           742: 
        !           743: @table @samp
        !           744: @item -ffloat-store
        !           745: Do not store floating-point variables in registers.  This
        !           746: prevents undesirable excess precision on machines such as the
        !           747: 68000 where the floating registers (of the 68881) keep more
        !           748: precision than a @code{double} is supposed to have.
        !           749: 
        !           750: For most programs, the excess precision does only good, but a few
        !           751: programs rely on the precise definition of IEEE floating point.
        !           752: Use @samp{-ffloat-store} for such programs.
        !           753: 
        !           754: @item -fno-asm
        !           755: Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
        !           756: keyword.  These words may then be used as identifiers.
        !           757: 
        !           758: @item -fno-defer-pop
        !           759: Always pop the arguments to each function call as soon as that
        !           760: function returns.  Normally the compiler (when optimizing) lets
        !           761: arguments accumulate on the stack for several function calls and
        !           762: pops them all at once.
        !           763: 
        !           764: @item -fstrength-reduce
        !           765: Perform the optimizations of loop strength reduction and
        !           766: elimination of iteration variables.
        !           767: 
        !           768: @item -fcombine-regs
        !           769: Allow the combine pass to combine an instruction that copies one
        !           770: register into another.  This might or might not produce better
        !           771: code when used in addition to @samp{-O}.  I am interested in
        !           772: hearing about the difference this makes.
        !           773: 
        !           774: @item -fforce-mem
        !           775: Force memory operands to be copied into registers before doing
        !           776: arithmetic on them.  This may produce better code by making all
        !           777: memory references potential common subexpressions.  When they are
        !           778: not common subexpressions, instruction combination should
        !           779: eliminate the separate register-load.  I am interested in hearing
        !           780: about the difference this makes.
        !           781: 
        !           782: @item -fforce-addr
        !           783: Force memory address constants to be copied into registers before
        !           784: doing arithmetic on them.  This may produce better code just as
        !           785: @samp{-fforce-mem} may.  I am interested in hearing about the
        !           786: difference this makes.
        !           787: 
        !           788: @item -fomit-frame-pointer
        !           789: Don't keep the frame pointer in a register for functions that
        !           790: don't need one.  This avoids the instructions to save, set up and
        !           791: restore frame pointers; it also makes an extra register available
        !           792: in many functions.  @strong{It also makes debugging impossible.}
        !           793: 
        !           794: On some machines, such as the Vax, this flag has no effect,
        !           795: because the standard calling sequence automatically handles the
        !           796: frame pointer and nothing is saved by pretending it doesn't
        !           797: exist.  The machine-description macro
        !           798: @code{FRAME_POINTER_REQUIRED} controls whether a target machine
        !           799: supports this flag.  @xref{Registers}.@refill
        !           800: 
        !           801: @item -finline-functions
        !           802: Integrate all simple functions into their callers.  The compiler
        !           803: heuristically decides which functions are simple enough to be
        !           804: worth integrating in this way.
        !           805: 
        !           806: If all calls to a given function are integrated, and the function
        !           807: is declared @code{static}, then the function is normally not
        !           808: output as assembler code in its own right.
        !           809: 
        !           810: @item -fkeep-inline-functions
        !           811: Even if all calls to a given function are integrated, and the
        !           812: function is declared @code{static}, nevertheless output a
        !           813: separate run-time callable version of the function.
        !           814: 
        !           815: @item -fwritable-strings
        !           816: Store string constants in the writable data segment and don't
        !           817: uniquize them.  This is for compatibility with old programs which
        !           818: assume they can write into string constants.  Writing into string
        !           819: constants is a very bad idea; ``constants'' should be constant.
        !           820: 
        !           821: @item -fno-function-cse
        !           822: Do not put function addresses in registers; make each instruction
        !           823: that calls a constant function contain the function's address
        !           824: explicitly.
        !           825: 
        !           826: This option results in less efficient code, but some strange
        !           827: hacks that alter the assembler output may be confused by the
        !           828: optimizations performed when this option is not used.
        !           829: 
        !           830: @item -fvolatile
        !           831: Consider all memory references through pointers to be volatile.
        !           832: 
        !           833: @item -funsigned-char
        !           834: Let the type @code{char} be the unsigned, like @code{unsigned
        !           835: char}.
        !           836: 
        !           837: Each kind of machine has a default for what @code{char} should
        !           838: be.  It is either like @code{unsigned char} by default or like
        !           839: @code{signed char} by default.  (Actually, at present, the
        !           840: default is always signed.)
        !           841: 
        !           842: The type @code{char} is always a distinct type from either
        !           843: @code{signed char} or @code{unsigned char}, even though its
        !           844: behavior is always just like one of those two.
        !           845: 
        !           846: @item -fsigned-char
        !           847: Let the type @code{char} be signed, like @code{signed char}.
        !           848: 
        !           849: @item -ffixed-@var{reg}
        !           850: Treat the register named @var{reg} as a fixed register; generated
        !           851: code should never refer to it (except perhaps as a stack pointer,
        !           852: frame pointer or in some other fixed role).
        !           853: 
        !           854: @var{reg} must be the name of a register.  The register names
        !           855: accepted are machine-specific and are defined in the
        !           856: @code{REGISTER_NAMES} macro in the machine description macro
        !           857: file.
        !           858: 
        !           859: @item -fcall-used-@var{reg}
        !           860: Treat the register named @var{reg} as an allocatable register
        !           861: that is clobbered by function calls.  It may be allocated for
        !           862: temporaries or variables that do not live across a call.
        !           863: Functions compiled this way will not save and restore the
        !           864: register @var{reg}.
        !           865: 
        !           866: Use of this flag for a register that has a fixed pervasive role
        !           867: in the machine's execution model, such as the stack pointer or
        !           868: frame pointer, will produce disastrous results.
        !           869: 
        !           870: @item -fcall-saved-@var{reg}
        !           871: Treat the register named @var{reg} as an allocatable register
        !           872: saved by functions.  It may be allocated even for temporaries or
        !           873: variables that live across a call.  Functions compiled this way
        !           874: will save and restore the register @var{reg} if they use it.
        !           875: 
        !           876: Use of this flag for a register that has a fixed pervasive role
        !           877: in the machine's execution model, such as the stack pointer or
        !           878: frame pointer, will produce disastrous results.
        !           879: 
        !           880: A different sort of disaster will result from the use of this
        !           881: flag for a register in which function values may be returned.
        !           882: @end table
        !           883: 
        !           884: @item -d@var{letters}
        !           885: Says to make debugging dumps at times specified by @var{letters}.
        !           886: Here are the possible letters:
        !           887: 
        !           888: @table @samp
        !           889: @item r
        !           890: Dump after RTL generation.
        !           891: @item j
        !           892: Dump after first jump optimization.
        !           893: @item J
        !           894: Dump after last jump optimization.
        !           895: @item s
        !           896: Dump after CSE (including the jump optimization that sometimes
        !           897: follows CSE).
        !           898: @item L
        !           899: Dump after loop optimization.
        !           900: @item f
        !           901: Dump after flow analysis.
        !           902: @item c
        !           903: Dump after instruction combination.
        !           904: @item l
        !           905: Dump after local register allocation.
        !           906: @item g
        !           907: Dump after global register allocation.
        !           908: @item m
        !           909: Print statistics on memory usage, at the end of the run.
        !           910: @end table
        !           911: 
        !           912: @item -pedantic
        !           913: Issue all the warnings demanded by strict ANSI standard C; reject
        !           914: all programs that use forbidden extensions.
        !           915: 
        !           916: Valid ANSI standard C programs should compile properly with or without
        !           917: this option (though a rare few will require @samp{-ansi}).  However,
        !           918: without this option, certain GNU extensions and traditional C features
        !           919: are supported as well.  With this option, they are rejected.  There is
        !           920: no reason to @i{use} this option; it exists only to satisfy pedants.
        !           921: @end table
        !           922: 
        !           923: These options control the C preprocessor, which is run on each C source
        !           924: file before actual compilation.  If you use the @samp{-E} option, nothing
        !           925: is done except C preprocessing.  Some of these options make sense only
        !           926: together with @samp{-E} because they request preprocessor output that is
        !           927: not suitable for actual compilation.
        !           928: 
        !           929: @table @samp
        !           930: @item -C
        !           931: Tell the preprocessor not to discard comments.  Used with the
        !           932: @samp{-E} option.
        !           933: 
        !           934: @item -I@var{dir}
        !           935: Search directory @var{dir} for include files.
        !           936: 
        !           937: @item -I-
        !           938: Any directories specified with @samp{-I} options before the @samp{-I-}
        !           939: option are searched only for the case of @samp{#include "@var{file}"};
        !           940: they are not searched for @samp{#include <@var{file}>}.
        !           941: 
        !           942: If additional directories are specified with @samp{-I} options after
        !           943: the @samp{-I-}, these directories are searched for all @samp{#include}
        !           944: directives.  (Ordinarily @emph{all} @samp{-I} directories are used
        !           945: this way.)
        !           946: 
        !           947: In addition, the @samp{-I-} option inhibits the use of the current
        !           948: directory as the first search directory for @samp{#include
        !           949: "@var{file}"}.  Therefore, the current directory is searched only if
        !           950: it is requested explicitly with @samp{-I.}.  Specifying both
        !           951: @samp{-I-} and @samp{-I.} allows you to control precisely which
        !           952: directories are searched before the current one and which are searched
        !           953: after.
        !           954: 
        !           955: @item -nostdinc
        !           956: Do not search the standard system directories for header files.  Only
        !           957: the directories you have specified with @samp{-I} options (and the
        !           958: current directory, if appropriate) are searched.
        !           959: 
        !           960: Between @samp{-nostdinc} and @samp{-I-}, you can eliminate all
        !           961: directories from the search path except those you specify.
        !           962: 
        !           963: @item -M
        !           964: Tell the preprocessor to output a rule suitable for @code{make}
        !           965: describing the dependencies of each source file.  For each source
        !           966: file, the preprocessor outputs one @code{make}-rule whose target is
        !           967: the object file name for that source file and whose dependencies are
        !           968: all the files @samp{#include}d in it.  This rule may be a single line
        !           969: or may be continued with @samp{\}-newline if it is long.
        !           970: 
        !           971: @samp{-M} implies @samp{-E}.
        !           972: 
        !           973: @item -MM
        !           974: Like @samp{-M} but the output mentions only the user-header files
        !           975: included with @samp{#include "@var{file}"}.  System header files
        !           976: included with @samp{#include <@var{file}>} are omitted.
        !           977: 
        !           978: @samp{-MM} implies @samp{-E}.
        !           979: 
        !           980: @item -D@var{macro}
        !           981: Define macro @var{macro} with the empty string as its definition.
        !           982: 
        !           983: @item -D@var{macro}=@var{defn}
        !           984: Define macro @var{macro} as @var{defn}.
        !           985: 
        !           986: @item -U@var{macro}
        !           987: Undefine macro @var{macro}.
        !           988: 
        !           989: @item -T
        !           990: Support ANSI C trigraphs.  You don't want to know about this
        !           991: brain-damage.  The @samp{-ansi} option also has this effect.
        !           992: @end table
        !           993: 
        !           994: @node Installation, Trouble, Options, Top
        !           995: @chapter Installing GNU CC
        !           996: 
        !           997: Here is the procedure for installing GNU CC on a Unix system.
        !           998: @menu
        !           999: * VMS Install::   See below for installation on VMS.
        !          1000: @end menu
        !          1001: @iftex
        !          1002: (See below for VMS.)
        !          1003: @end iftex
        !          1004: 
        !          1005: @enumerate
        !          1006: @item
        !          1007: Edit @file{Makefile}.  If you are using HPUX, or any form of system V,
        !          1008: you must make a few changes described in comments at the beginning of
        !          1009: the file.
        !          1010: 
        !          1011: @item
        !          1012: On a Sequent system, go to the Berkeley universe.
        !          1013: 
        !          1014: @item
        !          1015: Choose configuration files.
        !          1016: 
        !          1017: @itemize @bullet
        !          1018: @item
        !          1019: Make a symbolic link named @file{config.h} to the top-level
        !          1020: config file for the machine you are using (@pxref{Config}).  This
        !          1021: file is responsible for defining information about the host
        !          1022: machine.  It includes @file{tm.h}.
        !          1023: 
        !          1024: The file's name should be @file{config-@var{machine}.h}, with these
        !          1025: exceptions:
        !          1026: 
        !          1027: @table @file
        !          1028: @item config-vms.h
        !          1029: for vaxen running VMS.
        !          1030: @item config-vaxv.h
        !          1031: for vaxen running system V.
        !          1032: @item config-i386v.h
        !          1033: for Intel 80386's running system V.
        !          1034: @item config-sun4.h
        !          1035: for Suns (model 2, 3 or 4) running @emph{operating system} version 4.
        !          1036: @item config-hp9k3.h
        !          1037: for the HP 9000 series 300.
        !          1038: @item config-gnx.h
        !          1039: for the ns32000 running Genix
        !          1040: @end table
        !          1041: 
        !          1042: If your system does not support symbolic links, you might want to
        !          1043: set up @file{config.h} to contain a @samp{#include} command which
        !          1044: refers to the appropriate file.
        !          1045: 
        !          1046: @item
        !          1047: Make a symbolic link named @file{tm.h} to the machine-description
        !          1048: macro file for your machine (its name should be
        !          1049: @file{tm-@var{machine}.h}).
        !          1050: 
        !          1051: If your system is a 68000, don't use the file @file{tm-m68k.h}
        !          1052: directly.  Instead, use one of these files:
        !          1053: 
        !          1054: @table @file
        !          1055: @item tm-sun3.h
        !          1056: for Sun 3 machines.
        !          1057: @item tm-sun2.h
        !          1058: for Sun 2 machines.
        !          1059: @item tm-3b1.h
        !          1060: for AT&T 3b1 (aka 7300 Unix PC).
        !          1061: @item tm-isi68.h
        !          1062: for Integrated Solutions systems.
        !          1063: @item tm-news800.h
        !          1064: for SONY News systems.
        !          1065: @item tm-hp9k320.h
        !          1066: for HPUX systems, if you are using GNU CC with the system's
        !          1067: assembler and linker.
        !          1068: @item tm-hp9k320g.h
        !          1069: for HPUX systems, if you are using the GNU assembler, linker and
        !          1070: other utilities.  Not all of the pieces of GNU software needed
        !          1071: for this mode of operation are as yet in distribution; full
        !          1072: instructions will appear here in the future.@refill
        !          1073: @end table
        !          1074: 
        !          1075: For the vax, use @file{tm-vax.h} on BSD Unix, @file{tm-vaxv.h} on
        !          1076: system V, or @file{tm-vms.h} on VMS.@refill
        !          1077: 
        !          1078: For the SPARC (Sun 4), use @file{tm-sparc.h}.
        !          1079: 
        !          1080: For the Motorola 88000, use @file{tm-m88k.h}.  The support for the
        !          1081: 88000 has a few unfinished spots because there was no way to run the
        !          1082: output.  Bugs are suspected in handling of branch-tables and in
        !          1083: the function prologue and epilogue.
        !          1084: 
        !          1085: For the 80386, don't use @file{tm-i386.h} directly.  Use
        !          1086: @file{tm-i386v.h} if the target machine is running system V,
        !          1087: @file{tm-seq386.h} for a Sequent 386 system, or @file{tm-compaq.h} for
        !          1088: a Compaq.
        !          1089: 
        !          1090: For the 32000, use @file{tm-sequent.h} if you are using a Sequent
        !          1091: machine, or @file{tm-encore.h} for an Encore machine, or
        !          1092: @file{tm-gnx.h} if you are using Genix version 3; otherwise, perhaps
        !          1093: @file{tm-ns32k.h} will work for you.
        !          1094: 
        !          1095: Note that Genix has bugs in @code{alloca} and @code{malloc}; you must
        !          1096: get the compiled versions of these from GNU Emacs and edit GNU CC's
        !          1097: @file{Makefile} to use them.
        !          1098: 
        !          1099: Note that Encore systems are supported only under BSD.
        !          1100: 
        !          1101: @item
        !          1102: Make a symbolic link named @file{md} to the machine description
        !          1103: pattern file (its name should be @file{@var{machine}.md}).
        !          1104: 
        !          1105: @item
        !          1106: Make a symbolic link named @file{aux-output.c} to the output
        !          1107: subroutine file for your machine (its name should be
        !          1108: @file{output-@var{machine}.c}).
        !          1109: @end itemize
        !          1110: 
        !          1111: @item
        !          1112: Make sure the Bison parser generator is installed.  (This is
        !          1113: unnecessary if the Bison output files @file{c-parse.tab.c} and
        !          1114: @file{cexp.c} are more recent than @file{c-parse.y} and @file{cexp.y}
        !          1115: and you do not plan to change the @samp{.y} files.)
        !          1116: 
        !          1117: Bison versions older that Sept 8, 1988 will produce incorrect output
        !          1118: for @file{c-parse.tab.c}.
        !          1119: 
        !          1120: @item
        !          1121: If you are using a Sun, make sure the environment variable
        !          1122: @code{FLOAT_OPTION} is not set.  If this option were set to
        !          1123: @code{f68881} when @file{gnulib} is compiled, the resulting code would
        !          1124: demand to be linked with a special startup file and will not link
        !          1125: properly without special pains.
        !          1126: 
        !          1127: @item
        !          1128: Build the compiler.  Just type @samp{make} in the compiler directory.
        !          1129: 
        !          1130: @item
        !          1131: Move the first-stage object files and executables into a subdirectory
        !          1132: with this command:
        !          1133: 
        !          1134: @example
        !          1135: make stage1
        !          1136: @end example
        !          1137: 
        !          1138: The files are moved into a subdirectory named @file{stage1}.
        !          1139: Once installation is complete, you may wish to delete these files
        !          1140: with @code{rm -r stage1}.
        !          1141: 
        !          1142: @item
        !          1143: Recompile the compiler with itself, with this command:
        !          1144: 
        !          1145: @example
        !          1146: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/"
        !          1147: @end example
        !          1148: 
        !          1149: On a 68000 or 68020 system lacking floating point hardware,
        !          1150: unless you have selected a @file{tm.h} file that expects by default
        !          1151: that there is no such hardware, do this instead:
        !          1152: 
        !          1153: @example
        !          1154: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -msoft-float"
        !          1155: @end example
        !          1156: 
        !          1157: @item
        !          1158: If you wish to test the compiler by compiling it with itself one more
        !          1159: time, do this:
        !          1160: 
        !          1161: @example
        !          1162: make stage2
        !          1163: make CC=stage2/gcc CFLAGS="-g -O -Bstage2/"
        !          1164: foreach file (*.o)
        !          1165: cmp $file stage2/$file
        !          1166: end
        !          1167: @end example
        !          1168: 
        !          1169: This will notify you if any of these stage 3 object files differs from
        !          1170: those of stage 2.  Any difference, no matter how innocuous, indicates
        !          1171: that the stage 2 compiler has compiled GNU CC incorrectly, and is
        !          1172: therefore a potentially serious bug which you should investigate and
        !          1173: report (@pxref{Bugs}).
        !          1174: 
        !          1175: Aside from the @samp{-B} option, the options should be the same as
        !          1176: when you made stage 2.
        !          1177: 
        !          1178: @item
        !          1179: Install the compiler driver, the compiler's passes and run-time support.
        !          1180: You can use the following command:
        !          1181: 
        !          1182: @example
        !          1183: make install
        !          1184: @end example
        !          1185: 
        !          1186: @noindent
        !          1187: This copies the files @file{cc1}, @file{cpp} and @file{gnulib} to
        !          1188: files @file{gcc-cc1}, @file{gcc-cpp} and @file{gcc-gnulib} in
        !          1189: directory @file{/usr/local/lib}, which is where the compiler driver
        !          1190: program looks for them.  It also copies the driver program @file{gcc}
        !          1191: into the directory @file{/usr/local}, so that it appears in typical
        !          1192: execution search paths.@refill
        !          1193: 
        !          1194: @strong{Warning: there is a bug in @code{alloca} in the Sun library.
        !          1195: To avoid this bug, install the binaries of GNU CC that were compiled
        !          1196: by GNU CC.  They use @code{alloca} as a built-in function and never
        !          1197: the one in the library.}
        !          1198: 
        !          1199: @strong{Warning: the GNU CPP may not work for @file{ioctl.h},
        !          1200: @file{ttychars.h} and other system header files unless the
        !          1201: @samp{-traditional} option is used.}  The bug is in the header files:
        !          1202: at least on some machines, they rely on behavior that is incompatible
        !          1203: with ANSI C.  This behavior consists of substituting for macro
        !          1204: argument names when they appear inside of character constants.  The
        !          1205: @samp{-traditional} option tells GNU CC to behave the way these
        !          1206: headers expect.
        !          1207: 
        !          1208: Because of this problem, you might prefer to configure GNU CC to use
        !          1209: the system's own C preprocessor.  To do so, make the file
        !          1210: @file{/usr/local/lib/gcc-cpp} a link to @file{/lib/cpp}.
        !          1211: 
        !          1212: Alternatively, on Sun systems and 4.3BSD at least, you can correct the
        !          1213: include files by running the shell script @file{fixincludes}.  This
        !          1214: installs modified, corrected copies of the files @file{ioctl.h},
        !          1215: @file{ttychars.h} and many others, in a special directory where only
        !          1216: GNU CC will normally look for them.
        !          1217: 
        !          1218: See the file @file{fixincludes} for a list of all the files we know to
        !          1219: require correction.
        !          1220: @end enumerate
        !          1221: 
        !          1222: If you cannot install the compiler's passes and run-time support in
        !          1223: @file{/usr/local/lib}, you can alternatively use the @samp{-B} option to
        !          1224: specify a prefix by which they may be found.  The compiler concatenates
        !          1225: the prefix with the names  @file{cpp}, @file{cc1} and @file{gnulib}.
        !          1226: Thus, you can put the files in a directory @file{/usr/foo/gcc} and
        !          1227: specify @samp{-B/usr/foo/gcc/} when you run GNU CC.
        !          1228: 
        !          1229: Also, you can specify an alternative default directory for these files
        !          1230: by setting the Make variable @code{libdir} when you make GNU CC.
        !          1231: 
        !          1232: @node VMS Install,, Installation, Installation
        !          1233: @section Installing GNU CC on VMS
        !          1234: 
        !          1235: The VMS version of GNU CC is distributed in an unusual tape format which
        !          1236: consists of several tape files.  The first is a command file; the second is
        !          1237: an executable program which reads Unix tar format; the third is another
        !          1238: command file which uses this program to read the remainder of the tape.
        !          1239: 
        !          1240: To load the tape, it suffices to mount it @samp{/foreign} and then do
        !          1241: @samp{@@mta0:} to execute the command file at the beginning of the tape.
        !          1242: 
        !          1243: The tape contains executables and object files as well as sources, so no
        !          1244: compilation is necessary unless you change the sources.  (This is a good
        !          1245: thing, since you probably don't have any other C compiler.)  If you must
        !          1246: recompile, here is how:
        !          1247: 
        !          1248: @enumerate
        !          1249: @item
        !          1250: Copy the file @file{tm-vms.h} to @file{tm.h}, @file{config-vms.h} to
        !          1251: @file{config.h}, @file{vax.md} to @file{md.} and @file{output-vax.c}
        !          1252: to @file{aux-output.c}.@refill
        !          1253: 
        !          1254: @item
        !          1255: Type @samp{@@make} to do recompile everything.
        !          1256: @end enumerate
        !          1257: 
        !          1258: To install the @samp{GCC} command so you can use the compiler easily, in
        !          1259: the same manner as you use the VMS C compiler, you must install the VMS CLD
        !          1260: file for GNU CC as follows:
        !          1261: 
        !          1262: @enumerate
        !          1263: @item
        !          1264: Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE}
        !          1265: to point to the directories where the GNU CC executables
        !          1266: (@samp{gcc-cpp}, @samp{gcc-cc1}, etc.) and the C include files are
        !          1267: kept.  This should be done with the commands:@refill
        !          1268: 
        !          1269: @example
        !          1270: $ assign /super /system disk:[gcc] gnu_cc
        !          1271: $ assign /super /system disk:[gcc.include] gnu_cc_include
        !          1272: @end example
        !          1273: 
        !          1274: @noindent
        !          1275: with the appropriate disk and directory names.  These commands can be
        !          1276: placed in your system startup file so they will be executed whenever
        !          1277: the machine is rebooted.
        !          1278: 
        !          1279: @item
        !          1280: Install the @samp{GCC} command with the command line:
        !          1281: 
        !          1282: @example
        !          1283: $ set command /table=sys$library:dcltables gnu_cc:gcc
        !          1284: @end example
        !          1285: 
        !          1286: @noindent
        !          1287: Now you can invoke the compiler with a command like @samp{gcc /verbose
        !          1288: file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in
        !          1289: Unix.
        !          1290: @end enumerate
        !          1291: 
        !          1292: @node Trouble, Incompatibilities, Installation, Top
        !          1293: @chapter Known Causes of Trouble with GNU CC.
        !          1294: 
        !          1295: Here are some of the things that have caused trouble for people installing
        !          1296: or using GNU CC.
        !          1297: 
        !          1298: @itemize @bullet
        !          1299: @item
        !          1300: On certain systems, defining certain environment variables such as
        !          1301: @samp{CC} can interfere with the functioning of @code{make}.
        !          1302: 
        !          1303: @item
        !          1304: Cross compilation can run into trouble for certain machines because
        !          1305: some target machines' assemblers require floating point numbers to be
        !          1306: written as @emph{integer} constants in certain contexts.
        !          1307: 
        !          1308: The compiler writes these integer constants by examining the floating
        !          1309: point value as an integer and printing that integer, because this is
        !          1310: simple to write and independent of the details of the floating point
        !          1311: representation.  But this does not work if the compiler is running on
        !          1312: a different machine with an incompatible floating point format, or
        !          1313: even a different byte-ordering.
        !          1314: 
        !          1315: It is possible to fix this by writing machine-independent code which
        !          1316: understands the floating point representation of the target machine.
        !          1317: I am not interested in doing that much work to compensate for bugs
        !          1318: in assemblers.
        !          1319: 
        !          1320: @item
        !          1321: DBX rejects some files produced by GNU CC, though it accepts similar
        !          1322: constructs in output from PCC.  Until someone can supply a coherent
        !          1323: description of what is valid DBX input and what is not, there is
        !          1324: nothing I can do about these problems.  You are on your own.
        !          1325: @end itemize
        !          1326: 
        !          1327: @node Incompatibilities, Extensions, Trouble, Top
        !          1328: @chapter Incompatibilities of GNU CC
        !          1329: 
        !          1330: There are several noteworthy incompatibilities between GNU C and most
        !          1331: existing (non-ANSI) versions of C.
        !          1332: 
        !          1333: Ultimately our intention is that the @samp{-traditional} option will
        !          1334: eliminate most of these incompatibilities by telling GNU C to behave
        !          1335: like the other C compilers.
        !          1336: 
        !          1337: @itemize @bullet
        !          1338: @item
        !          1339: GNU CC normally makes string constants read-only.  If several
        !          1340: identical-looking string constants are used, GNU CC stores only one
        !          1341: copy of the string.
        !          1342: 
        !          1343: One consequence is that you cannot call @code{mktemp} with a string
        !          1344: constant argument.  The function @code{mktemp} always alters the
        !          1345: string its argument points to.
        !          1346: 
        !          1347: Another consequence is that @code{sscanf} does not work on some
        !          1348: systems when passed a string constant as its format control string.
        !          1349: This is because @code{sscanf} incorrectly tries to write into the
        !          1350: string constant.
        !          1351: 
        !          1352: The best solution to these problems is to change the program to use
        !          1353: @code{char}-array variables with initialization strings for these
        !          1354: purposes instead of string constants.  But if this is not possible,
        !          1355: you can use the @samp{-fwritable-strings} flag, which directs GNU CC
        !          1356: to handle string constants the same way most C compilers do.
        !          1357: 
        !          1358: @item
        !          1359: GNU CC does not substitute macro arguments when they appear inside of
        !          1360: string constants.  For example, the following macro in GNU CC
        !          1361: 
        !          1362: @example
        !          1363: #define foo(a) "a"
        !          1364: @end example
        !          1365: 
        !          1366: @noindent
        !          1367: will produce output @samp{"a"} regardless of what the argument @var{a} is.
        !          1368: 
        !          1369: The @samp{-traditional} option directs GNU CC to handle such cases
        !          1370: (among others) in the old-fashioned (non-ANSI) fashion.
        !          1371: 
        !          1372: @item
        !          1373: When you use @code{setjmp} and @code{longjmp}, the only automatic
        !          1374: variables guaranteed to remain valid are those declared
        !          1375: @code{volatile}.  This is a consequence of automatic register
        !          1376: allocation.  Consider this function:
        !          1377: 
        !          1378: @example
        !          1379: jmp_buf j;
        !          1380: 
        !          1381: foo ()
        !          1382: @{
        !          1383:   int a, b;
        !          1384: 
        !          1385:   a = fun1 ();
        !          1386:   if (setjmp (j))
        !          1387:     return a;
        !          1388: 
        !          1389:   a = fun2 ();
        !          1390:   /* @r{@code{longjmp (j)} may be occur in @code{fun3}.} */
        !          1391:   return a + fun3 ();
        !          1392: @}
        !          1393: @end example
        !          1394: 
        !          1395: Here @code{a} may or may not be restored to its first value when the
        !          1396: @code{longjmp} occurs.  If @code{a} is allocated in a register, then
        !          1397: its first value is restored; otherwise, it keeps the last value stored
        !          1398: in it.
        !          1399: 
        !          1400: If you use the @samp{-W} option with the @samp{-O} option, you will
        !          1401: get a warning when GNU CC thinks such a problem might be possible.
        !          1402: 
        !          1403: @item
        !          1404: Declarations of external variables and functions within a block apply
        !          1405: only to the block containing the declaration.  In other words, they
        !          1406: have the same scope as any other declaration in the same place.
        !          1407: 
        !          1408: In some other C compilers, a @code{extern} declaration affects all the
        !          1409: rest of the file even if it happens within a block.
        !          1410: 
        !          1411: The @samp{-traditional} option directs GNU C to treat all @code{extern}
        !          1412: declarations as global, like traditional compilers.
        !          1413: 
        !          1414: @item
        !          1415: In traditional C, you can combine @code{long}, etc., with a typedef name,
        !          1416: as shown here:
        !          1417: 
        !          1418: @example
        !          1419: typedef int foo;
        !          1420: typedef long foo bar;
        !          1421: @end example
        !          1422: 
        !          1423: In ANSI C, this is not allowed: @code{long} and other type modifiers
        !          1424: require an explicit @code{int}.  Because this criterion is expressed
        !          1425: by Bison grammar rules rather than C code, the @samp{-traditional}
        !          1426: flag cannot alter it.
        !          1427: 
        !          1428: @item
        !          1429: PCC allows typedef names to be used as function parameters.  The
        !          1430: difficulty described immediately above applies here too.
        !          1431: 
        !          1432: @item
        !          1433: PCC allows whitespace in the middle of compound assignment operators
        !          1434: such as @samp{+=}.  GNU CC, following the ANSI standard, does not
        !          1435: allow this.  The difficulty described immediately above applies here
        !          1436: too.
        !          1437: 
        !          1438: @item
        !          1439: GNU CC will flag unterminated character constants inside of preprocessor
        !          1440: conditionals that fail.  Some programs have English comments enclosed in
        !          1441: conditionals that are guaranteed to fail; if these comments contain
        !          1442: apostrophes, GNU CC will probably report an error.  For example,
        !          1443: this code would produce an error:
        !          1444: 
        !          1445: @example
        !          1446: #if 0
        !          1447: You can't expect this to work.
        !          1448: #endif
        !          1449: @end example
        !          1450: 
        !          1451: The best solution to such a problem is to put the text into an actual
        !          1452: C comment delimited by @samp{/*@dots{}*/}.  However,
        !          1453: @samp{-traditional} suppresses these error messages.
        !          1454: 
        !          1455: @item
        !          1456: When compiling functions that return @code{float}, PCC converts it to
        !          1457: a double.  GNU CC actually returns a @code{float}.  If you are concerned
        !          1458: with PCC compatibility, you should declare your functions to return
        !          1459: @code{double}; you might as well say what you mean.
        !          1460: 
        !          1461: @item
        !          1462: When compiling functions that return structures or unions, GNU CC
        !          1463: output code uses a method different from that used on most versions of
        !          1464: Unix.  As a result, code compiled with GNU CC cannot call a
        !          1465: structure-returning function compiled with PCC, and vice versa.
        !          1466: 
        !          1467: The method used by GCC is as follows: a structure or union which is 1,
        !          1468: 2, 4 or 8 bytes long is returned like a scalar.  A structure or union
        !          1469: with any other size is stored into an address supplied by the caller
        !          1470: in a special, fixed register.
        !          1471: 
        !          1472: PCC usually handles all sizes of structures and unions by returning
        !          1473: the address of a block of static storage containing the value.  This
        !          1474: method is not used in GCC because it is slower and nonreentrant.
        !          1475: 
        !          1476: On systems where PCC works this way, you may be able to make GCC-compiled
        !          1477: code call such functions that were compiled with PCC by declaring them
        !          1478: to return a pointer to the structure or union instead of the structure
        !          1479: or union itself.  For example, instead of this:
        !          1480: 
        !          1481: @example
        !          1482: struct foo nextfoo ();
        !          1483: @end example
        !          1484: 
        !          1485: @noindent
        !          1486: write this:
        !          1487: 
        !          1488: @example
        !          1489: struct foo *nextfoo ();
        !          1490: #define nextfoo *nextfoo
        !          1491: @end example
        !          1492: 
        !          1493: @noindent
        !          1494: (Note that this assumes you are using the GNU preprocessor and not
        !          1495: @samp{-traditional}, so that the ANSI antirecursion rules for macro
        !          1496: expansions are effective.)
        !          1497: @end itemize
        !          1498: 
        !          1499: @node Extensions, Bugs, Incompatibilities, Top
        !          1500: @chapter GNU Extensions to the C Language
        !          1501: 
        !          1502: GNU C provides several language features not found in ANSI standard C.
        !          1503: (The @samp{-pedantic} option directs GNU CC to print a warning message if
        !          1504: any of these features is used.)  To test for the availability of these
        !          1505: features in conditional compilation, check for a predefined macro
        !          1506: @code{__GNUC__}, which is always defined under GNU CC.
        !          1507: 
        !          1508: @menu
        !          1509: * Statement Exprs::     Putting statements and declarations inside expressions.
        !          1510: * Naming Types::        Giving a name to the type of some expression.
        !          1511: * Typeof::             @code{typeof}: referring to the type of an expression.
        !          1512: * Lvalues::            Using @samp{?:}, @samp{,} and casts in lvalues.
        !          1513: * Conditionals::       Omitting the middle operand of a @samp{?:} expression.
        !          1514: * Zero-Length::                Zero-length arrays.
        !          1515: * Variable-Length::    Arrays whose length is computed at run time.
        !          1516: * Subscripting::       Any array can be subscripted, even if not an lvalue.
        !          1517: * Pointer Arith::      Arithmetic on @code{void}-pointers and function pointers.
        !          1518: * Constructors::       Constructor expressions give structures, unions
        !          1519:                         or arrays as values.
        !          1520: * Dollar Signs::        Dollar sign is allowed in identifiers.
        !          1521: * Alignment::           Inquiring about the alignment of a type or variable.
        !          1522: * Inline::              Defining inline functions (as fast as macros).
        !          1523: * Extended Asm::       Assembler instructions with C expressions as operands.
        !          1524:                         (With them you can define ``built-in'' functions.)
        !          1525: * Asm Labels::         Specifying the assembler name to use for a C symbol.
        !          1526: @end menu
        !          1527: 
        !          1528: @node Statement Exprs, Naming Types, Extensions, Extensions
        !          1529: @section Statements and Declarations inside of Expressions
        !          1530: 
        !          1531: A compound statement in parentheses may appear inside an expression in GNU
        !          1532: C.  This allows you to declare variables within an expression.  For
        !          1533: example:
        !          1534: 
        !          1535: @example
        !          1536: (@{ int y = foo (); int z;
        !          1537:    if (y > 0) z = y;
        !          1538:    else z = - y;
        !          1539:    z; @})
        !          1540: @end example
        !          1541: 
        !          1542: @noindent
        !          1543: is a valid (though slightly more complex than necessary) expression
        !          1544: for the absolute value of @code{foo ()}.
        !          1545: 
        !          1546: This feature is especially useful in making macro definitions ``safe'' (so
        !          1547: that they evaluate each operand exactly once).  For example, the
        !          1548: ``maximum'' function is commonly defined as a macro in standard C as
        !          1549: follows:
        !          1550: 
        !          1551: @example
        !          1552: #define max(a,b) ((a) > (b) ? (a) : (b))
        !          1553: @end example
        !          1554: 
        !          1555: @noindent
        !          1556: But this definition computes either @var{a} or @var{b} twice, with bad
        !          1557: results if the operand has side effects.  In GNU C, if you know the
        !          1558: type of the operands (here let's assume @code{int}), you can define
        !          1559: the macro safely as follows:
        !          1560: 
        !          1561: @example
        !          1562: #define maxint(a,b) \
        !          1563:   (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
        !          1564: @end example
        !          1565: 
        !          1566: Embedded statements are not allowed in constant expressions, such as
        !          1567: the value of an enumeration constant, the width of a bit field, or
        !          1568: the initial value of a static variable.
        !          1569: 
        !          1570: If you don't know the type of the operand, you can still do this, but you
        !          1571: must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming
        !          1572: Types}).
        !          1573: 
        !          1574: @node Naming Types, Typeof, Statement Exprs, Extensions
        !          1575: @section Naming an Expression's Type
        !          1576: 
        !          1577: You can give a name to the type of an expression using a @code{typedef}
        !          1578: declaration with an initializer.  Here is how to define @var{name} as a
        !          1579: type name for the type of @var{exp}:
        !          1580: 
        !          1581: @example
        !          1582: typedef @var{name} = @var{exp};
        !          1583: @end example
        !          1584: 
        !          1585: This is useful in conjunction with the statements-within-expressions
        !          1586: feature.  Here is how the two together can be used to define a safe
        !          1587: ``maximum'' macro that operates on any arithmetic type:
        !          1588: 
        !          1589: @example
        !          1590: #define max(a,b) \
        !          1591:   (@{typedef _ta = (a), _tb = (b);  \
        !          1592:     _ta _a = (a); _tb _b = (b);     \
        !          1593:     _a > _b ? _a : _b; @})
        !          1594: @end example
        !          1595: 
        !          1596: The reason for using names that start with underscores for the local
        !          1597: variables is to avoid conflicts with variable names that occur within the
        !          1598: expressions that are substituted for @code{a} and @code{b}.  Eventually we
        !          1599: hope to design a new form of declaration syntax that allows you to declare
        !          1600: variables whose scopes start only after their initializers; this will be a
        !          1601: more reliable way to prevent such conflicts.
        !          1602: 
        !          1603: @node Typeof, Lvalues, Naming Types, Extensions
        !          1604: @section Referring to a Type with @code{typeof}
        !          1605: 
        !          1606: Another way to refer to the type of an expression is with @code{typeof}.
        !          1607: The syntax of using of this keyword looks like @code{sizeof}, but the
        !          1608: construct acts semantically like a type name defined with @code{typedef}.
        !          1609: 
        !          1610: There are two ways of writing the argument to @code{typeof}: with an
        !          1611: expression or with a type.  Here is an example with an expression:
        !          1612: 
        !          1613: @example
        !          1614: typeof (x[0](1))
        !          1615: @end example
        !          1616: 
        !          1617: @noindent
        !          1618: This assumes that @code{x} is an array of functions; the type described
        !          1619: is that of the values of the functions.
        !          1620: 
        !          1621: Here is an example with a typename as the argument:
        !          1622: 
        !          1623: @example
        !          1624: typeof (int *)
        !          1625: @end example
        !          1626: 
        !          1627: @noindent
        !          1628: Here the type described is that of pointers to @code{int}.
        !          1629: 
        !          1630: A @code{typeof}-construct can be used anywhere a typedef name could be
        !          1631: used.  For example, you can use it in a declaration, in a cast, or inside
        !          1632: of @code{sizeof} or @code{typeof}.
        !          1633: 
        !          1634: @itemize @bullet
        !          1635: @item
        !          1636: This declares @code{y} with the type of what @code{x} points to.
        !          1637: 
        !          1638: @example
        !          1639: typeof (*x) y;
        !          1640: @end example
        !          1641: 
        !          1642: @item
        !          1643: This declares @code{y} as an array of such values.
        !          1644: 
        !          1645: @example
        !          1646: typeof (*x) y[4];
        !          1647: @end example
        !          1648: 
        !          1649: @item
        !          1650: This declares @code{y} as an array of pointers to characters:
        !          1651: 
        !          1652: @example
        !          1653: typeof (typeof (char *)[4]) y;
        !          1654: @end example
        !          1655: 
        !          1656: @noindent
        !          1657: It is equivalent to the following traditional C declaration:
        !          1658: 
        !          1659: @example
        !          1660: char *y[4];
        !          1661: @end example
        !          1662: 
        !          1663: To see the meaning of the declaration using @code{typeof}, and why it
        !          1664: might be a useful way to write, let's rewrite it with these macros:
        !          1665: 
        !          1666: @example
        !          1667: #define pointer(T)  typeof(T *)
        !          1668: #define array(T, N) typeof(T [N])
        !          1669: @end example
        !          1670: 
        !          1671: @noindent
        !          1672: Now the declaration can be rewritten this way:
        !          1673: 
        !          1674: @example
        !          1675: array (pointer (char), 4) y;
        !          1676: @end example
        !          1677: 
        !          1678: @noindent
        !          1679: Thus, @samp{array (pointer (char), 4)} is the type of arrays of 4
        !          1680: pointers to @code{char}.
        !          1681: @end itemize
        !          1682: 
        !          1683: @node Lvalues, Conditionals, Typeof, Extensions
        !          1684: @section Generalized Lvalues
        !          1685: 
        !          1686: Compound expressions, conditional expressions and casts are allowed as
        !          1687: lvalues provided their operands are lvalues.  This means that you can take
        !          1688: their addresses or store values into them.
        !          1689: 
        !          1690: For example, a compound expression can be assigned, provided the last
        !          1691: expression in the sequence is an lvalue.  These two expressions are
        !          1692: equivalent:
        !          1693: 
        !          1694: @example
        !          1695: (a, b) += 5
        !          1696: a, (b += 5)
        !          1697: @end example
        !          1698: 
        !          1699: Similarly, the address of the compound expression can be taken.  These two
        !          1700: expressions are equivalent:
        !          1701: 
        !          1702: @example
        !          1703: &(a, b)
        !          1704: a, &b
        !          1705: @end example
        !          1706: 
        !          1707: A conditional expression is a valid lvalue if its type is not void and the
        !          1708: true and false branches are both valid lvalues.  For example, these two
        !          1709: expressions are equivalent:
        !          1710: 
        !          1711: @example
        !          1712: (a ? b : c) = 5
        !          1713: (a ? b = 5 : (c = 5))
        !          1714: @end example
        !          1715: 
        !          1716: A cast is a valid lvalue if its operand is valid.  Taking the address of
        !          1717: the cast is the same as taking the address without a cast, except for the
        !          1718: type of the result.  For example, these two expressions are equivalent (but
        !          1719: the second may be valid when the type of @samp{a} does not permit a cast to
        !          1720: @samp{int *}).
        !          1721: 
        !          1722: @example
        !          1723: &(int *)a
        !          1724: (int **)&a
        !          1725: @end example
        !          1726: 
        !          1727: A simple assignment whose left-hand side is a cast works by converting the
        !          1728: right-hand side first to the specified type, then to the type of the inner
        !          1729: left-hand side expression.  After this is stored, the value is converter
        !          1730: back to the specified type to become the value of the assignment.  Thus, if
        !          1731: @samp{a} has type @samp{char *}, the following two expressions are
        !          1732: equivalent:
        !          1733: 
        !          1734: @example
        !          1735: (int)a = 5
        !          1736: (int)(a = (char *)5)
        !          1737: @end example
        !          1738: 
        !          1739: An assignment-with-arithmetic operation such as @samp{+=} applied to a cast
        !          1740: performs the arithmetic using the type resulting from the cast, and then
        !          1741: continues as in the previous case.  Therefore, these two expressions are
        !          1742: equivalent:
        !          1743: 
        !          1744: @example
        !          1745: (int)a += 5
        !          1746: (int)(a = (char *) ((int)a + 5))
        !          1747: @end example
        !          1748: 
        !          1749: @node Conditionals, Zero-Length, Lvalues, Extensions
        !          1750: @section Conditional Expressions with Omitted Middle-Operands
        !          1751: 
        !          1752: The middle operand in a conditional expression may be omitted.  Then
        !          1753: if the first operand is nonzero, its value is the value of the conditional
        !          1754: expression.
        !          1755: 
        !          1756: Therefore, the expression
        !          1757: 
        !          1758: @example
        !          1759: x ? : y
        !          1760: @end example
        !          1761: 
        !          1762: @noindent
        !          1763: has the value of @code{x} if that is nonzero; otherwise, the value of
        !          1764: @code{y}.
        !          1765: 
        !          1766: This example is perfectly equivalent to
        !          1767: 
        !          1768: @example
        !          1769: x ? x : y
        !          1770: @end example
        !          1771: 
        !          1772: @noindent
        !          1773: In this simple case, the ability to omit the middle operand is not
        !          1774: especially useful.  When it becomes useful is when the first operand does,
        !          1775: or may (if it is a macro argument), contain a side effect.  Then repeating
        !          1776: the operand in the middle would perform the side effect twice.  Omitting
        !          1777: the middle operand uses the value already computed without the undesirable
        !          1778: effects of recomputing it.
        !          1779: 
        !          1780: @node Zero-Length, Variable-Length, Conditionals, Extensions
        !          1781: @section Arrays of Length Zero
        !          1782: 
        !          1783: Zero-length arrays are allowed in GNU C.  They are very useful as the last
        !          1784: element of a structure which is really a header for a variable-length
        !          1785: object:
        !          1786: 
        !          1787: @example
        !          1788: struct line @{
        !          1789:   int length;
        !          1790:   char contents[0];
        !          1791: @};
        !          1792: 
        !          1793: @{
        !          1794:   struct line *thisline 
        !          1795:     = (struct line *) malloc (sizeof (struct line) + this_length);
        !          1796:   thisline->length = this_length;
        !          1797: @}
        !          1798: @end example
        !          1799: 
        !          1800: In standard C, you would have to give @code{contents} a length of 1, which
        !          1801: means either you waste space or complicate the argument to @code{malloc}.
        !          1802: 
        !          1803: @node Variable-Length, Subscripting, Zero-Length, Extensions
        !          1804: @section Arrays of Variable Length
        !          1805: 
        !          1806: Variable-length automatic arrays are allowed in GNU C.  These arrays are
        !          1807: declared like any other automatic arrays, but with a length that is not a
        !          1808: constant expression.  The storage is allocated at that time and
        !          1809: deallocated when the brace-level is exited.  For example:
        !          1810: 
        !          1811: @example
        !          1812: FILE *concat_fopen (char *s1, char *s2, char *mode)
        !          1813: @{
        !          1814:   char str[strlen (s1) + strlen (s2) + 1];
        !          1815:   strcpy (str, s1);
        !          1816:   strcat (str, s2);
        !          1817:   return fopen (str, mode);
        !          1818: @}
        !          1819: @end example
        !          1820: 
        !          1821: You can also define structure types containing variable-length arrays, and
        !          1822: use them even for arguments or function values, as shown here:
        !          1823: 
        !          1824: @example
        !          1825: int foo;
        !          1826: 
        !          1827: struct entry
        !          1828: @{
        !          1829:   char data[foo];
        !          1830: @};
        !          1831: 
        !          1832: struct entry
        !          1833: tester (struct entry arg)
        !          1834: @{
        !          1835:   struct entry new;
        !          1836:   int i;
        !          1837:   for (i = 0; i < foo; i++)
        !          1838:     new.data[i] = arg.data[i] + 1;
        !          1839:   return new;
        !          1840: @}
        !          1841: @end example
        !          1842: 
        !          1843: @noindent
        !          1844: (Eventually there will be a way to say that the size of the array is
        !          1845: another member of the same structure.)
        !          1846: 
        !          1847: The length of an array is computed on entry to the brace-level where the
        !          1848: array is declared and is remembered for the scope of the array in case you
        !          1849: access it with @code{sizeof}.
        !          1850: 
        !          1851: Jumping or breaking out of the scope of the array name will also deallocate
        !          1852: the storage.  Jumping into the scope is not allowed; you will get an error
        !          1853: message for it.
        !          1854: 
        !          1855: You can use the function @code{alloca} to get an effect much like
        !          1856: variable-length arrays.  The function @code{alloca} is available in
        !          1857: many other C implementations (but not in all).  On the other hand,
        !          1858: variable-length arrays are more elegant.
        !          1859: 
        !          1860: There are other differences between these two methods.  Space allocated
        !          1861: with @code{alloca} exists until the containing @emph{function} returns.
        !          1862: The space for a variable-length array is deallocated as soon as the array
        !          1863: name's scope ends.  (If you use both variable-length arrays and
        !          1864: @code{alloca} in the same function, deallocation of a variable-length array
        !          1865: will also deallocate anything more recently allocated with @code{alloca}.)
        !          1866: 
        !          1867: @node Subscripting, Pointer Arith, Variable-Length, Extensions
        !          1868: @section Non-Lvalue Arrays May Have Subscripts
        !          1869: 
        !          1870: Subscripting is allowed on arrays that are not lvalues, even though the
        !          1871: unary @samp{&} operator is not.  For example, this is valid in GNU C though
        !          1872: not valid in other C dialects:
        !          1873: 
        !          1874: @example
        !          1875: struct foo @{int a[4];@};
        !          1876: 
        !          1877: struct foo f();
        !          1878: 
        !          1879: bar (int index)
        !          1880: @{
        !          1881:   return f().a[index];
        !          1882: @}
        !          1883: @end example
        !          1884: 
        !          1885: @node Pointer Arith, Initializers, Subscripting, Extensions
        !          1886: @section Arithmetic on @code{void}-Pointers and Function Pointers
        !          1887: 
        !          1888: In GNU C, addition and subtraction operations are supported on pointers to
        !          1889: @code{void} and on pointers to functions.  This is done by treating the
        !          1890: size of a @code{void} or of a function as 1.
        !          1891: 
        !          1892: A consequence of this is that @code{sizeof} is also allowed on @code{void}
        !          1893: and on function types, and returns 1.
        !          1894: 
        !          1895: @node Initializers, Constructors, Pointer Arith, Extensions
        !          1896: @section Non-Constant Initializers
        !          1897: 
        !          1898: The elements of an aggregate initializer are not required to be constant
        !          1899: expressions in GNU C.  Here is an example of an initializer with run-time
        !          1900: varying elements:
        !          1901: 
        !          1902: @example
        !          1903: foo (float f, float g)
        !          1904: @{
        !          1905:   float beat_freqs[2] = @{ f-g, f+g @};
        !          1906:   @dots{}
        !          1907: @}
        !          1908: @end example
        !          1909: 
        !          1910: @node Constructors, Dollar Signs, Initializers, Extensions
        !          1911: @section Constructor Expressions
        !          1912: 
        !          1913: GNU C supports constructor expressions.  A constructor looks like a cast
        !          1914: containing an initializer.  Its value is an object of the type specified in
        !          1915: the cast, containing the elements specified in the initializer.  The type
        !          1916: must be a structure, union or array type.
        !          1917: 
        !          1918: Assume that @code{struct foo} and @code{structure} are declared as shown:
        !          1919: 
        !          1920: @example
        !          1921: struct foo @{int a; char b[2];@} structure;
        !          1922: @end example
        !          1923: 
        !          1924: @noindent
        !          1925: Here is an example of constructing a @samp{struct foo} with a constructor:
        !          1926: 
        !          1927: @example
        !          1928: structure = ((struct foo) @{x + y, 'a', 0@});
        !          1929: @end example
        !          1930: 
        !          1931: @noindent
        !          1932: This is equivalent to writing the following:
        !          1933: 
        !          1934: @example
        !          1935: @{
        !          1936:   struct foo temp = @{x + y, 'a', 0@};
        !          1937:   structure = temp;
        !          1938: @}
        !          1939: @end example
        !          1940: 
        !          1941: You can also construct an array.  If all the elements of the constructor
        !          1942: are (made up of) simple constant expressions, suitable for use in
        !          1943: initializers, then the constructor is an lvalue and can be coerced to a
        !          1944: pointer to its first element, as shown here:
        !          1945: 
        !          1946: @example
        !          1947: char **foo = (char *[]) @{ "x", "y", "z" @};
        !          1948: @end example
        !          1949: 
        !          1950: Array constructors whose elements are not simple constants are not very
        !          1951: useful, because the constructor is not an lvalue.  There are only two valid
        !          1952: ways to use it: to subscript it, or initialize an array variable with it.
        !          1953: The former is probably slower than a @code{switch} statement, while the
        !          1954: latter does the same thing an ordinary C initializer would do.
        !          1955: 
        !          1956: @example
        !          1957: output = ((int[]) @{ 2, x, 28 @}) [input];
        !          1958: @end example
        !          1959: 
        !          1960: @node Dollar Signs, Alignment, Constructors, Extensions
        !          1961: @section Dollar Signs in Identifier Names
        !          1962: 
        !          1963: In GNU C, you may use dollar signs in identifier names.  This is because
        !          1964: many traditional C implementations allow such identifiers.
        !          1965: 
        !          1966: @node Alignment, Inline, Dollar Signs, Extensions
        !          1967: @section Inquiring about the Alignment of a Type or Variable
        !          1968: 
        !          1969: The keyword @code{__alignof} allows you to inquire about how an object
        !          1970: is aligned, or the minimum alignment usually required by a type.  Its
        !          1971: syntax is just like @code{sizeof}.
        !          1972: 
        !          1973: For example, if the target machine requires a @code{double} value to be
        !          1974: aligned on an 8-byte boundary, then @code{__alignof (double)} is 8.  This
        !          1975: is true on many RISC machines.  On more traditional machine designs,
        !          1976: @code{__alignof (double)} is 4 or even 2.
        !          1977: 
        !          1978: Some machines never actually require alignment; they allow reference to any
        !          1979: data type even at an odd addresses.  For these machines, @code{__alignof}
        !          1980: reports the @emph{recommended} alignment of a type.
        !          1981: 
        !          1982: When the operand of @code{__alignof} is an lvalue rather than a type, the
        !          1983: value is the largest alignment that the lvalue is known to have.  It may
        !          1984: have this alignment as a result of its data type, or because it is part of
        !          1985: a structure and inherits alignment from that structure. For example, after
        !          1986: this declaration:
        !          1987: 
        !          1988: @example
        !          1989: struct foo @{ int x; char y; @} foo1;
        !          1990: @end example
        !          1991: 
        !          1992: @noindent
        !          1993: the value of @code{__alignof (foo1.y)} is probably 2 or 4, the same as
        !          1994: @code{__alignof (int)}, even though the data type of @code{foo1.y} does not
        !          1995: itself demand any alignment.@refill
        !          1996: 
        !          1997: @node Inline, Extended Asm, Alignment, Extensions
        !          1998: @section An Inline Function is As Fast As a Macro
        !          1999: 
        !          2000: By declaring a function @code{inline}, you can direct GNU CC to integrate
        !          2001: that function's code into the code for its callers.  This makes execution
        !          2002: faster by eliminating the function-call overhead; in addition, if any of
        !          2003: the actual argument values are constant, their known values may permit
        !          2004: simplifications at compile time so that not all of the inline function's
        !          2005: code needs to be included.
        !          2006: 
        !          2007: To declare a function inline, use the @code{inline} keyword in its
        !          2008: declaration, like this:
        !          2009: 
        !          2010: @example
        !          2011: inline int
        !          2012: inc (int *a)
        !          2013: @{
        !          2014:   (*a)++;
        !          2015: @}
        !          2016: @end example
        !          2017: 
        !          2018: You can also make all ``simple enough'' functions inline with the
        !          2019: option @samp{-finline-functions}.  Note that certain usages in a
        !          2020: function definition can make it unsuitable for inline substitution.
        !          2021: 
        !          2022: When a function is both inline and @code{static}, if all calls to the
        !          2023: function are integrated into the caller, then the function's own assembler
        !          2024: code is never referenced.  In this case, GNU CC does not actually output
        !          2025: assembler code for the function, unless you specify the option
        !          2026: @samp{-fkeep-inline-functions}.  Some calls cannot be integrated for
        !          2027: various reasons (in particular, calls that precede the function's
        !          2028: definition cannot be integrated, and neither can recursive calls within the
        !          2029: definition).  If there is a nonintegrated call, then the function is
        !          2030: compiled to assembler code as usual.
        !          2031: 
        !          2032: When an inline function is not @code{static}, then the compiler must assume
        !          2033: that there may be calls from other source files; since a global symbol can
        !          2034: be defined only once in any program, the function must not be defined in
        !          2035: the other source files, so the calls therein cannot be integrated.
        !          2036: Therefore, a non-@code{static} inline function is always compiled on its
        !          2037: own in the usual fashion.
        !          2038: 
        !          2039: @node Extended Asm, Asm Labels, Inline, Extensions
        !          2040: @section Assembler Instructions with C Expression Operands
        !          2041: 
        !          2042: In an assembler instruction using @code{asm}, you can now specify the
        !          2043: operands of the instruction using C expressions.  This means no more
        !          2044: guessing which registers or memory locations will contain the data you want
        !          2045: to use.
        !          2046: 
        !          2047: You must specify an assembler instruction template much like what appears
        !          2048: in a machine description, plus an operand constraint string for each
        !          2049: operand.
        !          2050: 
        !          2051: For example, here is how to use the 68881's @code{fsinx} instruction:
        !          2052: 
        !          2053: @example
        !          2054: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
        !          2055: @end example
        !          2056: 
        !          2057: @noindent
        !          2058: Here @code{angle} is the C expression for the input operand while
        !          2059: @code{result} is that of the output operand.  Each has @samp{"f"} as its
        !          2060: operand constraint, saying that a floating-point register is required.  The
        !          2061: constraints use the same language used in the machine description
        !          2062: (@pxref{Constraints}).
        !          2063: 
        !          2064: Each operand is described by an operand-constraint string followed by the C
        !          2065: expression in parentheses.  A colon separates the assembler template from
        !          2066: the first output operand, and another separates the last output operand
        !          2067: from the first input, if any.  Commas separate output operands and separate
        !          2068: inputs.  The number of operands is limited to the maximum number of
        !          2069: operands in any instruction pattern in the machine description.
        !          2070: 
        !          2071: Output operand expressions must be lvalues; the compiler can check this.
        !          2072: The input operands need not be lvalues.  The compiler cannot check whether
        !          2073: the operands have data types that are reasonable for the instruction being
        !          2074: executed.  It does not parse the assembler instruction template and does
        !          2075: not know what it means, or whether it is valid assembler input.  The
        !          2076: extended @code{asm} feature is most often used for machine instructions
        !          2077: that the compiler itself does not know exist.
        !          2078: 
        !          2079: If there are no output operands, and there are input operands, then you
        !          2080: should write two colons in a row where the output operands would go.
        !          2081: 
        !          2082: The output operands must be write-only; GNU CC will assume that the values
        !          2083: in these operands before the instruction are dead and need not be
        !          2084: generated.  For an operand that is read-write, or in which not all bits are
        !          2085: written and the other bits contain useful information, you must logically
        !          2086: split its function into two separate operands, one input operand and one
        !          2087: write-only output operand.  The connection between them is expressed by
        !          2088: constraints which say they need to be in the same location when the
        !          2089: instruction executes.  You can use the same C expression for both operands,
        !          2090: or different expressions.  For example, here we write the (fictitious)
        !          2091: @samp{combine} instruction with @code{bar} as its read-only source operand
        !          2092: and @code{foo} as its read-write destination:
        !          2093: 
        !          2094: @example
        !          2095: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
        !          2096: @end example
        !          2097: 
        !          2098: @noindent
        !          2099: The constraint @samp{"0"} for operand 1 says that it must occupy the same
        !          2100: location as operand 0.
        !          2101: 
        !          2102: Only a digit in the constraint can guarantee that one operand will be in
        !          2103: the same place as another.  The mere fact that @code{foo} is the value of
        !          2104: both operands is not enough to guarantee that they will be in the same
        !          2105: place in the generated assembler code.  The following would not work:
        !          2106: 
        !          2107: @example
        !          2108: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
        !          2109: @end example
        !          2110: 
        !          2111: Various optimizations or reloading could cause operands 0 and 1 to be in
        !          2112: different registers; GNU CC knows no reason not to do so.  For example, the
        !          2113: compiler might find a copy of the value of @code{foo} in one register and
        !          2114: use it for operand 1, but generate the output operand 0 in a different
        !          2115: register (copying it afterward to @code{foo}'s own address).  Of course,
        !          2116: since the register for operand 1 is not even mentioned in the assembler
        !          2117: code, the result will not work, but GNU CC can't tell that.
        !          2118: 
        !          2119: Unless an output operand has the @samp{&} constraint modifier, GNU CC may
        !          2120: allocate it in the same register as an unrelated input operand, on the
        !          2121: assumption that the inputs are consumed before the outputs are produced.
        !          2122: This assumption may be false if the assembler code actually consists of
        !          2123: more than one instruction.  In such a case, use @samp{&} for each output
        !          2124: operand that may not overlap an input.  @xref{Modifiers}.
        !          2125: 
        !          2126: Some instructions clobber specific hard registers.  To describe this,
        !          2127: write a third colon after the input operands, followed by the names of
        !          2128: the clobbered hard registers (given as strings).  For example, on the vax,
        !          2129: 
        !          2130: @example
        !          2131: asm volatile ("movc3 %0,%1,%2"
        !          2132:               : /* no outputs */
        !          2133:               : "g" (from), "g" (to), "g" (count)
        !          2134:               : "r0", "r1", "r2", "r3", "r4", "r5");
        !          2135: @end example
        !          2136: 
        !          2137: Usually the most convenient way to use these @code{asm} instructions is to
        !          2138: encapsulate them in macros that look like functions.  For example,
        !          2139: 
        !          2140: @example
        !          2141: #define sin(x)       \
        !          2142: (@{ double __value, __arg = (x);   \
        !          2143:    asm ("fsinx %1,%0": "=f" (__value): "f" (__arg));  \
        !          2144:    __value; @})
        !          2145: @end example
        !          2146: 
        !          2147: @noindent
        !          2148: Here the variable @code{__arg} is used to make sure that the instruction
        !          2149: operates on a proper @code{double} value, and to accept only those
        !          2150: arguments @code{x} which can convert automatically to a @code{double}.
        !          2151: 
        !          2152: Another way to make sure the instruction operates on the correct data type
        !          2153: is to use a cast in the @code{asm}.  This is different from using a
        !          2154: variable @code{__arg} in that it converts more different types.  For
        !          2155: example, if the desired type were @code{int}, casting the argument to
        !          2156: @code{int} would accept a pointer with no complaint, while assigning the
        !          2157: argument to an @code{int} variable named @code{__arg} would warn about
        !          2158: using a pointer unless the caller explicitly casts it.
        !          2159: 
        !          2160: GNU CC assumes for optimization purposes that these instructions have no
        !          2161: side effects except to change the output operands.  This does not mean that
        !          2162: instructions with a side effect cannot be used, but you must be careful,
        !          2163: because the compiler may eliminate them if the output operands aren't used,
        !          2164: or move them out of loops, or replace two with one if they constitute a
        !          2165: common subexpression.  Also, if your instruction does have a side effect on
        !          2166: a variable that otherwise appears not to change, the old value of the
        !          2167: variable may be reused later if it happens to be found in a register.
        !          2168: 
        !          2169: You can prevent an @code{asm} instruction from being deleted, moved or
        !          2170: combined by writing the keyword @code{volatile} after the @code{asm}.  For
        !          2171: example:
        !          2172: 
        !          2173: @example
        !          2174: #define set_priority(x)  \
        !          2175: asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
        !          2176: @end example
        !          2177: 
        !          2178: It is a natural idea to look for a way to give access to the condition
        !          2179: code left by the assembler instruction.  However, when we attempted to
        !          2180: implement this, we found no way to make it work reliably.  The problem
        !          2181: is that output operands might need reloading, which would result in
        !          2182: additional following ``store'' instructions.  On most machines, these
        !          2183: instructions would alter the condition code before there was time to
        !          2184: test it.  This problem doesn't arise for ordinary ``test'' and
        !          2185: ``compare'' instructions because they don't have any output operands.
        !          2186: 
        !          2187: @node Asm Labels,,Extended Asm, Extensions
        !          2188: @section Controlling Names Used in Assembler Code
        !          2189: 
        !          2190: You can specify the name to be used in the assembler code for a C function
        !          2191: or variable by writing the @code{asm} keyword after the declarator as
        !          2192: follows:
        !          2193: 
        !          2194: @example
        !          2195: int foo asm ("myfoo") = 2;
        !          2196: @end example
        !          2197: 
        !          2198: @noindent
        !          2199: This specifies that the name to be used for the variable @code{foo} in
        !          2200: the assembler code should be @samp{myfoo} rather than the usual
        !          2201: @samp{_foo}.
        !          2202: 
        !          2203: On systems where an underscore is normally prepended to the name of a C
        !          2204: function or variable, this feature allows you to define names for the
        !          2205: linker that do not start with an underscore.
        !          2206: 
        !          2207: You cannot use @code{asm} in this way in a function @emph{definition}; but
        !          2208: you can get the same effect by writing a declaration for the function
        !          2209: before its definition and putting @code{asm} there, like this:
        !          2210: 
        !          2211: @example
        !          2212: extern func () asm ("FUNC");
        !          2213: 
        !          2214: func (x, y)
        !          2215:      int x, y;
        !          2216: @dots{}
        !          2217: @end example
        !          2218: 
        !          2219: It is up to you to make sure that the assembler names you choose do not
        !          2220: conflict with any other assembler symbols.  Also, you must not use a
        !          2221: register name; that would produce completely invalid assembler code.  GNU
        !          2222: CC does not as yet have the ability to store static variables in registers.
        !          2223: Perhaps that will be added.
        !          2224: 
        !          2225: @node Bugs, Portability, Extensions, Top
        !          2226: @chapter Reporting Bugs
        !          2227: 
        !          2228: Your bug reports play an essential role in making GNU CC reliable.
        !          2229: 
        !          2230: Reporting a bug may help you by bringing a solution to your problem, or it
        !          2231: may not.  But in any case the important function of a bug report is to help
        !          2232: the entire community by making the next version of GNU CC work better.  Bug
        !          2233: reports are your contribution to the maintenance of GNU CC.
        !          2234: 
        !          2235: In order for a bug report to serve its purpose, you must include the
        !          2236: information that makes for fixing the bug.
        !          2237: 
        !          2238: @menu
        !          2239: * Criteria:  Bug Criteria.   Have you really found a bug?
        !          2240: * Reporting: Bug Reporting.  How to report a bug effectively.
        !          2241: @end menu
        !          2242: 
        !          2243: @node Bug Criteria, Bug Reporting, Bugs, Bugs
        !          2244: @section Have You Found a Bug?
        !          2245: 
        !          2246: If you are not sure whether you have found a bug, here are some guidelines:
        !          2247: 
        !          2248: @itemize @bullet
        !          2249: @item
        !          2250: If the compiler gets a fatal signal, for any input whatever, that is a
        !          2251: compiler bug.  Reliable compilers never crash.
        !          2252: 
        !          2253: @item
        !          2254: If the compiler produces invalid assembly code, for any input whatever
        !          2255: (except an @code{asm} statement), that is a compiler bug, unless the
        !          2256: compiler reports errors (not just warnings) which would ordinarily
        !          2257: prevent the assembler from being run.
        !          2258: 
        !          2259: @item
        !          2260: If the compiler produces valid assembly code that does not correctly
        !          2261: execute the input source code, that is a compiler bug.
        !          2262: 
        !          2263: However, you must double-check to make sure, because you may have run
        !          2264: into an incompatibility between GNU C and traditional C
        !          2265: (@pxref{Incompatibilities}).  These incompatibilities might be considered
        !          2266: bugs, but they are inescapable consequences of valuable features.
        !          2267: 
        !          2268: Or you may have a program whose behavior is undefined, which happened
        !          2269: by chance to give the desired results with another C compiler.
        !          2270: 
        !          2271: For example, in many nonoptimizing compilers, you can write @samp{x;}
        !          2272: at the end of a function instead of @samp{return x;}, with the same
        !          2273: results.  But the value of the function is undefined if @samp{return}
        !          2274: is omitted; it is not a bug when GNU CC produces different results.
        !          2275: 
        !          2276: Problems often result from expressions with two increment operators,
        !          2277: as in @samp{f (*p++, *p++)}.  Your previous compiler might have
        !          2278: interpreted that expression the way you intended; GNU CC might
        !          2279: interpret it another way; neither compiler is wrong.
        !          2280: 
        !          2281: After you have localized the error to a single source line, it should
        !          2282: be easy to check for these things.  If your program is correct and
        !          2283: well defined, you have found a compiler bug.
        !          2284: 
        !          2285: @item
        !          2286: If the compiler produces an error message for valid input, that is a
        !          2287: compiler bug.
        !          2288: 
        !          2289: Note that the following is not valid input, and the error message for
        !          2290: it is not a bug:
        !          2291: 
        !          2292: @example
        !          2293: int foo (char);
        !          2294: 
        !          2295: int
        !          2296: foo (x)
        !          2297:      char x;
        !          2298: @{ @dots{} @}
        !          2299: @end example
        !          2300: 
        !          2301: @noindent
        !          2302: The prototype says to pass a @code{char}, while the definition says to
        !          2303: pass an @code{int} and treat the value as a @code{char}.  This is what
        !          2304: the ANSI standard says, and it makes sense.
        !          2305: 
        !          2306: @item
        !          2307: If the compiler does not produce an error message for invalid input,
        !          2308: that is a compiler bug.  However, you should note that your idea of
        !          2309: ``invalid input'' might be my idea of ``an extension'' or ``support
        !          2310: for traditional practice''.
        !          2311: 
        !          2312: @item
        !          2313: If you are an experienced user of C compilers, your suggestions
        !          2314: for improvement of GNU CC are welcome in any case.
        !          2315: @end itemize
        !          2316: 
        !          2317: @node Bug Reporting,, Bug Criteria, Bugs
        !          2318: @section How to Report Bugs
        !          2319: 
        !          2320: Send bug reports for GNU C to one of these addresses:
        !          2321: 
        !          2322: @example
        !          2323: bug-gcc@@prep.ai.mit.edu
        !          2324: @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gcc
        !          2325: @end example
        !          2326: 
        !          2327: As a last resort, snail them to:
        !          2328: 
        !          2329: @example
        !          2330: GNU Compiler Bugs
        !          2331: 545 Tech Sq
        !          2332: Cambridge, MA 02139
        !          2333: @end example
        !          2334: 
        !          2335: The fundamental principle of reporting bugs usefully is this:
        !          2336: @strong{report all the facts}.  If you are not sure whether to mention a
        !          2337: fact or leave it out, mention it!
        !          2338: 
        !          2339: Often people omit facts because they think they know what causes the
        !          2340: problem and they conclude that some details don't matter.  Thus, you might
        !          2341: assume that the name of the variable you use in an example does not matter.
        !          2342: Well, probably it doesn't, but one cannot be sure.  Perhaps the bug is a
        !          2343: stray memory reference which happens to fetch from the location where that
        !          2344: name is stored in memory; perhaps, if the name were different, the contents
        !          2345: of that location would fool the compiler into doing the right thing despite
        !          2346: the bug.  Play it safe and give an exact example.
        !          2347: 
        !          2348: If you want to enable me to fix the bug, you should include all these
        !          2349: things:
        !          2350: 
        !          2351: @itemize @bullet
        !          2352: @item
        !          2353: The version of GNU CC.  You can get this by running it with the
        !          2354: @samp{-v} option.
        !          2355: 
        !          2356: Without this, I won't know whether there is any point in looking for
        !          2357: the bug in the current version of GNU CC.
        !          2358: 
        !          2359: @item
        !          2360: A complete input file that will reproduce the bug.  If the bug is in
        !          2361: the C preprocessor, send me a source file and any header files that it
        !          2362: requires.  If the bug is in the compiler proper (@file{cc1}), run your
        !          2363: source file through the C preprocessor by doing @samp{gcc -E
        !          2364: @var{sourcefile} > @var{outfile}}, then include the contents of
        !          2365: @var{outfile} in the bug report.  (Any @samp{-I}, @samp{-D} or
        !          2366: @samp{-U} options that you used in actual compilation should also be
        !          2367: used when doing this.)
        !          2368: 
        !          2369: A single statement is not enough of an example.  In order to compile
        !          2370: it, it must be embedded in a function definition; and the bug might
        !          2371: depend on the details of how this is done.
        !          2372: 
        !          2373: Without a real example I can compile, all I can do about your bug
        !          2374: report is wish you luck.  It would be futile to try to guess how to
        !          2375: provoke the bug.  For example, bugs in register allocation and
        !          2376: reloading frequently depend on every little detail of the function
        !          2377: they happen in.
        !          2378: 
        !          2379: @item
        !          2380: The command arguments you gave GNU CC to compile that example and
        !          2381: observe the bug.  For example, did you use @samp{-O}?  To guarantee
        !          2382: you won't omit something important, list them all.
        !          2383: 
        !          2384: If I were to try to guess the arguments, I would probably guess wrong
        !          2385: and then I would not encounter the bug.
        !          2386: 
        !          2387: @item
        !          2388: The names of the files that you used for @file{tm.h} and @file{md}
        !          2389: when you installed the compiler.
        !          2390: 
        !          2391: @item
        !          2392: The type of machine you are using, and the operating system name and
        !          2393: version number.
        !          2394: 
        !          2395: @item
        !          2396: A description of what behavior you observe that you believe is
        !          2397: incorrect.  For example, ``It gets a fatal signal,'' or, ``There is an
        !          2398: incorrect assembler instruction in the output.''
        !          2399: 
        !          2400: Of course, if the bug is that the compiler gets a fatal signal, then I
        !          2401: will certainly notice it.  But if the bug is incorrect output, I might
        !          2402: not notice unless it is glaringly wrong.  I won't study all the
        !          2403: assembler code from a 50-line C program just on the off chance that it
        !          2404: might be wrong.
        !          2405: 
        !          2406: Even if the problem you experience is a fatal signal, you should still
        !          2407: say so explicitly.  Suppose something strange is going on, such as,
        !          2408: your copy of the compiler is out of synch, or you have encountered a
        !          2409: bug in the C library on your system.  (This has happened!)  Your copy
        !          2410: might crash and mine would not.  If you @i{told} me to expect a crash,
        !          2411: then when mine fails to crash, I would know that the bug was not
        !          2412: happening for me.  If you had not told me to expect a crash, then I
        !          2413: would not be able to draw any conclusion from my observations.
        !          2414: 
        !          2415: In cases where GNU CC generates incorrect code, if you send me a small
        !          2416: complete sample program I will find the error myself by running the
        !          2417: program under a debugger.  If you send me a large example or a part of
        !          2418: a larger program, I cannot do this; you must debug the compiled
        !          2419: program and narrow the problem down to one source line.  Tell me which
        !          2420: source line it is, and what you believe is incorrect about the code
        !          2421: generated for that line.
        !          2422: 
        !          2423: @item
        !          2424: If you send me examples of output from GNU CC, please use @samp{-g}
        !          2425: when you make them.  The debugging information includes source line
        !          2426: numbers which are essential for correlating the output with the input.
        !          2427: 
        !          2428: @item
        !          2429: If you wish to suggest changes to the GNU CC source, send me context
        !          2430: diffs.  If you even discuss something in the GNU CC source, refer to
        !          2431: it by context, not by line number.
        !          2432: 
        !          2433: The line numbers in my development sources don't match those in your
        !          2434: sources.  Your line numbers would convey no useful information to me.
        !          2435: 
        !          2436: @item
        !          2437: Additional information from a debugger might enable me to find
        !          2438: a problem on a machine which I do not have available myself.
        !          2439: However, you need to think when you collect this information if
        !          2440: you want it to have any chance of being useful.
        !          2441: 
        !          2442: For example, many people send just a backtrace, but that is never
        !          2443: useful by itself.  A simple backtrace with arguments conveys little
        !          2444: about GNU CC because the compiler is largely data-driven; the same
        !          2445: functions are called over and over for different RTL insns, doing
        !          2446: different things depending on the details of the insn.
        !          2447: 
        !          2448: Most of the arguments listed in the backtrace are useless because they
        !          2449: are pointers to RTL list structure.  The numeric values of the
        !          2450: pointers, which the debugger prints in the backtrace, have no
        !          2451: significance whatever; all that matters is the contents of the objects
        !          2452: they point to (and most of the contents are other such pointers).
        !          2453: 
        !          2454: In addition, most compiler passes consist of one or more loops that
        !          2455: scan the RTL insn sequence.  The most vital piece of information about
        !          2456: such a loop--which insn it has reached--is usually in a local variable,
        !          2457: not in an argument.
        !          2458: 
        !          2459: What you need to provide in addition to a backtrace are the values of
        !          2460: the local variables for several stack frames up.  When a local
        !          2461: variable or an argument is an RTX, first print its value and then use
        !          2462: the GDB command @code{pr} to print the RTL expression that it points
        !          2463: to.  (If GDB doesn't run on your machine, use your debugger to call
        !          2464: the function @code{debug_rtx} with the RTX as an argument.)  In
        !          2465: general, whenever a variable is a pointer, its value is no use
        !          2466: without the data it points to.
        !          2467: 
        !          2468: In addition, include a debugging dump from just before the pass
        !          2469: in which the crash happens.  Most bugs involve a series of insns,
        !          2470: not just one.
        !          2471: @end itemize
        !          2472: 
        !          2473: Here are some things that are not necessary:
        !          2474: 
        !          2475: @itemize @bullet
        !          2476: @item
        !          2477: A description of the envelope of the bug.
        !          2478: 
        !          2479: Often people who encounter a bug spend a lot of time investigating
        !          2480: which changes to the input file will make the bug go away and which
        !          2481: changes will not affect it.
        !          2482: 
        !          2483: This is often time consuming and not very useful, because the way I
        !          2484: will find the bug is by running a single example under the debugger
        !          2485: with breakpoints, not by pure deduction from a series of examples.
        !          2486: 
        !          2487: Of course, if you can find a simpler example to report @emph{instead}
        !          2488: of the original one, that is a convenience for me.  Errors in the
        !          2489: output will be easier to spot, running under the debugger will take
        !          2490: less time, etc.  Most GNU CC bugs involve just one function, so the
        !          2491: most straightforward way to simplify an example is to delete all the
        !          2492: function definitions except the one where the bug occurs.  Those
        !          2493: earlier in the file may be replaced by external declarations if the
        !          2494: crucial function depends on them.
        !          2495: 
        !          2496: However, simplification is not vital; if you don't want to do this,
        !          2497: report the bug anyway.
        !          2498: 
        !          2499: @item
        !          2500: A patch for the bug.
        !          2501: 
        !          2502: A patch for the bug does help me if it is a good one.  But don't omit
        !          2503: the necessary information, such as the test case, because I might see
        !          2504: problems with your patch and decide to fix the problem another way.
        !          2505: 
        !          2506: Sometimes with a program as complicated as GNU CC it is very hard to
        !          2507: construct an example that will make the program follow a certain path
        !          2508: through the code.  If you don't send me the example, I won't be able
        !          2509: to construct one, so I won't be able to verify that the bug is fixed.
        !          2510: 
        !          2511: @item
        !          2512: A guess about what the bug is or what it depends on.
        !          2513: 
        !          2514: Such guesses are usually wrong.  Even I can't guess right about such
        !          2515: things without using the debugger to find the facts.
        !          2516: @end itemize
        !          2517: 
        !          2518: @node Portability, Interface, Bugs, Top
        !          2519: @chapter GNU CC and Portability
        !          2520: 
        !          2521: The main goal of GNU CC was to make a good, fast compiler for machines in
        !          2522: the class that the GNU system aims to run on: 32-bit machines that address
        !          2523: 8-bit bytes and have several general registers.  Elegance, theoretical
        !          2524: power and simplicity are only secondary.
        !          2525: 
        !          2526: GNU CC gets most of the information about the target machine from a machine
        !          2527: description which gives an algebraic formula for each of the machine's
        !          2528: instructions.  This is a very clean way to describe the target.  But when
        !          2529: the compiler needs information that is difficult to express in this
        !          2530: fashion, I have not hesitated to define an ad-hoc parameter to the machine
        !          2531: description.  The purpose of portability is to reduce the total work needed
        !          2532: on the compiler; it was not of interest for its own sake.
        !          2533: 
        !          2534: GNU CC does not contain machine dependent code, but it does contain code
        !          2535: that depends on machine parameters such as endianness (whether the most
        !          2536: significant byte has the highest or lowest address of the bytes in a word)
        !          2537: and the availability of autoincrement addressing.  In the RTL-generation
        !          2538: pass, it is often necessary to have multiple strategies for generating code
        !          2539: for a particular kind of syntax tree, strategies that are usable for different
        !          2540: combinations of parameters.  Often I have not tried to address all possible
        !          2541: cases, but only the common ones or only the ones that I have encountered.
        !          2542: As a result, a new target may require additional strategies.  You will know
        !          2543: if this happens because the compiler will call @code{abort}.  Fortunately,
        !          2544: the new strategies can be added in a machine-independent fashion, and will
        !          2545: affect only the target machines that need them.
        !          2546: 
        !          2547: @node Interface, Passes, Portability, Top
        !          2548: @chapter Interfacing to GNU CC Output
        !          2549: 
        !          2550: GNU CC is normally configured to use the same function calling convention
        !          2551: normally in use on the target system.  This is done with the
        !          2552: machine-description macros described (@pxref{Machine Macros}).
        !          2553: 
        !          2554: However, returning of structure and union values is done differently on
        !          2555: some target machines.  As a result, functions compiled with PCC
        !          2556: returning such types cannot be called from code compiled with GNU CC,
        !          2557: and vice versa.  This does not cause trouble often because few Unix
        !          2558: library routines return structures or unions.
        !          2559: 
        !          2560: GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes
        !          2561: long in the same registers used for @code{int} or @code{double} return
        !          2562: values.  (GNU CC typically allocates variables of such types in
        !          2563: registers also.)  Structures and unions of other sizes are returned by
        !          2564: storing them into an address passed by the caller (usually in a
        !          2565: register).  The machine-description macros @code{STRUCT_VALUE} and
        !          2566: @code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address.
        !          2567: 
        !          2568: By contrast, PCC on most target machines returns structures and unions
        !          2569: of any size by copying the data into an area of static storage, and then
        !          2570: returning the address of that storage as if it were a pointer value.
        !          2571: The caller must copy the data from that memory area to the place where
        !          2572: the value is wanted.  This is slower than the method used by GNU CC, and
        !          2573: fails to be reentrant.
        !          2574: 
        !          2575: On some target machines, such as RISC machines and the 80386, the
        !          2576: standard system convention is to pass to the subroutine the address of
        !          2577: where to return the value.  On these machines, GNU CC has been
        !          2578: configured to be compatible with the standard compiler, when this method
        !          2579: is used.  It may not be compatible for structures of 1, 2, 4 or 8 bytes.
        !          2580: 
        !          2581: GNU CC uses the system's standard convention for passing arguments.  On
        !          2582: some machines, the first few arguments are passed in registers; in
        !          2583: others, all are passed on the stack.  It would be possible to use
        !          2584: registers for argument passing on any machine, and this would probably
        !          2585: result in a significant speedup.  But the result would be complete
        !          2586: incompatibility with code that follows the standard convention.  So this
        !          2587: change is practical only if you are switching to GNU CC as the sole C
        !          2588: compiler for the system.  We may implement register argument passing on
        !          2589: certain machines once we have a complete GNU system so that we can
        !          2590: compile the libraries with GNU CC.
        !          2591: 
        !          2592: If you use @code{longjmp}, beware of automatic variables.  ANSI C says that
        !          2593: automatic variables that are not declared @code{volatile} have undefined
        !          2594: values after a @code{longjmp}.  And this is all GNU CC promises to do,
        !          2595: because it is very difficult to restore register variables correctly, and
        !          2596: one of GNU CC's features is that it can put variables in registers without
        !          2597: your asking it to.
        !          2598: 
        !          2599: If you want a variable to be unaltered by @code{longjmp}, and you don't
        !          2600: want to write @code{volatile} because old C compilers don't accept it,
        !          2601: just take the address of the variable.  If a variable's address is ever
        !          2602: taken, even if just to compute it and ignore it, then the variable cannot
        !          2603: go in a register:
        !          2604: 
        !          2605: @example
        !          2606: @{
        !          2607:   int careful;
        !          2608:   &careful;
        !          2609:   @dots{}
        !          2610: @}
        !          2611: @end example
        !          2612: 
        !          2613: Code compiled with GNU CC may call certain library routines.  Most of
        !          2614: them handle arithmetic for which there are no instructions.  This
        !          2615: includes multiply and divide on some machines, and floating point
        !          2616: operations on any machine for which floating point support is disabled
        !          2617: with @samp{-msoft-float}.  Some standard parts of the C library, such as
        !          2618: @code{bcopy} or @code{memcpy}, are also called automatically.  The usual
        !          2619: function call interface is used for calling the library routines.
        !          2620: 
        !          2621: These library routines should be defined in the library @file{gnulib},
        !          2622: which GNU CC automatically searches whenever it links a program.  On
        !          2623: machines that have multiply and divide instructions, if hardware
        !          2624: floating point is in use, normally @file{gnulib} is not needed, but it
        !          2625: is searched just in case.
        !          2626: 
        !          2627: Each arithmetic function is defined in @file{gnulib.c} to use the
        !          2628: corresponding C arithmetic operator.  As long as the file is compiled
        !          2629: with another C compiler, which supports all the C arithmetic operators,
        !          2630: this file will work portably.  However, @file{gnulib.c} does not work if
        !          2631: compiled with GNU CC, because each arithmetic function would compile
        !          2632: into a call to itself!
        !          2633: 
        !          2634: @node Passes, RTL, Interface, Top
        !          2635: @chapter Passes and Files of the Compiler
        !          2636: 
        !          2637: The overall control structure of the compiler is in @file{toplev.c}.  This
        !          2638: file is responsible for initialization, decoding arguments, opening and
        !          2639: closing files, and sequencing the passes.
        !          2640: 
        !          2641: The parsing pass is invoked only once, to parse the entire input.  The RTL
        !          2642: intermediate code for a function is generated as the function is parsed, a
        !          2643: statement at a time.  Each statement is read in as a syntax tree and then
        !          2644: converted to RTL; then the storage for the tree for the statement is
        !          2645: reclaimed.  Storage for types (and the expressions for their sizes),
        !          2646: declarations, and a representation of the binding contours and how they nest,
        !          2647: remains until the function is finished being compiled; these are all needed
        !          2648: to output the debugging information.
        !          2649: 
        !          2650: Each time the parsing pass reads a complete function definition or
        !          2651: top-level declaration, it calls the function
        !          2652: @code{rest_of_compilation} or @code{rest_of_decl_compilation} in
        !          2653: @file{toplev.c}, which are responsible for all further processing
        !          2654: necessary, ending with output of the assembler language.  All other
        !          2655: compiler passes run, in sequence, within @code{rest_of_compilation}.
        !          2656: When that function returns from compiling a function definition, the
        !          2657: storage used for that function definition's compilation is entirely
        !          2658: freed, unless it is an inline function (@pxref{Inline}).
        !          2659: 
        !          2660: Here is a list of all the passes of the compiler and their source files.
        !          2661: Also included is a description of where debugging dumps can be requested
        !          2662: with @samp{-d} options.
        !          2663: 
        !          2664: @itemize @bullet
        !          2665: @item
        !          2666: Parsing.  This pass reads the entire text of a function definition,
        !          2667: constructing partial syntax trees.  This and RTL generation are no longer
        !          2668: truly separate passes (formerly they were), but it is easier to think
        !          2669: of them as separate.
        !          2670: 
        !          2671: The tree representation does not entirely follow C syntax, because it is
        !          2672: intended to support other languages as well.
        !          2673: 
        !          2674: C data type analysis is also done in this pass, and every tree node
        !          2675: that represents an expression has a data type attached.  Variables are
        !          2676: represented as declaration nodes.
        !          2677: 
        !          2678: Constant folding and associative-law simplifications are also done
        !          2679: during this pass.
        !          2680: 
        !          2681: The source files for parsing are @file{c-parse.y}, @file{c-decl.c},
        !          2682: @file{c-typeck.c}, @file{c-convert.c}, @file{stor-layout.c},
        !          2683: @file{fold-const.c}, and @file{tree.c}.  The last three files are
        !          2684: intended to be language-independent.  There are also header files
        !          2685: @file{c-parse.h}, @file{c-tree.h}, @file{tree.h} and @file{tree.def}.
        !          2686: The last two define the format of the tree representation.@refill
        !          2687: 
        !          2688: @item
        !          2689: RTL generation.  This is the conversion of syntax tree into RTL code.
        !          2690: It is actually done statement-by-statement during parsing, but for
        !          2691: most purposes it can be thought of as a separate pass.
        !          2692: 
        !          2693: This is where the bulk of target-parameter-dependent code is found,
        !          2694: since often it is necessary for strategies to apply only when certain
        !          2695: standard kinds of instructions are available.  The purpose of named
        !          2696: instruction patterns is to provide this information to the RTL
        !          2697: generation pass.
        !          2698: 
        !          2699: Optimization is done in this pass for @code{if}-conditions that are
        !          2700: comparisons, boolean operations or conditional expressions.  Tail
        !          2701: recursion is detected at this time also.  Decisions are made about how
        !          2702: best to arrange loops and how to output @code{switch} statements.
        !          2703: 
        !          2704: The source files for RTL generation are @file{stmt.c}, @file{expr.c},
        !          2705: @file{explow.c}, @file{expmed.c}, @file{optabs.c} and @file{emit-rtl.c}.
        !          2706: Also, the file @file{insn-emit.c}, generated from the machine description
        !          2707: by the program @code{genemit}, is used in this pass.  The header files
        !          2708: @file{expr.h} is used for communication within this pass.@refill
        !          2709: 
        !          2710: The header files @file{insn-flags.h} and @file{insn-codes.h},
        !          2711: generated from the machine description by the programs @code{genflags}
        !          2712: and @code{gencodes}, tell this pass which standard names are available
        !          2713: for use and which patterns correspond to them.@refill
        !          2714: 
        !          2715: Aside from debugging information output, none of the following passes
        !          2716: refers to the tree structure representation of the function (only
        !          2717: part of which is saved).
        !          2718: 
        !          2719: The decision of whether the function can and should be expanded inline
        !          2720: in its subsequent callers is made at the end of rtl generation.  The
        !          2721: function must meet certain criteria, currently related to the size of
        !          2722: the function and the types and number of parameters it has.  Note that
        !          2723: this function may contain loops, recursive calls to itself
        !          2724: (tail-recursive functions can be inlined!), gotos, in short, all
        !          2725: constructs supported by GNU CC.
        !          2726: 
        !          2727: The option @samp{-dr} causes a debugging dump of the RTL code after
        !          2728: this pass.  This dump file's name is made by appending @samp{.rtl} to
        !          2729: the input file name.
        !          2730: 
        !          2731: @item
        !          2732: Jump optimization.  This pass simplifies jumps to the following
        !          2733: instruction, jumps across jumps, and jumps to jumps.  It deletes
        !          2734: unreferenced labels and unreachable code, except that unreachable code
        !          2735: that contains a loop is not recognized as unreachable in this pass.
        !          2736: (Such loops are deleted later in the basic block analysis.)
        !          2737: 
        !          2738: Jump optimization is performed two or three times.  The first time is
        !          2739: immediately following RTL generation.  The second time is after CSE,
        !          2740: but only if CSE says repeated jump optimization is needed.  The
        !          2741: last time is right before the final pass.  That time, cross-jumping
        !          2742: and deletion of no-op move instructions are done together with the
        !          2743: optimizations described above.
        !          2744: 
        !          2745: The source file of this pass is @file{jump.c}.
        !          2746: 
        !          2747: The option @samp{-dj} causes a debugging dump of the RTL code after
        !          2748: this pass is run for the first time.  This dump file's name is made by
        !          2749: appending @samp{.jump} to the input file name.
        !          2750: 
        !          2751: @item
        !          2752: Register scan.  This pass finds the first and last use of each
        !          2753: register, as a guide for common subexpression elimination.  Its source
        !          2754: is in @file{regclass.c}.
        !          2755: 
        !          2756: @item
        !          2757: Common subexpression elimination.  This pass also does constant
        !          2758: propagation.  Its source file is @file{cse.c}.  If constant
        !          2759: propagation causes conditional jumps to become unconditional or to
        !          2760: become no-ops, jump optimization is run again when CSE is finished.
        !          2761: 
        !          2762: The option @samp{-ds} causes a debugging dump of the RTL code after
        !          2763: this pass.  This dump file's name is made by appending @samp{.cse} to
        !          2764: the input file name.
        !          2765: 
        !          2766: @item
        !          2767: Loop optimization.  This pass moves constant expressions out of loops.
        !          2768: Its source file is @file{loop.c}.
        !          2769: 
        !          2770: The option @samp{-dL} causes a debugging dump of the RTL code after
        !          2771: this pass.  This dump file's name is made by appending @samp{.loop} to
        !          2772: the input file name.
        !          2773: 
        !          2774: @item
        !          2775: Stupid register allocation is performed at this point in a
        !          2776: nonoptimizing compilation.  It does a little data flow analysis as
        !          2777: well.  When stupid register allocation is in use, the next pass
        !          2778: executed is the reloading pass; the others in between are skipped.
        !          2779: The source file is @file{stupid.c}.
        !          2780: 
        !          2781: @item
        !          2782: Data flow analysis (@file{flow.c}).  This pass divides the program
        !          2783: into basic blocks (and in the process deletes unreachable loops); then
        !          2784: it computes which pseudo-registers are live at each point in the
        !          2785: program, and makes the first instruction that uses a value point at
        !          2786: the instruction that computed the value.
        !          2787: 
        !          2788: This pass also deletes computations whose results are never used, and
        !          2789: combines memory references with add or subtract instructions to make
        !          2790: autoincrement or autodecrement addressing.
        !          2791: 
        !          2792: The option @samp{-df} causes a debugging dump of the RTL code after
        !          2793: this pass.  This dump file's name is made by appending @samp{.flow} to
        !          2794: the input file name.  If stupid register allocation is in use, this
        !          2795: dump file reflects the full results of such allocation.
        !          2796: 
        !          2797: @item
        !          2798: Instruction combination (@file{combine.c}).  This pass attempts to
        !          2799: combine groups of two or three instructions that are related by data
        !          2800: flow into single instructions.  It combines the RTL expressions for
        !          2801: the instructions by substitution, simplifies the result using algebra,
        !          2802: and then attempts to match the result against the machine description.
        !          2803: 
        !          2804: The option @samp{-dc} causes a debugging dump of the RTL code after
        !          2805: this pass.  This dump file's name is made by appending @samp{.combine}
        !          2806: to the input file name.
        !          2807: 
        !          2808: @item
        !          2809: Register class preferencing.  The RTL code is scanned to find out
        !          2810: which register class is best for each pseudo register.  The source
        !          2811: file is @file{regclass.c}.
        !          2812: 
        !          2813: @item
        !          2814: Local register allocation (@file{local-alloc.c}).  This pass allocates
        !          2815: hard registers to pseudo registers that are used only within one basic
        !          2816: block.  Because the basic block is linear, it can use fast and
        !          2817: powerful techniques to do a very good job.
        !          2818: 
        !          2819: The option @samp{-dl} causes a debugging dump of the RTL code after
        !          2820: this pass.  This dump file's name is made by appending @samp{.lreg} to
        !          2821: the input file name.
        !          2822: 
        !          2823: @item
        !          2824: Global register allocation (@file{global-alloc.c}).  This pass
        !          2825: allocates hard registers for the remaining pseudo registers (those
        !          2826: whose life spans are not contained in one basic block).
        !          2827: 
        !          2828: @item
        !          2829: Reloading.  This pass renumbers pseudo registers with the hardware
        !          2830: registers numbers they were allocated.  Pseudo registers that did not
        !          2831: get hard registers are replaced with stack slots.  Then it finds
        !          2832: instructions that are invalid because a value has failed to end up in
        !          2833: a register, or has ended up in a register of the wrong kind.  It fixes
        !          2834: up these instructions by reloading the problematical values
        !          2835: temporarily into registers.  Additional instructions are generated to
        !          2836: do the copying.
        !          2837: 
        !          2838: Source files are @file{reload.c} and @file{reload1.c}, plus the header
        !          2839: @file{reload.h} used for communication between them.
        !          2840: 
        !          2841: The option @samp{-dg} causes a debugging dump of the RTL code after
        !          2842: this pass.  This dump file's name is made by appending @samp{.greg} to
        !          2843: the input file name.
        !          2844: 
        !          2845: @item
        !          2846: Jump optimization is repeated, this time including cross-jumping
        !          2847: and deletion of no-op move instructions.  Machine-specific peephole
        !          2848: optimizations are performed at the same time.
        !          2849: 
        !          2850: The option @samp{-dJ} causes a debugging dump of the RTL code after
        !          2851: this pass.  This dump file's name is made by appending @samp{.jump2}
        !          2852: to the input file name.
        !          2853: 
        !          2854: @item
        !          2855: Final.  This pass outputs the assembler code for the function.  It is
        !          2856: also responsible for identifying spurious test and compare
        !          2857: instructions.  The function entry and exit sequences are generated
        !          2858: directly as assembler code in this pass; they never exist as RTL.
        !          2859: 
        !          2860: The source files are @file{final.c} plus @file{insn-output.c}; the
        !          2861: latter is generated automatically from the machine description by the
        !          2862: tool @file{genoutput}.  The header file @file{conditions.h} is used
        !          2863: for communication between these files.
        !          2864: 
        !          2865: @item
        !          2866: Debugging information output.  This is run after final because it must
        !          2867: output the stack slot offsets for pseudo registers that did not get
        !          2868: hard registers.  Source files are @file{dbxout.c} for DBX symbol table
        !          2869: format and @file{symout.c} for GDB's own symbol table format.
        !          2870: @end itemize
        !          2871: 
        !          2872: Some additional files are used by all or many passes:
        !          2873: 
        !          2874: @itemize @bullet
        !          2875: @item
        !          2876: Every pass uses @file{machmode.def}, which defines the machine modes.
        !          2877: 
        !          2878: @item
        !          2879: All the passes that work with RTL use the header files @file{rtl.h}
        !          2880: and @file{rtl.def}, and subroutines in file @file{rtl.c}.  The tools
        !          2881: @code{gen*} also use these files to read and work with the machine
        !          2882: description RTL.
        !          2883: 
        !          2884: @item
        !          2885: Several passes refer to the header file @file{insn-config.h} which
        !          2886: contains a few parameters (C macro definitions) generated
        !          2887: automatically from the machine description RTL by the tool
        !          2888: @code{genconfig}.
        !          2889: 
        !          2890: @item
        !          2891: Several passes use the instruction recognizer, which consists of
        !          2892: @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
        !          2893: and @file{insn-extract.c} that are generated automatically from the
        !          2894: machine description by the tools @file{genrecog} and
        !          2895: @file{genextract}.@refill
        !          2896: 
        !          2897: @item
        !          2898: Several passes use the header files @file{regs.h} which defines the
        !          2899: information recorded about pseudo register usage, and @file{basic-block.h}
        !          2900: which defines the information recorded about basic blocks.
        !          2901: 
        !          2902: @item
        !          2903: @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
        !          2904: with a bit for each hard register, and some macros to manipulate it.
        !          2905: This type is just @code{int} if the machine has few enough hard registers;
        !          2906: otherwise it is an array of @code{int} and some of the macros expand
        !          2907: into loops.
        !          2908: @end itemize
        !          2909: 
        !          2910: @node RTL, Machine Desc, Passes, Top
        !          2911: @chapter RTL Representation
        !          2912: 
        !          2913: Most of the work of the compiler is done on an intermediate representation
        !          2914: called register transfer language.  In this language, the instructions to be
        !          2915: output are described, pretty much one by one, in an algebraic form that
        !          2916: describes what the instruction does.
        !          2917: 
        !          2918: RTL is inspired by Lisp lists.  It has both an internal form, made up of
        !          2919: structures that point at other structures, and a textual form that is used
        !          2920: in the machine description and in printed debugging dumps.  The textual
        !          2921: form uses nested parentheses to indicate the pointers in the internal form.
        !          2922: 
        !          2923: @menu
        !          2924: * RTL Objects::       Expressions vs vectors vs strings vs integers.
        !          2925: * Accessors::         Macros to access expression operands or vector elts.
        !          2926: * Flags::             Other flags in an RTL expression.
        !          2927: * Machine Modes::     Describing the size and format of a datum.
        !          2928: * Constants::         Expressions with constant values.
        !          2929: * Regs and Memory::   Expressions representing register contents or memory.
        !          2930: * Arithmetic::        Expressions representing arithmetic on other expressions.
        !          2931: * Comparisons::       Expressions representing comparison of expressions.
        !          2932: * Bit Fields::        Expressions representing bit-fields in memory or reg.
        !          2933: * Conversions::       Extending, truncating, floating or fixing.
        !          2934: * RTL Declarations::  Declaring volatility, constancy, etc.
        !          2935: * Side Effects::      Expressions for storing in registers, etc.
        !          2936: * Incdec::            Embedded side-effects for autoincrement addressing.
        !          2937: * Assembler::        Representing @code{asm} with operands.
        !          2938: * Insns::             Expression types for entire insns.
        !          2939: * Calls::            RTL representation of function call insns.
        !          2940: * Sharing::           Some expressions are unique; others *must* be copied.
        !          2941: @end menu
        !          2942: 
        !          2943: @node RTL Objects, Accessors, RTL, RTL
        !          2944: @section RTL Object Types
        !          2945: 
        !          2946: RTL uses four kinds of objects: expressions, integers, strings and vectors.
        !          2947: Expressions are the most important ones.  An RTL expression (``RTX'', for
        !          2948: short) is a C structure, but it is usually referred to with a pointer; a
        !          2949: type that is given the typedef name @code{rtx}.
        !          2950: 
        !          2951: An integer is simply an @code{int}, and a string is a @code{char *}.
        !          2952: Within RTL code, strings appear only inside @samp{symbol_ref} expressions,
        !          2953: but they appear in other contexts in the RTL expressions that make up
        !          2954: machine descriptions.  Their written form uses decimal digits.
        !          2955: 
        !          2956: A string is a sequence of characters.  In core it is represented as a
        !          2957: @code{char *} in usual C fashion, and it is written in C syntax as well.
        !          2958: However, strings in RTL may never be null.  If you write an empty string in
        !          2959: a machine description, it is represented in core as a null pointer rather
        !          2960: than as a pointer to a null character.  In certain contexts, these null
        !          2961: pointers instead of strings are valid.
        !          2962: 
        !          2963: A vector contains an arbitrary, specified number of pointers to
        !          2964: expressions.  The number of elements in the vector is explicitly present in
        !          2965: the vector.  The written form of a vector consists of square brackets
        !          2966: (@samp{[@dots{}]}) surrounding the elements, in sequence and with
        !          2967: whitespace separating them.  Vectors of length zero are not created; null
        !          2968: pointers are used instead.
        !          2969: 
        !          2970: Expressions are classified by @dfn{expression codes} (also called RTX
        !          2971: codes).  The expression code is a name defined in @file{rtl.def}, which is
        !          2972: also (in upper case) a C enumeration constant.  The possible expression
        !          2973: codes and their meanings are machine-independent.  The code of an RTX can
        !          2974: be extracted with the macro @code{GET_CODE (@var{x})} and altered with
        !          2975: @code{PUT_CODE (@var{x}, @var{newcode})}.
        !          2976: 
        !          2977: The expression code determines how many operands the expression contains,
        !          2978: and what kinds of objects they are.  In RTL, unlike Lisp, you cannot tell
        !          2979: by looking at an operand what kind of object it is.  Instead, you must know
        !          2980: from its context---from the expression code of the containing expression.
        !          2981: For example, in an expression of code @samp{subreg}, the first operand is
        !          2982: to be regarded as an expression and the second operand as an integer.  In
        !          2983: an expression of code @samp{plus}, there are two operands, both of which
        !          2984: are to be regarded as expressions.  In a @samp{symbol_ref} expression,
        !          2985: there is one operand, which is to be regarded as a string.
        !          2986: 
        !          2987: Expressions are written as parentheses containing the name of the
        !          2988: expression type, its flags and machine mode if any, and then the operands
        !          2989: of the expression (separated by spaces).
        !          2990: 
        !          2991: Expression code names in the @samp{md} file are written in lower case,
        !          2992: but when they appear in C code they are written in upper case.  In this
        !          2993: manual, they are shown as follows: @samp{const_int}.
        !          2994: 
        !          2995: In a few contexts a null pointer is valid where an expression is normally
        !          2996: wanted.  The written form of this is @samp{(nil)}.
        !          2997: 
        !          2998: @node Accessors, Flags, RTL Objects, RTL
        !          2999: @section Access to Operands
        !          3000: 
        !          3001: For each expression type @file{rtl.def} specifies the number of contained
        !          3002: objects and their kinds, with four possibilities: @samp{e} for expression
        !          3003: (actually a pointer to an expression), @samp{i} for integer, @samp{s} for
        !          3004: string, and @samp{E} for vector of expressions.  The sequence of letters
        !          3005: for an expression code is called its @dfn{format}.  Thus, the format of
        !          3006: @samp{subreg} is @samp{ei}.@refill
        !          3007: 
        !          3008: Two other format characters are used occasionally: @samp{u} and @samp{0}.
        !          3009: @samp{u} is equivalent to @samp{e} except that it is printed differently in
        !          3010: debugging dumps, and @samp{0} means a slot whose contents do not fit any
        !          3011: normal category.  @samp{0} slots are not printed at all in dumps, and are
        !          3012: often used in special ways by small parts of the compiler.@refill
        !          3013: 
        !          3014: There are macros to get the number of operands and the format of an
        !          3015: expression code:
        !          3016: 
        !          3017: @table @code
        !          3018: @item GET_RTX_LENGTH (@var{code})
        !          3019: Number of operands of an RTX of code @var{code}.
        !          3020: 
        !          3021: @item GET_RTX_FORMAT (@var{code})
        !          3022: The format of an RTX of code @var{code}, as a C string.
        !          3023: @end table
        !          3024: 
        !          3025: Operands of expressions are accessed using the macros @code{XEXP},
        !          3026: @code{XINT} and @code{XSTR}.  Each of these macros takes two arguments: an
        !          3027: expression-pointer (RTX) and an operand number (counting from zero).
        !          3028: Thus,@refill
        !          3029: 
        !          3030: @example
        !          3031: XEXP (@var{x}, 2)
        !          3032: @end example
        !          3033: 
        !          3034: @noindent
        !          3035: accesses operand 2 of expression @var{x}, as an expression.
        !          3036: 
        !          3037: @example
        !          3038: XINT (@var{x}, 2)
        !          3039: @end example
        !          3040: 
        !          3041: @noindent
        !          3042: accesses the same operand as an integer.  @code{XSTR}, used in the same
        !          3043: fashion, would access it as a string.
        !          3044: 
        !          3045: Any operand can be accessed as an integer, as an expression or as a string.
        !          3046: You must choose the correct method of access for the kind of value actually
        !          3047: stored in the operand.  You would do this based on the expression code of
        !          3048: the containing expression.  That is also how you would know how many
        !          3049: operands there are.
        !          3050: 
        !          3051: For example, if @var{x} is a @samp{subreg} expression, you know that it has
        !          3052: two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
        !          3053: and @code{XINT (@var{x}, 1)}.  If you did @code{XINT (@var{x}, 0)}, you
        !          3054: would get the address of the expression operand but cast as an integer;
        !          3055: that might occasionally be useful, but it would be cleaner to write
        !          3056: @code{(int) XEXP (@var{x}, 0)}.  @code{XEXP (@var{x}, 1)} would also
        !          3057: compile without error, and would return the second, integer operand cast as
        !          3058: an expression pointer, which would probably result in a crash when
        !          3059: accessed.  Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
        !          3060: but this will access memory past the end of the expression with
        !          3061: unpredictable results.@refill
        !          3062: 
        !          3063: Access to operands which are vectors is more complicated.  You can use the
        !          3064: macro @code{XVEC} to get the vector-pointer itself, or the macros
        !          3065: @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
        !          3066: vector.
        !          3067: 
        !          3068: @table @code
        !          3069: @item XVEC (@var{exp}, @var{idx})
        !          3070: Access the vector-pointer which is operand number @var{idx} in @var{exp}.
        !          3071: 
        !          3072: @item XVECLEN (@var{exp}, @var{idx})
        !          3073: Access the length (number of elements) in the vector which is
        !          3074: in operand number @var{idx} in @var{exp}.  This value is an @code{int}.
        !          3075: 
        !          3076: @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
        !          3077: Access element number @var{eltnum} in the vector which is
        !          3078: in operand number @var{idx} in @var{exp}.  This value is an RTX.
        !          3079: 
        !          3080: It is up to you to make sure that @var{eltnum} is not negative
        !          3081: and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
        !          3082: @end table
        !          3083: 
        !          3084: All the macros defined in this section expand into lvalues and therefore
        !          3085: can be used to assign the operands, lengths and vector elements as well as
        !          3086: to access them.
        !          3087: 
        !          3088: @node Flags, Machine Modes, Accessors, RTL
        !          3089: @section Flags in an RTL Expression
        !          3090: 
        !          3091: RTL expressions contain several flags (one-bit bit-fields) that are used
        !          3092: in certain types of expression.  Most often they are accessed with the
        !          3093: following macros:
        !          3094: 
        !          3095: @table @code
        !          3096: @item MEM_VOLATILE_P (@var{x})
        !          3097: In @samp{mem} expressions, nonzero for volatile memory references.
        !          3098: Stored in the @code{volatil} field and printed as @samp{/v}.
        !          3099: 
        !          3100: @item MEM_IN_STRUCT_P (@var{x})
        !          3101: In @samp{mem} expressions, nonzero for reference to an entire
        !          3102: structure, union or array, or to a component of one.  Zero for
        !          3103: references to a scalar variable or through a pointer to a scalar.
        !          3104: Stored in the @code{in_struct} field and printed as @samp{/s}.
        !          3105: 
        !          3106: @item REG_USER_VAR_P (@var{x})
        !          3107: In a @samp{reg}, nonzero if it corresponds to a variable present in
        !          3108: the user's source code.  Zero for temporaries generated internally by
        !          3109: the compiler.  Stored in the @code{volatil} field and printed as
        !          3110: @samp{/v}.
        !          3111: 
        !          3112: @item REG_FUNCTION_VALUE_P (@var{x})
        !          3113: Nonzero in a @samp{reg} if it is the place in which this function's
        !          3114: value is going to be returned.  (This happens only in a hard
        !          3115: register.)  Stored in the @code{integrated} field and printed as
        !          3116: @samp{/i}.
        !          3117: 
        !          3118: The same hard register may be used also for collecting the values of
        !          3119: functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
        !          3120: in this kind of use.
        !          3121: 
        !          3122: @item RTX_UNCHANGING_P (@var{x})
        !          3123: Nonzero in a @samp{reg} or @samp{mem} if the value is not changed
        !          3124: explicitly by the current function.  (If it is a memory reference then
        !          3125: it may be changed by other functions or by aliasing.)  Stored in the
        !          3126: @code{unchanging} field and printed as @samp{/u}.
        !          3127: 
        !          3128: @item RTX_INTEGRATED_P (@var{insn})
        !          3129: Nonzero in an insn if it resulted from an in-line function call.
        !          3130: Stored in the @code{integrated} field and printed as @samp{/i}.  This
        !          3131: may be deleted; nothing currently depends on it.
        !          3132: 
        !          3133: @item INSN_DELETED_P (@var{insn})
        !          3134: In an insn, nonzero if the insn has been deleted.  Stored in the
        !          3135: @code{volatil} field and printed as @samp{/v}.
        !          3136: 
        !          3137: @item CONSTANT_POOL_ADDRESS_P (@var{x})
        !          3138: Nonzero in a @samp{symbol_ref} if it refers to part of the current
        !          3139: function's ``constants pool''.  These are addresses close to the
        !          3140: beginning of the function, and GNU CC assumes they can be addressed
        !          3141: directly (perhaps with the help of base registers).  Stored in the
        !          3142: @code{unchanging} field and printed as @samp{/u}.
        !          3143: @end table
        !          3144: 
        !          3145: These are the fields which the above macros refer to:
        !          3146: 
        !          3147: @table @code
        !          3148: @item used
        !          3149: This flag is used only momentarily, at the end of RTL generation for a
        !          3150: function, to count the number of times an expression appears in insns.
        !          3151: Expressions that appear more than once are copied, according to the
        !          3152: rules for shared structure (@pxref{Sharing}).
        !          3153: 
        !          3154: @item volatil
        !          3155: This flag is used in @samp{mem} and @samp{reg} expressions and in insns.
        !          3156: In RTL dump files, it is printed as @samp{/v}.
        !          3157: 
        !          3158: In a @samp{mem} expression, it is 1 if the memory reference is volatile.
        !          3159: Volatile memory references may not be deleted, reordered or combined.
        !          3160: 
        !          3161: In a @samp{reg} expression, it is 1 if the value is a user-level variable.
        !          3162: 0 indicates an internal compiler temporary.
        !          3163: 
        !          3164: In an insn, 1 means the insn has been deleted.
        !          3165: 
        !          3166: @item in_struct
        !          3167: This flag is used in @samp{mem} expressions.  It is 1 if the memory
        !          3168: datum referred to is all or part of a structure or array; 0 if it is (or
        !          3169: might be) a scalar variable.  A reference through a C pointer has 0
        !          3170: because the pointer might point to a scalar variable.
        !          3171: 
        !          3172: This information allows the compiler to determine something about possible
        !          3173: cases of aliasing.
        !          3174: 
        !          3175: In an RTL dump, this flag is represented as @samp{/s}.
        !          3176: 
        !          3177: @item unchanging
        !          3178: This flag is used in @samp{reg} and @samp{mem} expressions.  1 means
        !          3179: that the value of the expression never changes (at least within the
        !          3180: current function).
        !          3181: 
        !          3182: In an RTL dump, this flag is represented as @samp{/u}.
        !          3183: 
        !          3184: @item integrated
        !          3185: In some kinds of expressions, including insns, this flag means the
        !          3186: rtl was produced by procedure integration.
        !          3187: 
        !          3188: In a @samp{reg} expression, this flag indicates the register
        !          3189: containing the value to be returned by the current function.  On
        !          3190: machines that pass parameters in registers, the same register number
        !          3191: may be used for parameters as well, but this flag is not set on such
        !          3192: uses.
        !          3193: @end table
        !          3194: 
        !          3195: @node Machine Modes, Constants, Flags, RTL
        !          3196: @section Machine Modes
        !          3197: 
        !          3198: A machine mode describes a size of data object and the representation used
        !          3199: for it.  In the C code, machine modes are represented by an enumeration
        !          3200: type, @code{enum machine_mode}, defined in @file{machmode.def}.  Each RTL
        !          3201: expression has room for a machine mode and so do certain kinds of tree
        !          3202: expressions (declarations and types, to be precise).
        !          3203: 
        !          3204: In debugging dumps and machine descriptions, the machine mode of an RTL
        !          3205: expression is written after the expression code with a colon to separate
        !          3206: them.  The letters @samp{mode} which appear at the end of each machine mode
        !          3207: name are omitted.  For example, @code{(reg:SI 38)} is a @samp{reg}
        !          3208: expression with machine mode @code{SImode}.  If the mode is
        !          3209: @code{VOIDmode}, it is not written at all.
        !          3210: 
        !          3211: Here is a table of machine modes.
        !          3212: 
        !          3213: @table @code
        !          3214: @item QImode
        !          3215: ``Quarter-Integer'' mode represents a single byte treated as an integer.
        !          3216: 
        !          3217: @item HImode
        !          3218: ``Half-Integer'' mode represents a two-byte integer.
        !          3219: 
        !          3220: @item SImode
        !          3221: ``Single Integer'' mode represents a four-byte integer.
        !          3222: 
        !          3223: @item DImode
        !          3224: ``Double Integer'' mode represents an eight-byte integer.
        !          3225: 
        !          3226: @item TImode
        !          3227: ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
        !          3228: 
        !          3229: @item SFmode
        !          3230: ``Single Floating'' mode represents a single-precision (four byte) floating
        !          3231: point number.
        !          3232: 
        !          3233: @item DFmode
        !          3234: ``Double Floating'' mode represents a double-precision (eight byte) floating
        !          3235: point number.
        !          3236: 
        !          3237: @item TFmode
        !          3238: ``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
        !          3239: floating point number.
        !          3240: 
        !          3241: @item BLKmode
        !          3242: ``Block'' mode represents values that are aggregates to which none of
        !          3243: the other modes apply.  In RTL, only memory references can have this mode,
        !          3244: and only if they appear in string-move or vector instructions.  On machines
        !          3245: which have no such instructions, @code{BLKmode} will not appear in RTL.
        !          3246: 
        !          3247: @item VOIDmode
        !          3248: Void mode means the absence of a mode or an unspecified mode.
        !          3249: For example, RTL expressions of code @samp{const_int} have mode
        !          3250: @code{VOIDmode} because they can be taken to have whatever mode the context
        !          3251: requires.  In debugging dumps of RTL, @code{VOIDmode} is expressed by
        !          3252: the absence of any mode.
        !          3253: 
        !          3254: @item EPmode
        !          3255: ``Entry Pointer'' mode is intended to be used for function variables in
        !          3256: Pascal and other block structured languages.  Such values contain
        !          3257: both a function address and a static chain pointer for access to
        !          3258: automatic variables of outer levels.  This mode is only partially
        !          3259: implemented since C does not use it.
        !          3260: 
        !          3261: @item CSImode@r{, @dots{}}
        !          3262: ``Complex Single Integer'' mode stands for a complex number represented
        !          3263: as a pair of @code{SImode} integers.  Any of the integer and floating modes
        !          3264: may have @samp{C} prefixed to its name to obtain a complex number mode.
        !          3265: For example, there are @code{CQImode}, @code{CSFmode}, and @code{CDFmode}.
        !          3266: Since C does not support complex numbers, these machine modes are only
        !          3267: partially implemented.
        !          3268: 
        !          3269: @item BImode
        !          3270: This is the machine mode of a bit-field in a structure.  It is used
        !          3271: only in the syntax tree, never in RTL, and in the syntax tree it appears
        !          3272: only in declaration nodes.  In C, it appears only in @code{FIELD_DECL}
        !          3273: nodes for structure fields defined with a bit size.
        !          3274: @end table
        !          3275: 
        !          3276: The machine description defines @code{Pmode} as a C macro which expands
        !          3277: into the machine mode used for addresses.  Normally this is @code{SImode}.
        !          3278: 
        !          3279: The only modes which a machine description @i{must} support are
        !          3280: @code{QImode}, @code{SImode}, @code{SFmode} and @code{DFmode}.  The
        !          3281: compiler will attempt to use @code{DImode} for two-word structures and
        !          3282: unions, but it would not be hard to program it to avoid this.  Likewise,
        !          3283: you can arrange for the C type @code{short int} to avoid using
        !          3284: @code{HImode}.  In the long term it would be desirable to make the set of
        !          3285: available machine modes machine-dependent and eliminate all assumptions
        !          3286: about specific machine modes or their uses from the machine-independent
        !          3287: code of the compiler.
        !          3288: 
        !          3289: Here are some C macros that relate to machine modes:
        !          3290: 
        !          3291: @table @code
        !          3292: @item GET_MODE (@var{x})
        !          3293: Returns the machine mode of the RTX @var{x}.
        !          3294: 
        !          3295: @item PUT_MODE (@var{x}, @var{newmode})
        !          3296: Alters the machine mode of the RTX @var{x} to be @var{newmode}.
        !          3297: 
        !          3298: @item GET_MODE_SIZE (@var{m})
        !          3299: Returns the size in bytes of a datum of mode @var{m}.
        !          3300: 
        !          3301: @item GET_MODE_BITSIZE (@var{m})
        !          3302: Returns the size in bits of a datum of mode @var{m}.
        !          3303: 
        !          3304: @item GET_MODE_UNIT_SIZE (@var{m})
        !          3305: Returns the size in bits of the subunits of a datum of mode @var{m}.
        !          3306: This is the same as @code{GET_MODE_SIZE} except in the case of
        !          3307: complex modes and @code{EPmode}.  For them, the unit size is the
        !          3308: size of the real or imaginary part, or the size of the function
        !          3309: pointer or the context pointer.
        !          3310: @end table
        !          3311: 
        !          3312: @node Constants, Regs and Memory, Machine Modes, RTL
        !          3313: @section Constant Expression Types
        !          3314: 
        !          3315: The simplest RTL expressions are those that represent constant values.
        !          3316: 
        !          3317: @table @code
        !          3318: @item (const_int @var{i})
        !          3319: This type of expression represents the integer value @var{i}.  @var{i}
        !          3320: is customarily accessed with the macro @code{INTVAL} as in
        !          3321: @code{INTVAL (@var{exp})}, which is equivalent to @code{XINT (@var{exp}, 0)}.
        !          3322: 
        !          3323: There is only one expression object for the integer value zero;
        !          3324: it is the value of the variable @code{const0_rtx}.  Likewise, the
        !          3325: only expression for integer value one is found in @code{const1_rtx}.
        !          3326: Any attempt to create an expression of code @samp{const_int} and
        !          3327: value zero or one will return @code{const0_rtx} or @code{const1_rtx}
        !          3328: as appropriate.
        !          3329: 
        !          3330: @item (const_double:@var{m} @var{i0} @var{i1})
        !          3331: Represents a 64-bit constant or mode @var{m}.  All floating point
        !          3332: constants are represented in this way, and so are 64-bit @code{DImode}
        !          3333: integer constants.
        !          3334: 
        !          3335: The two integers @var{i0} and @var{i1} together contain the bits of
        !          3336: the value.  If the constant is floating point (either single or double
        !          3337: precision), then they represent a @code{double}.  To convert them to a
        !          3338: @code{double}, do
        !          3339: 
        !          3340: @example
        !          3341: union @{ double d; int i[2];@} u;
        !          3342: u.i[0] = XINT (x, 0);
        !          3343: u.i[1] = XINT (x, 1);
        !          3344: @end example
        !          3345: 
        !          3346: @noindent
        !          3347: and then refer to @code{u.d}.
        !          3348: 
        !          3349: The global variables @code{dconst0_rtx} and @code{fconst0_rtx} hold
        !          3350: @samp{const_double} expressions with value 0, in modes @code{DFmode} and
        !          3351: @code{SFmode}, respectively.
        !          3352: 
        !          3353: @item (symbol_ref @var{symbol})
        !          3354: Represents the value of an assembler label for data.  @var{symbol} is
        !          3355: a string that describes the name of the assembler label.  If it starts
        !          3356: with a @samp{*}, the label is the rest of @var{symbol} not including
        !          3357: the @samp{*}.  Otherwise, the label is @var{symbol}, prefixed with
        !          3358: @samp{_}.
        !          3359: 
        !          3360: @item (label_ref @var{label})
        !          3361: Represents the value of an assembler label for code.  It contains one
        !          3362: operand, an expression, which must be a @samp{code_label} that appears
        !          3363: in the instruction sequence to identify the place where the label
        !          3364: should go.
        !          3365: 
        !          3366: The reason for using a distinct expression type for code label
        !          3367: references is so that jump optimization can distinguish them.
        !          3368: 
        !          3369: @item (const @var{exp})
        !          3370: Represents a constant that is the result of an assembly-time
        !          3371: arithmetic computation.  The operand, @var{exp}, is an expression that
        !          3372: contains only constants (@samp{const_int}, @samp{symbol_ref} and
        !          3373: @samp{label_ref} expressions) combined with @samp{plus} and
        !          3374: @samp{minus}.  However, not all combinations are valid, since the
        !          3375: assembler cannot do arbitrary arithmetic on relocatable symbols.
        !          3376: @end table
        !          3377: 
        !          3378: @node Regs and Memory, Arithmetic, Constants, RTL
        !          3379: @section Registers and Memory
        !          3380: 
        !          3381: Here are the RTL expression types for describing access to machine
        !          3382: registers and to main memory.
        !          3383: 
        !          3384: @table @code
        !          3385: @item (reg:@var{m} @var{n})
        !          3386: For small values of the integer @var{n} (less than
        !          3387: @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
        !          3388: register number @var{n}: a @dfn{hard register}.  For larger values of
        !          3389: @var{n}, it stands for a temporary value or @dfn{pseudo register}.
        !          3390: The compiler's strategy is to generate code assuming an unlimited
        !          3391: number of such pseudo registers, and later convert them into hard
        !          3392: registers or into memory references.
        !          3393: 
        !          3394: The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
        !          3395: description, since the number of hard registers on the machine is an
        !          3396: invariant characteristic of the machine.  Note, however, that not
        !          3397: all of the machine registers must be general registers.  All the
        !          3398: machine registers that can be used for storage of data are given
        !          3399: hard register numbers, even those that can be used only in certain
        !          3400: instructions or can hold only certain types of data.
        !          3401: 
        !          3402: Each pseudo register number used in a function's RTL code is
        !          3403: represented by a unique @samp{reg} expression.
        !          3404: 
        !          3405: @var{m} is the machine mode of the reference.  It is necessary because
        !          3406: machines can generally refer to each register in more than one mode.
        !          3407: For example, a register may contain a full word but there may be
        !          3408: instructions to refer to it as a half word or as a single byte, as
        !          3409: well as instructions to refer to it as a floating point number of
        !          3410: various precisions.
        !          3411: 
        !          3412: Even for a register that the machine can access in only one mode,
        !          3413: the mode must always be specified.
        !          3414: 
        !          3415: A hard register may be accessed in various modes throughout one
        !          3416: function, but each pseudo register is given a natural mode
        !          3417: and is accessed only in that mode.  When it is necessary to describe
        !          3418: an access to a pseudo register using a nonnatural mode, a @samp{subreg}
        !          3419: expression is used.
        !          3420: 
        !          3421: A @samp{reg} expression with a machine mode that specifies more than
        !          3422: one word of data may actually stand for several consecutive registers.
        !          3423: If in addition the register number specifies a hardware register, then
        !          3424: it actually represents several consecutive hardware registers starting
        !          3425: with the specified one.
        !          3426: 
        !          3427: Such multi-word hardware register @samp{reg} expressions may not be live
        !          3428: across the boundary of a basic block.  The lifetime analysis pass does not
        !          3429: know how to record properly that several consecutive registers are
        !          3430: actually live there, and therefore register allocation would be confused.
        !          3431: The CSE pass must go out of its way to make sure the situation does
        !          3432: not arise.
        !          3433: 
        !          3434: @item (subreg:@var{m} @var{reg} @var{wordnum})
        !          3435: @samp{subreg} expressions are used to refer to a register in a machine
        !          3436: mode other than its natural one, or to refer to one register of
        !          3437: a multi-word @samp{reg} that actually refers to several registers.
        !          3438: 
        !          3439: Each pseudo-register has a natural mode.  If it is necessary to
        !          3440: operate on it in a different mode---for example, to perform a fullword
        !          3441: move instruction on a pseudo-register that contains a single byte---
        !          3442: the pseudo-register must be enclosed in a @samp{subreg}.  In such
        !          3443: a case, @var{wordnum} is zero.
        !          3444: 
        !          3445: The other use of @samp{subreg} is to extract the individual registers
        !          3446: of a multi-register value.  Machine modes such as @code{DImode} and
        !          3447: @code{EPmode} indicate values longer than a word, values which usually
        !          3448: require two consecutive registers.  To access one of the registers,
        !          3449: use a @samp{subreg} with mode @code{SImode} and a @var{wordnum} that
        !          3450: says which register.
        !          3451: 
        !          3452: The compilation parameter @code{WORDS_BIG_ENDIAN}, if defined, says
        !          3453: that word number zero is the most significant part; otherwise, it is
        !          3454: the least significant part.
        !          3455: 
        !          3456: Between the combiner pass and the reload pass, it is possible to have
        !          3457: a @samp{subreg} which contains a @samp{mem} instead of a @samp{reg} as
        !          3458: its first operand.  The reload pass eliminates these cases by
        !          3459: reloading the @samp{mem} into a suitable register.
        !          3460: 
        !          3461: Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
        !          3462: using a @samp{subreg}.  On some machines the most significant part of a
        !          3463: @code{DFmode} value does not have the same format as a single-precision
        !          3464: floating value.
        !          3465: 
        !          3466: @item (cc0)
        !          3467: This refers to the machine's condition code register.  It has no
        !          3468: operands and may not have a machine mode.  It may be validly used in
        !          3469: only two contexts: as the destination of an assignment (in test and
        !          3470: compare instructions) and in comparison operators comparing against
        !          3471: zero (@samp{const_int} with value zero; that is to say,
        !          3472: @code{const0_rtx}).
        !          3473: 
        !          3474: There is only one expression object of code @samp{cc0}; it is the
        !          3475: value of the variable @code{cc0_rtx}.  Any attempt to create an
        !          3476: expression of code @samp{cc0} will return @code{cc0_rtx}.
        !          3477: 
        !          3478: One special thing about the condition code register is that
        !          3479: instructions can set it implicitly.  On many machines, nearly all
        !          3480: instructions set the condition code based on the value that they
        !          3481: compute or store.  It is not necessary to record these actions
        !          3482: explicitly in the RTL because the machine description includes a
        !          3483: prescription for recognizing the instructions that do so (by means of
        !          3484: the macro @code{NOTICE_UPDATE_CC}).  Only instructions whose sole
        !          3485: purpose is to set the condition code, and instructions that use the
        !          3486: condition code, need mention @code{(cc0)}.
        !          3487: 
        !          3488: @item (pc)
        !          3489: This represents the machine's program counter.  It has no operands and
        !          3490: may not have a machine mode.  @code{(pc)} may be validly used only in
        !          3491: certain specific contexts in jump instructions.
        !          3492: 
        !          3493: There is only one expression object of code @samp{pc}; it is the value
        !          3494: of the variable @code{pc_rtx}.  Any attempt to create an expression of
        !          3495: code @samp{pc} will return @code{pc_rtx}.
        !          3496: 
        !          3497: All instructions that do not jump alter the program counter implicitly
        !          3498: by incrementing it, but there is no need to mention this in the RTL.
        !          3499: 
        !          3500: @item (mem:@var{m} @var{addr})
        !          3501: This RTX represents a reference to main memory at an address
        !          3502: represented by the expression @var{addr}.  @var{m} specifies how large
        !          3503: a unit of memory is accessed.
        !          3504: @end table
        !          3505: 
        !          3506: @node Arithmetic, Comparisons, Regs and Memory, RTL
        !          3507: @section RTL Expressions for Arithmetic
        !          3508: 
        !          3509: @table @code
        !          3510: @item (plus:@var{m} @var{x} @var{y})
        !          3511: Represents the sum of the values represented by @var{x} and @var{y}
        !          3512: carried out in machine mode @var{m}.  This is valid only if
        !          3513: @var{x} and @var{y} both are valid for mode @var{m}.
        !          3514: 
        !          3515: @item (minus:@var{m} @var{x} @var{y})
        !          3516: Like @samp{plus} but represents subtraction.
        !          3517: 
        !          3518: @item (minus @var{x} @var{y})
        !          3519: Represents the result of subtracting @var{y} from @var{x}
        !          3520: for purposes of comparison.  The absence of a machine mode
        !          3521: in the @samp{minus} expression indicates that the result is
        !          3522: computed without overflow, as if with infinite precision.
        !          3523: 
        !          3524: Of course, machines can't really subtract with infinite precision.
        !          3525: However, they can pretend to do so when only the sign of the
        !          3526: result will be used, which is the case when the result is stored
        !          3527: in @code{(cc0)}.  And that is the only way this kind of expression
        !          3528: may validly be used: as a value to be stored in the condition codes.
        !          3529: 
        !          3530: @item (neg:@var{m} @var{x})
        !          3531: Represents the negation (subtraction from zero) of the value
        !          3532: represented by @var{x}, carried out in mode @var{m}.  @var{x} must be
        !          3533: valid for mode @var{m}.
        !          3534: 
        !          3535: @item (mult:@var{m} @var{x} @var{y})
        !          3536: Represents the signed product of the values represented by @var{x} and
        !          3537: @var{y} carried out in machine mode @var{m}.  If
        !          3538: @var{x} and @var{y} are both valid for mode @var{m}, this is ordinary
        !          3539: size-preserving multiplication.  Alternatively, both @var{x} and @var{y}
        !          3540: may be valid for a different, narrower mode.  This represents the
        !          3541: kind of multiplication that generates a product wider than the operands.
        !          3542: Widening multiplication and same-size multiplication are completely
        !          3543: distinct and supported by different machine instructions; machines may
        !          3544: support one but not the other.@refill
        !          3545: 
        !          3546: @samp{mult} may be used for floating point division as well.
        !          3547: Then @var{m} is a floating point machine mode.
        !          3548: 
        !          3549: @item (umult:@var{m} @var{x} @var{y})
        !          3550: Like @samp{mult} but represents unsigned multiplication.  It may be
        !          3551: used in both same-size and widening forms, like @samp{mult}.
        !          3552: @samp{umult} is used only for fixed-point multiplication.
        !          3553: 
        !          3554: @item (div:@var{m} @var{x} @var{y})
        !          3555: Represents the quotient in signed division of @var{x} by @var{y},
        !          3556: carried out in machine mode @var{m}.  If @var{m} is a floating-point
        !          3557: mode, it represents the exact quotient; otherwise, the integerized
        !          3558: quotient.  If @var{x} and @var{y} are both valid for mode @var{m},
        !          3559: this is ordinary size-preserving division.  Some machines have
        !          3560: division instructions in which the operands and quotient widths are
        !          3561: not all the same; such instructions are represented by @samp{div}
        !          3562: expressions in which the machine modes are not all the same.
        !          3563: 
        !          3564: @item (udiv:@var{m} @var{x} @var{y})
        !          3565: Like @samp{div} but represents unsigned division.
        !          3566: 
        !          3567: @item (mod:@var{m} @var{x} @var{y})
        !          3568: @itemx (umod:@var{m} @var{x} @var{y})
        !          3569: Like @samp{div} and @samp{udiv} but represent the remainder instead of
        !          3570: the quotient.
        !          3571: 
        !          3572: @item (not:@var{m} @var{x})
        !          3573: Represents the bitwise complement of the value represented by @var{x},
        !          3574: carried out in mode @var{m}, which must be a fixed-point machine mode.
        !          3575: @var{x} must be valid for mode @var{m}, which must be a fixed-point mode.
        !          3576: 
        !          3577: @item (and:@var{m} @var{x} @var{y})
        !          3578: Represents the bitwise logical-and of the values represented by
        !          3579: @var{x} and @var{y}, carried out in machine mode @var{m}.  This is
        !          3580: valid only if @var{x} and @var{y} both are valid for mode @var{m},
        !          3581: which must be a fixed-point mode.
        !          3582: 
        !          3583: @item (ior:@var{m} @var{x} @var{y})
        !          3584: Represents the bitwise inclusive-or of the values represented by
        !          3585: @var{x} and @var{y}, carried out in machine mode @var{m}.  This is
        !          3586: valid only if @var{x} and @var{y} both are valid for mode @var{m},
        !          3587: which must be a fixed-point mode.
        !          3588: 
        !          3589: @item (xor:@var{m} @var{x} @var{y})
        !          3590: Represents the bitwise exclusive-or of the values represented by
        !          3591: @var{x} and @var{y}, carried out in machine mode @var{m}.  This is
        !          3592: valid only if @var{x} and @var{y} both are valid for mode @var{m},
        !          3593: which must be a fixed-point mode.
        !          3594: 
        !          3595: @item (lshift:@var{m} @var{x} @var{c})
        !          3596: Represents the result of logically shifting @var{x} left by @var{c}
        !          3597: places.  @var{x} must be valid for the mode @var{m}, a fixed-point
        !          3598: machine mode.  @var{c} must be valid for a fixed-point mode;
        !          3599: which mode is determined by the mode called for in the machine
        !          3600: description entry for the left-shift instruction.  For example,
        !          3601: on the Vax, the mode of @var{c} is @code{QImode} regardless of @var{m}.
        !          3602: 
        !          3603: On some machines, negative values of @var{c} may be meaningful; this
        !          3604: is why logical left shift and arithmetic left shift are distinguished.
        !          3605: For example, Vaxes have no right-shift instructions, and right shifts
        !          3606: are represented as left-shift instructions whose counts happen
        !          3607: to be negative constants or else computed (in a previous instruction)
        !          3608: by negation.
        !          3609: 
        !          3610: @item (ashift:@var{m} @var{x} @var{c})
        !          3611: Like @samp{lshift} but for arithmetic left shift.
        !          3612: 
        !          3613: @item (lshiftrt:@var{m} @var{x} @var{c})
        !          3614: @itemx (ashiftrt:@var{m} @var{x} @var{c})
        !          3615: Like @samp{lshift} and @samp{ashift} but for right shift.
        !          3616: 
        !          3617: @item (rotate:@var{m} @var{x} @var{c})
        !          3618: @itemx (rotatert:@var{m} @var{x} @var{c})
        !          3619: Similar but represent left and right rotate.
        !          3620: 
        !          3621: @item (abs:@var{m} @var{x})
        !          3622: Represents the absolute value of @var{x}, computed in mode @var{m}.
        !          3623: @var{x} must be valid for @var{m}.
        !          3624: 
        !          3625: @item (sqrt:@var{m} @var{x})
        !          3626: Represents the square root of @var{x}, computed in mode @var{m}.
        !          3627: @var{x} must be valid for @var{m}.  Most often @var{m} will be
        !          3628: a floating point mode.
        !          3629: 
        !          3630: @item (ffs:@var{m} @var{x})
        !          3631: Represents the one plus the index of the least significant 1-bit in
        !          3632: @var{x}, represented as an integer of mode @var{m}.  (The value is
        !          3633: zero if @var{x} is zero.)  The mode of @var{x} need not be @var{m};
        !          3634: depending on the target machine, various mode combinations may be
        !          3635: valid.
        !          3636: @end table
        !          3637: 
        !          3638: @node Comparisons, Bit Fields, Arithmetic, RTL
        !          3639: @section Comparison Operations
        !          3640: 
        !          3641: Comparison operators test a relation on two operands and are considered to
        !          3642: represent the value 1 if the relation holds, or zero if it does not.  The
        !          3643: mode of the comparison is determined by the operands; they must both be
        !          3644: valid for a common machine mode.  A comparison with both operands constant
        !          3645: would be invalid as the machine mode could not be deduced from it, but such
        !          3646: a comparison should never exist in RTL due to constant folding.
        !          3647: 
        !          3648: Inequality comparisons come in two flavors, signed and unsigned.  Thus,
        !          3649: there are distinct expression codes @samp{gt} and @samp{gtu} for signed and
        !          3650: unsigned greater-than.  These can produce different results for the same
        !          3651: pair of integer values: for example, 1 is signed greater-than -1 but not
        !          3652: unsigned greater-than, because -1 when regarded as unsigned is actually
        !          3653: @code{0xffffffff} which is greater than 1.
        !          3654: 
        !          3655: The signed comparisons are also used for floating point values.  Floating
        !          3656: point comparisons are distinguished by the machine modes of the operands.
        !          3657: 
        !          3658: The comparison operators may be used to compare the condition codes
        !          3659: @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}.  Such a
        !          3660: construct actually refers to the result of the preceding instruction in
        !          3661: which the condition codes were set.  The above example stands for 1 if the
        !          3662: condition codes were set to say ``zero'' or ``equal'', 0 otherwise.
        !          3663: Although the same comparison operators are used for this as may be used in
        !          3664: other contexts on actual data, no confusion can result since the machine
        !          3665: description would never allow both kinds of uses in the same context.
        !          3666: 
        !          3667: @table @code
        !          3668: @item (eq @var{x} @var{y})
        !          3669: 1 if the values represented by @var{x} and @var{y} are equal,
        !          3670: otherwise 0.
        !          3671: 
        !          3672: @item (ne @var{x} @var{y})
        !          3673: 1 if the values represented by @var{x} and @var{y} are not equal,
        !          3674: otherwise 0.
        !          3675: 
        !          3676: @item (gt @var{x} @var{y})
        !          3677: 1 if the @var{x} is greater than @var{y}.  If they are fixed-point,
        !          3678: the comparison is done in a signed sense.
        !          3679: 
        !          3680: @item (gtu @var{x} @var{y})
        !          3681: Like @samp{gt} but does unsigned comparison, on fixed-point numbers only.
        !          3682: 
        !          3683: @item (lt @var{x} @var{y})
        !          3684: @item (ltu @var{x} @var{y})
        !          3685: Like @samp{gt} and @samp{gtu} but test for ``less than''.
        !          3686: 
        !          3687: @item (ge @var{x} @var{y})
        !          3688: @item (geu @var{x} @var{y})
        !          3689: Like @samp{gt} and @samp{gtu} but test for ``greater than or equal''.
        !          3690: 
        !          3691: @item (le @var{x} @var{y})
        !          3692: @item (leu @var{x} @var{y})
        !          3693: Like @samp{gt} and @samp{gtu} but test for ``less than or equal''.
        !          3694: 
        !          3695: @item (if_then_else @var{cond} @var{then} @var{else})
        !          3696: This is not a comparison operation but is listed here because it is
        !          3697: always used in conjunction with a comparison operation.  To be
        !          3698: precise, @var{cond} is a comparison expression.  This expression
        !          3699: represents a choice, according to @var{cond}, between the value
        !          3700: represented by @var{then} and the one represented by @var{else}.
        !          3701: 
        !          3702: On most machines, @samp{if_then_else} expressions are valid only
        !          3703: to express conditional jumps.
        !          3704: @end table
        !          3705: 
        !          3706: @node Bit Fields, Conversions, Comparisons, RTL
        !          3707: @section Bit-fields
        !          3708: 
        !          3709: Special expression codes exist to represent bit-field instructions.
        !          3710: These types of expressions are lvalues in RTL; they may appear
        !          3711: on the left side of a assignment, indicating insertion of a value
        !          3712: into the specified bit field.
        !          3713: 
        !          3714: @table @code
        !          3715: @item (sign_extract:SI @var{loc} @var{size} @var{pos})
        !          3716: This represents a reference to a sign-extended bit-field contained or
        !          3717: starting in @var{loc} (a memory or register reference).  The bit field
        !          3718: is @var{size} bits wide and starts at bit @var{pos}.  The compilation
        !          3719: option @code{BITS_BIG_ENDIAN} says which end of the memory unit
        !          3720: @var{pos} counts from.
        !          3721: 
        !          3722: Which machine modes are valid for @var{loc} depends on the machine,
        !          3723: but typically @var{loc} should be a single byte when in memory
        !          3724: or a full word in a register.
        !          3725: 
        !          3726: @item (zero_extract:SI @var{loc} @var{size} @var{pos})
        !          3727: Like @samp{sign_extract} but refers to an unsigned or zero-extended
        !          3728: bit field.  The same sequence of bits are extracted, but they
        !          3729: are filled to an entire word with zeros instead of by sign-extension.
        !          3730: @end table
        !          3731: 
        !          3732: @node Conversions, RTL Declarations, Bit Fields, RTL
        !          3733: @section Conversions
        !          3734: 
        !          3735: All conversions between machine modes must be represented by
        !          3736: explicit conversion operations.  For example, an expression
        !          3737: which is the sum of a byte and a full word cannot be written as
        !          3738: @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @samp{plus}
        !          3739: operation requires two operands of the same machine mode.
        !          3740: Therefore, the byte-sized operand is enclosed in a conversion
        !          3741: operation, as in
        !          3742: 
        !          3743: @example
        !          3744: (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
        !          3745: @end example
        !          3746: 
        !          3747: The conversion operation is not a mere placeholder, because there
        !          3748: may be more than one way of converting from a given starting mode
        !          3749: to the desired final mode.  The conversion operation code says how
        !          3750: to do it.
        !          3751: 
        !          3752: @table @code
        !          3753: @item (sign_extend:@var{m} @var{x})
        !          3754: Represents the result of sign-extending the value @var{x}
        !          3755: to machine mode @var{m}.  @var{m} must be a fixed-point mode
        !          3756: and @var{x} a fixed-point value of a mode narrower than @var{m}.
        !          3757: 
        !          3758: @item (zero_extend:@var{m} @var{x})
        !          3759: Represents the result of zero-extending the value @var{x}
        !          3760: to machine mode @var{m}.  @var{m} must be a fixed-point mode
        !          3761: and @var{x} a fixed-point value of a mode narrower than @var{m}.
        !          3762: 
        !          3763: @item (float_extend:@var{m} @var{x})
        !          3764: Represents the result of extending the value @var{x}
        !          3765: to machine mode @var{m}.  @var{m} must be a floating point mode
        !          3766: and @var{x} a floating point value of a mode narrower than @var{m}.
        !          3767: 
        !          3768: @item (truncate:@var{m} @var{x})
        !          3769: Represents the result of truncating the value @var{x}
        !          3770: to machine mode @var{m}.  @var{m} must be a fixed-point mode
        !          3771: and @var{x} a fixed-point value of a mode wider than @var{m}.
        !          3772: 
        !          3773: @item (float_truncate:@var{m} @var{x})
        !          3774: Represents the result of truncating the value @var{x}
        !          3775: to machine mode @var{m}.  @var{m} must be a floating point mode
        !          3776: and @var{x} a floating point value of a mode wider than @var{m}.
        !          3777: 
        !          3778: @item (float:@var{m} @var{x})
        !          3779: Represents the result of converting fixed point value @var{x},
        !          3780: regarded as signed, to floating point mode @var{m}.
        !          3781: 
        !          3782: @item (unsigned_float:@var{m} @var{x})
        !          3783: Represents the result of converting fixed point value @var{x},
        !          3784: regarded as unsigned, to floating point mode @var{m}.
        !          3785: 
        !          3786: @item (fix:@var{m} @var{x})
        !          3787: When @var{m} is a fixed point mode, represents the result of
        !          3788: converting floating point value @var{x} to mode @var{m}, regarded as
        !          3789: signed.  How rounding is done is not specified, so this operation may
        !          3790: be used validly in compiling C code only for integer-valued operands.
        !          3791: 
        !          3792: @item (unsigned_fix:@var{m} @var{x})
        !          3793: Represents the result of converting floating point value @var{x} to
        !          3794: fixed point mode @var{m}, regarded as unsigned.  How rounding is done
        !          3795: is not specified.
        !          3796: 
        !          3797: @item (fix:@var{m} @var{x})
        !          3798: When @var{m} is a floating point mode, represents the result of
        !          3799: converting floating point value @var{x} (valid for mode @var{m}) to an
        !          3800: integer, still represented in floating point mode @var{m}, by rounding
        !          3801: towards zero.
        !          3802: @end table
        !          3803: 
        !          3804: @node RTL Declarations, Side Effects, Conversions, RTL
        !          3805: @section Declarations
        !          3806: 
        !          3807: Declaration expression codes do not represent arithmetic operations
        !          3808: but rather state assertions about their operands.
        !          3809: 
        !          3810: @table @code
        !          3811: @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
        !          3812: This expression code is used in only one context: operand 0 of a
        !          3813: @samp{set} expression.  In addition, the operand of this expression
        !          3814: must be a @samp{subreg} expression.
        !          3815: 
        !          3816: The presence of @samp{strict_low_part} says that the part of the
        !          3817: register which is meaningful in mode @var{n}, but is not part of
        !          3818: mode @var{m}, is not to be altered.  Normally, an assignment to such
        !          3819: a subreg is allowed to have undefined effects on the rest of the
        !          3820: register when @var{m} is less than a word.
        !          3821: @end table
        !          3822: 
        !          3823: @node Side Effects, Incdec, RTL Declarations, RTL
        !          3824: @section Side Effect Expressions
        !          3825: 
        !          3826: The expression codes described so far represent values, not actions.
        !          3827: But machine instructions never produce values; they are meaningful
        !          3828: only for their side effects on the state of the machine.  Special
        !          3829: expression codes are used to represent side effects.
        !          3830: 
        !          3831: The body of an instruction is always one of these side effect codes;
        !          3832: the codes described above, which represent values, appear only as
        !          3833: the operands of these.
        !          3834: 
        !          3835: @table @code
        !          3836: @item (set @var{lval} @var{x})
        !          3837: Represents the action of storing the value of @var{x} into the place
        !          3838: represented by @var{lval}.  @var{lval} must be an expression
        !          3839: representing a place that can be stored in: @samp{reg} (or
        !          3840: @samp{subreg} or @samp{strict_low_part}), @samp{mem}, @samp{pc} or
        !          3841: @samp{cc0}.@refill
        !          3842: 
        !          3843: If @var{lval} is a @samp{reg}, @samp{subreg} or @samp{mem}, it has a
        !          3844: machine mode; then @var{x} must be valid for that mode.@refill
        !          3845: 
        !          3846: If @var{lval} is a @samp{reg} whose machine mode is less than the full
        !          3847: width of the register, then it means that the part of the register
        !          3848: specified by the machine mode is given the specified value and the
        !          3849: rest of the register receives an undefined value.  Likewise, if
        !          3850: @var{lval} is a @samp{subreg} whose machine mode is narrower than
        !          3851: @code{SImode}, the rest of the register can be changed in an undefined way.
        !          3852: 
        !          3853: If @var{lval} is a @samp{strict_low_part} of a @samp{subreg}, then the
        !          3854: part of the register specified by the machine mode of the
        !          3855: @samp{subreg} is given the value @var{x} and the rest of the register
        !          3856: is not changed.@refill
        !          3857: 
        !          3858: If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
        !          3859: have any mode.  This represents a ``test'' or ``compare'' instruction.@refill
        !          3860: 
        !          3861: If @var{lval} is @code{(pc)}, we have a jump instruction, and the
        !          3862: possibilities for @var{x} are very limited.  It may be a
        !          3863: @samp{label_ref} expression (unconditional jump).  It may be an
        !          3864: @samp{if_then_else} (conditional jump), in which case either the
        !          3865: second or the third operand must be @code{(pc)} (for the case which
        !          3866: does not jump) and the other of the two must be a @samp{label_ref}
        !          3867: (for the case which does jump).  @var{x} may also be a @samp{mem} or
        !          3868: @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @samp{reg} or a
        !          3869: @samp{mem}; these unusual patterns are used to represent jumps through
        !          3870: branch tables.@refill
        !          3871: 
        !          3872: @item (return)
        !          3873: Represents a return from the current function, on machines where this
        !          3874: can be done with one instruction, such as Vaxes.  On machines where a
        !          3875: multi-instruction ``epilogue'' must be executed in order to return
        !          3876: from the function, returning is done by jumping to a label which
        !          3877: precedes the epilogue, and the @samp{return} expression code is never
        !          3878: used.
        !          3879: 
        !          3880: @item (call @var{function} @var{nargs})
        !          3881: Represents a function call.  @var{function} is a @samp{mem} expression
        !          3882: whose address is the address of the function to be called.
        !          3883: @var{nargs} is an expression which can be used for two purposes: on
        !          3884: some machines it represents the number of bytes of stack argument; on
        !          3885: others, it represents the number of argument registers.
        !          3886: 
        !          3887: Each machine has a standard machine mode which @var{function} must
        !          3888: have.  The machine description defines macro @code{FUNCTION_MODE} to
        !          3889: expand into the requisite mode name.  The purpose of this mode is to
        !          3890: specify what kind of addressing is allowed, on machines where the
        !          3891: allowed kinds of addressing depend on the machine mode being
        !          3892: addressed.
        !          3893: 
        !          3894: @item (clobber @var{x})
        !          3895: Represents the storing or possible storing of an unpredictable,
        !          3896: undescribed value into @var{x}, which must be a @samp{reg} or
        !          3897: @samp{mem} expression.
        !          3898: 
        !          3899: One place this is used is in string instructions that store standard
        !          3900: values into particular hard registers.  It may not be worth the
        !          3901: trouble to describe the values that are stored, but it is essential to
        !          3902: inform the compiler that the registers will be altered, lest it
        !          3903: attempt to keep data in them across the string instruction.
        !          3904: 
        !          3905: @var{x} may also be null---a null C pointer, no expression at all.
        !          3906: Such a @code{(clobber (null))} expression means that all memory
        !          3907: locations must be presumed clobbered.
        !          3908: 
        !          3909: Note that the machine description classifies certain hard registers as
        !          3910: ``call-clobbered''.  All function call instructions are assumed by
        !          3911: default to clobber these registers, so there is no need to use
        !          3912: @samp{clobber} expressions to indicate this fact.  Also, each function
        !          3913: call is assumed to have the potential to alter any memory location.
        !          3914: 
        !          3915: @item (use @var{x})
        !          3916: Represents the use of the value of @var{x}.  It indicates that the
        !          3917: value in @var{x} at this point in the program is needed, even though
        !          3918: it may not be apparent why this is so.  Therefore, the compiler will
        !          3919: not attempt to delete instructions whose only effect is to store a
        !          3920: value in @var{x}.  @var{x} must be a @samp{reg} expression.
        !          3921: 
        !          3922: @item (parallel [@var{x0} @var{x1} @dots{}])
        !          3923: Represents several side effects performed in parallel.  The square
        !          3924: brackets stand for a vector; the operand of @samp{parallel} is a
        !          3925: vector of expressions.  @var{x0}, @var{x1} and so on are individual
        !          3926: side effects---expressions of code @samp{set}, @samp{call},
        !          3927: @samp{return}, @samp{clobber} or @samp{use}.@refill
        !          3928: 
        !          3929: ``In parallel'' means that first all the values used in the individual
        !          3930: side-effects are computed, and second all the actual side-effects are
        !          3931: performed.  For example,
        !          3932: 
        !          3933: @example
        !          3934: (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
        !          3935:            (set (mem:SI (reg:SI 1)) (reg:SI 1))])
        !          3936: @end example
        !          3937: 
        !          3938: @noindent
        !          3939: says unambiguously that the values of hard register 1 and the memory
        !          3940: location addressed by it are interchanged.  In both places where
        !          3941: @code{(reg:SI 1)} appears as a memory address it refers to the value
        !          3942: in register 1 @emph{before} the execution of the instruction.
        !          3943: 
        !          3944: Peephole optimization, which takes place in the last jump-optimization
        !          3945: pass, can produce insns whose patterns consist of a @samp{parallel}
        !          3946: whose elements are the operands needed to output the resulting
        !          3947: assembler code--often @samp{reg}, @samp{mem} or constant expressions.
        !          3948: This would not be well-formed RTL at any other stage in compilation,
        !          3949: but it is ok then because no further optimization remains to be done.
        !          3950: However, the definition of the macro @code{NOTICE_UPDATE_CC} may need
        !          3951: to deal with such insns.
        !          3952: 
        !          3953: @item (sequence [@var{insns} @dots{}])
        !          3954: Represents a sequence of insns.  Each of the @var{insns} that appears
        !          3955: in the vector is suitable for appearing in the chain of insns, so it
        !          3956: must be an @samp{insn}, @samp{jump_insn}, @samp{call_insn},
        !          3957: @samp{code_label}, @samp{barrier} or @samp{note}.
        !          3958: 
        !          3959: A @samp{sequence} RTX never appears in an actual insn.  It represents
        !          3960: the sequence of insns that result from a @samp{define_expand}
        !          3961: @emph{before} those insns are passed to @code{emit_insn} to insert
        !          3962: them in the chain of insns.  When actually inserted, the individual
        !          3963: sub-insns are separated out and the @samp{sequence} is forgotten.
        !          3964: @end table
        !          3965: 
        !          3966: Three expression codes appear in place of a side effect, as the body of an
        !          3967: insn, though strictly speaking they do not describe side effects as such:
        !          3968: 
        !          3969: @table @code
        !          3970: @item (asm_input @var{s})
        !          3971: Represents literal assembler code as described by the string @var{s}.
        !          3972: 
        !          3973: @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
        !          3974: Represents a table of jump addresses.  The vector elements @var{lr0},
        !          3975: etc., are @samp{label_ref} expressions.  The mode @var{m} specifies
        !          3976: how much space is given to each address; normally @var{m} would be
        !          3977: @code{Pmode}.
        !          3978: 
        !          3979: @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
        !          3980: Represents a table of jump addresses expressed as offsets from
        !          3981: @var{base}.  The vector elements @var{lr0}, etc., are @samp{label_ref}
        !          3982: expressions and so is @var{base}.  The mode @var{m} specifies how much
        !          3983: space is given to each address-difference.@refill
        !          3984: @end table
        !          3985: 
        !          3986: @node Incdec, Assembler, Side Effects, RTL
        !          3987: @section Embedded Side-Effects on Addresses
        !          3988: 
        !          3989: Four special side-effect expression codes appear as memory addresses.
        !          3990: 
        !          3991: @table @code
        !          3992: @item (pre_dec:@var{m} @var{x})
        !          3993: Represents the side effect of decrementing @var{x} by a standard
        !          3994: amount and represents also the value that @var{x} has after being
        !          3995: decremented.  @var{x} must be a @samp{reg} or @samp{mem}, but most
        !          3996: machines allow only a @samp{reg}.  @var{m} must be the machine mode
        !          3997: for pointers on the machine in use.  The amount @var{x} is decremented
        !          3998: by is the length in bytes of the machine mode of the containing memory
        !          3999: reference of which this expression serves as the address.  Here is an
        !          4000: example of its use:@refill
        !          4001: 
        !          4002: @example
        !          4003: (mem:DF (pre_dec:SI (reg:SI 39)))
        !          4004: @end example
        !          4005: 
        !          4006: @noindent
        !          4007: This says to decrement pseudo register 39 by the length of a @code{DFmode}
        !          4008: value and use the result to address a @code{DFmode} value.
        !          4009: 
        !          4010: @item (pre_inc:@var{m} @var{x})
        !          4011: Similar, but specifies incrementing @var{x} instead of decrementing it.
        !          4012: 
        !          4013: @item (post_dec:@var{m} @var{x})
        !          4014: Represents the same side effect as @samp{pre_decrement} but a different
        !          4015: value.  The value represented here is the value @var{x} has @i{before}
        !          4016: being decremented.
        !          4017: 
        !          4018: @item (post_inc:@var{m} @var{x})
        !          4019: Similar, but specifies incrementing @var{x} instead of decrementing it.
        !          4020: @end table
        !          4021: 
        !          4022: These embedded side effect expressions must be used with care.  Instruction
        !          4023: patterns may not use them.  Until the @samp{flow} pass of the compiler,
        !          4024: they may occur only to represent pushes onto the stack.  The @samp{flow}
        !          4025: pass finds cases where registers are incremented or decremented in one
        !          4026: instruction and used as an address shortly before or after; these cases are
        !          4027: then transformed to use pre- or post-increment or -decrement.
        !          4028: 
        !          4029: Explicit popping of the stack could be represented with these embedded
        !          4030: side effect operators, but that would not be safe; the instruction
        !          4031: combination pass could move the popping past pushes, thus changing
        !          4032: the meaning of the code.
        !          4033: 
        !          4034: An instruction that can be represented with an embedded side effect
        !          4035: could also be represented using @samp{parallel} containing an additional
        !          4036: @samp{set} to describe how the address register is altered.  This is not
        !          4037: done because machines that allow these operations at all typically
        !          4038: allow them wherever a memory address is called for.  Describing them as
        !          4039: additional parallel stores would require doubling the number of entries
        !          4040: in the machine description.
        !          4041: 
        !          4042: @node Assembler, Insns, IncDec, RTL
        !          4043: @section Assembler Instructions as Expressions
        !          4044: 
        !          4045: The RTX code @samp{asm_operands} represents a value produced by a
        !          4046: user-specified assembler instruction.  It is used to represent
        !          4047: an @code{asm} statement with arguments.  An @code{asm} statement with
        !          4048: a single output operand, like this:
        !          4049: 
        !          4050: @example
        !          4051: asm ("foo %1,%2,%0" : "a" (outputvar) : "g" (x + y), "di" (*z));
        !          4052: @end example
        !          4053: 
        !          4054: @noindent
        !          4055: is represented using a single @samp{asm_operands} RTX which represents
        !          4056: the value that is stored in @code{outputvar}:
        !          4057: 
        !          4058: @example
        !          4059: (set @var{rtx-for-outputvar}
        !          4060:      (asm_operands "foo %1,%2,%0" "a" 0
        !          4061:                    [@var{rtx-for-addition-result} @var{rtx-for-*z}]
        !          4062:                    [(asm_input:@var{m1} "g")
        !          4063:                     (asm_input:@var{m2} "di")]))
        !          4064: @end example
        !          4065: 
        !          4066: @noindent
        !          4067: Here the operands of the @samp{asm_operands} RTX are the assembler
        !          4068: template string, the output-operand's constraint, the index-number of the
        !          4069: output operand among the output operands specified, a vector of input
        !          4070: operand RTX's, and a vector of input-operand modes and constraints.  The
        !          4071: mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
        !          4072: @code{*z}.
        !          4073: 
        !          4074: When an @code{asm} statement has multiple output values, its insn has
        !          4075: several such @samp{set} RTX's inside of a @samp{parallel}.  Each @samp{set}
        !          4076: contains a @samp{asm_operands}; all of these share the same assembler
        !          4077: template and vectors, but each contains the constraint for the respective
        !          4078: output operand.  They are also distinguished by the output-operand index
        !          4079: number, which is 0, 1, @dots{} for successive output operands.
        !          4080: 
        !          4081: @node Insns, Calls, Assembler, RTL
        !          4082: @section Insns
        !          4083: 
        !          4084: The RTL representation of the code for a function is a doubly-linked
        !          4085: chain of objects called @dfn{insns}.  Insns are expressions with
        !          4086: special codes that are used for no other purpose.  Some insns are
        !          4087: actual instructions; others represent dispatch tables for @code{switch}
        !          4088: statements; others represent labels to jump to or various sorts of
        !          4089: declarative information.
        !          4090: 
        !          4091: In addition to its own specific data, each insn must have a unique id-number
        !          4092: that distinguishes it from all other insns in the current function, and
        !          4093: chain pointers to the preceding and following insns.  These three fields
        !          4094: occupy the same position in every insn, independent of the expression code
        !          4095: of the insn.  They could be accessed with @code{XEXP} and @code{XINT},
        !          4096: but instead three special macros are always used:
        !          4097: 
        !          4098: @table @code
        !          4099: @item INSN_UID (@var{i})
        !          4100: Accesses the unique id of insn @var{i}.
        !          4101: 
        !          4102: @item PREV_INSN (@var{i})
        !          4103: Accesses the chain pointer to the insn preceding @var{i}.
        !          4104: If @var{i} is the first insn, this is a null pointer.
        !          4105: 
        !          4106: @item NEXT_INSN (@var{i})
        !          4107: Accesses the chain pointer to the insn following @var{i}.
        !          4108: If @var{i} is the last insn, this is a null pointer.
        !          4109: @end table
        !          4110: 
        !          4111: The @code{NEXT_INSN} and @code{PREV_INSN} pointers must always
        !          4112: correspond: if @var{i} is not the first insn,
        !          4113: 
        !          4114: @example
        !          4115: NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
        !          4116: @end example
        !          4117: 
        !          4118: @noindent
        !          4119: is always true.
        !          4120: 
        !          4121: Every insn has one of the following six expression codes:
        !          4122: 
        !          4123: @table @samp
        !          4124: @item insn
        !          4125: The expression code @samp{insn} is used for instructions that do not jump
        !          4126: and do not do function calls.  Insns with code @samp{insn} have four
        !          4127: additional fields beyond the three mandatory ones listed above.
        !          4128: These four are described in a table below.
        !          4129: 
        !          4130: @item jump_insn
        !          4131: The expression code @samp{jump_insn} is used for instructions that may jump
        !          4132: (or, more generally, may contain @samp{label_ref} expressions).
        !          4133: @samp{jump_insn} insns have the same extra fields as @samp{insn} insns,
        !          4134: accessed in the same way.
        !          4135: 
        !          4136: @item call_insn
        !          4137: The expression code @samp{call_insn} is used for instructions that may do
        !          4138: function calls.  It is important to distinguish these instructions because
        !          4139: they imply that certain registers and memory locations may be altered
        !          4140: unpredictably.
        !          4141: 
        !          4142: @samp{call_insn} insns have the same extra fields as @samp{insn} insns,
        !          4143: accessed in the same way.
        !          4144: 
        !          4145: @item code_label
        !          4146: A @samp{code_label} insn represents a label that a jump insn can jump to.
        !          4147: It contains one special field of data in addition to the three standard ones.
        !          4148: It is used to hold the @dfn{label number}, a number that identifies this
        !          4149: label uniquely among all the labels in the compilation (not just in the
        !          4150: current function).  Ultimately, the label is represented in the assembler
        !          4151: output as an assembler label @samp{L@var{n}} where @var{n} is the label number.
        !          4152: 
        !          4153: @item barrier
        !          4154: Barriers are placed in the instruction stream after unconditional
        !          4155: jump instructions to indicate that the jumps are unconditional.
        !          4156: They contain no information beyond the three standard fields.
        !          4157: 
        !          4158: @item note
        !          4159: @samp{note} insns are used to represent additional debugging and
        !          4160: declarative information.  They contain two nonstandard fields, an
        !          4161: integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
        !          4162: string accessed with @code{NOTE_SOURCE_FILE}.
        !          4163: 
        !          4164: If @code{NOTE_LINE_NUMBER} is positive, the note represents the
        !          4165: position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
        !          4166: that the line came from.  These notes control generation of line
        !          4167: number data in the assembler output.
        !          4168: 
        !          4169: Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
        !          4170: code with one of the following values (and @code{NOTE_SOURCE_FILE}
        !          4171: must contain a null pointer):
        !          4172: 
        !          4173: @table @code
        !          4174: @item NOTE_INSN_DELETED
        !          4175: Such a note is completely ignorable.  Some passes of the compiler
        !          4176: delete insns by altering them into notes of this kind.
        !          4177: 
        !          4178: @item NOTE_INSN_BLOCK_BEG
        !          4179: @itemx NOTE_INSN_BLOCK_END
        !          4180: These types of notes indicate the position of the beginning and end
        !          4181: of a level of scoping of variable names.  They control the output
        !          4182: of debugging information.
        !          4183: 
        !          4184: @item NOTE_INSN_LOOP_BEG
        !          4185: @itemx NOTE_INSN_LOOP_END
        !          4186: These types of notes indicate the position of the beginning and end
        !          4187: of a @code{while} or @code{for} loop.  They enable the loop optimizer
        !          4188: to find loops quickly.
        !          4189: @end table
        !          4190: @end table
        !          4191: 
        !          4192: Here is a table of the extra fields of @samp{insn}, @samp{jump_insn}
        !          4193: and @samp{call_insn} insns:
        !          4194: 
        !          4195: @table @code
        !          4196: @item PATTERN (@var{i})
        !          4197: An expression for the side effect performed by this insn.
        !          4198: 
        !          4199: @item REG_NOTES (@var{i})
        !          4200: A list (chain of @samp{expr_list} expressions) giving information
        !          4201: about the usage of registers in this insn.  This list is set up by the
        !          4202: flow analysis pass; it is a null pointer until then.
        !          4203: 
        !          4204: @item LOG_LINKS (@var{i})
        !          4205: A list (chain of @samp{insn_list} expressions) of previous ``related''
        !          4206: insns: insns which store into registers values that are used for the
        !          4207: first time in this insn.  (An additional constraint is that neither a
        !          4208: jump nor a label may come between the related insns).  This list is
        !          4209: set up by the flow analysis pass; it is a null pointer until then.
        !          4210: 
        !          4211: @item INSN_CODE (@var{i})
        !          4212: An integer that says which pattern in the machine description matches
        !          4213: this insn, or -1 if the matching has not yet been attempted.
        !          4214: 
        !          4215: Such matching is never attempted and this field is not used on an insn
        !          4216: whose pattern consists of a single @samp{use}, @samp{clobber},
        !          4217: @samp{asm}, @samp{addr_vec} or @samp{addr_diff_vec} expression.
        !          4218: @end table
        !          4219: 
        !          4220: The @code{LOG_LINKS} field of an insn is a chain of @samp{insn_list}
        !          4221: expressions.  Each of these has two operands: the first is an insn,
        !          4222: and the second is another @samp{insn_list} expression (the next one in
        !          4223: the chain).  The last @samp{insn_list} in the chain has a null pointer
        !          4224: as second operand.  The significant thing about the chain is which
        !          4225: insns appear in it (as first operands of @samp{insn_list}
        !          4226: expressions).  Their order is not significant.
        !          4227: 
        !          4228: The @code{REG_NOTES} field of an insn is a similar chain but of
        !          4229: @samp{expr_list} expressions instead of @samp{insn_list}.  There are four
        !          4230: kinds of register notes, which are distinguished by the machine mode of the
        !          4231: @samp{expr_list}, which a register note is really understood as being an
        !          4232: @code{enum reg_note}.  The first operand @var{op} of the @samp{expr_list}
        !          4233: is data whose meaning depends on the kind of note.  Here are the four
        !          4234: kinds:
        !          4235: 
        !          4236: @table @code
        !          4237: @item REG_DEAD
        !          4238: The register @var{op} dies in this insn; that is to say, altering the
        !          4239: value immediately after this insn would not affect the future behavior
        !          4240: of the program.
        !          4241: 
        !          4242: @item REG_INC
        !          4243: The register @var{op} is incremented (or decremented; at this level
        !          4244: there is no distinction) by an embedded side effect inside this insn.
        !          4245: This means it appears in a @code{POST_INC}, @code{PRE_INC},
        !          4246: @code{POST_DEC} or @code{PRE_DEC} RTX.
        !          4247: 
        !          4248: @item REG_EQUIV
        !          4249: The register that is set by this insn will be equal to @var{op} at run
        !          4250: time, and could validly be replaced in all its occurrences by
        !          4251: @var{op}.  (``Validly'' here refers to the data flow of the program;
        !          4252: simple replacement may make some insns invalid.)
        !          4253: 
        !          4254: The value which the insn explicitly copies into the register may look
        !          4255: different from @var{op}, but they will be equal at run time.
        !          4256: 
        !          4257: For example, when a constant is loaded into a register that is never
        !          4258: assigned any other value, this kind of note is used.
        !          4259: 
        !          4260: When a parameter is copied into a pseudo-register at entry to a function,
        !          4261: a note of this kind records that the register is equivalent to the stack
        !          4262: slot where the parameter was passed.  Although in this case the register
        !          4263: may be set by other insns, it is still valid to replace the register
        !          4264: by the stack slot throughout the function.
        !          4265: 
        !          4266: @item REG_EQUAL
        !          4267: The register that is set by this insn will be equal to @var{op} at run
        !          4268: time at the end of this insn (but not necessarily elsewhere in the
        !          4269: function).
        !          4270: 
        !          4271: The RTX @var{op} is typically an arithmetic expression.  For example,
        !          4272: when a sequence of insns such as a library call is used to perform an
        !          4273: arithmetic operation, this kind of note is attached to the insn that
        !          4274: produces or copies the final value.  It tells the CSE pass how to
        !          4275: think of that value.
        !          4276: 
        !          4277: @item REG_RETVAL
        !          4278: This insn copies the value of a library call, and @var{op} is the
        !          4279: first insn that was generated to set up the arguments for the library
        !          4280: call.
        !          4281: 
        !          4282: Flow analysis uses this note to delete all of a library call whose
        !          4283: result is dead.
        !          4284: 
        !          4285: @item REG_WAS_0
        !          4286: The register @var{op} contained zero before this insn.  You can rely
        !          4287: on this note if it is present; its absence implies nothing.
        !          4288: 
        !          4289: @item REG_LIBCALL
        !          4290: This is the inverse of @code{REG_RETVAL}: it is placed on the first
        !          4291: insn of a library call, and it points to the last one.
        !          4292: 
        !          4293: Loop optimization uses this note to move an entire library call out
        !          4294: of a loop when its value is constant.
        !          4295: 
        !          4296: @item REG_NONNEG
        !          4297: The register @var{op} is known to have nonnegative value when this
        !          4298: insn is reached.
        !          4299: @end table
        !          4300: 
        !          4301: (The only difference between the expression codes @samp{insn_list} and
        !          4302: @samp{expr_list} is that the first operand of an @samp{insn_list} is
        !          4303: assumed to be an insn and is printed in debugging dumps as the insn's
        !          4304: unique id; the first operand of an @samp{expr_list} is printed in the
        !          4305: ordinary way as an expression.)
        !          4306: 
        !          4307: @node Calls, Sharing, Insns, RTL
        !          4308: @section RTL Representation of Function-Call Insns
        !          4309: 
        !          4310: Insns that call subroutines have the RTL expression code @samp{call_insn}.
        !          4311: These insns must satisfy special rules, and their bodies must use a special
        !          4312: RTL expression code, @samp{call}.
        !          4313: 
        !          4314: A @samp{call} expression has two operands, as follows:
        !          4315: 
        !          4316: @example
        !          4317: (call @var{nbytes} (mem:@var{fm} @var{addr}))
        !          4318: @end example
        !          4319: 
        !          4320: @noindent
        !          4321: Here @var{nbytes} is an operand that represents the number of bytes of
        !          4322: argument data being passed to the subroutine, @var{fm} is a machine mode
        !          4323: (which must equal as the definition of the @code{FUNCTION_MODE} macro in
        !          4324: the machine description) and @var{addr} represents the address of the
        !          4325: subroutine.
        !          4326: 
        !          4327: For a subroutine that returns no value, the @samp{call} RTX as shown above
        !          4328: is the entire body of the insn.
        !          4329: 
        !          4330: For a subroutine that returns a value whose mode is not @code{BLKmode},
        !          4331: the value is returned in a hard register.  If this register's number is
        !          4332: @var{r}, then the body of the call insn looks like this:
        !          4333: 
        !          4334: @example
        !          4335: (set (reg:@var{m} @var{r})
        !          4336:      (call @var{nbytes} (mem:@var{fm} @var{addr})))
        !          4337: @end example
        !          4338: 
        !          4339: @noindent
        !          4340: This RTL expression makes it clear (to the optimizer passes) that the
        !          4341: appropriate register receives a useful value in this insn.
        !          4342: 
        !          4343: Immediately after RTL generation, if the value of the subroutine is
        !          4344: actually used, this call insn is always followed closely by an insn which
        !          4345: refers to the register @var{r}.  This remains true through all the
        !          4346: optimizer passes until cross jumping occurs.
        !          4347: 
        !          4348: The following insn has one of two forms.  Either it copies the value into a
        !          4349: pseudo-register, like this:
        !          4350: 
        !          4351: @example
        !          4352: (set (reg:@var{m} @var{p}) (reg:@var{m} @var{r}))
        !          4353: @end example
        !          4354: 
        !          4355: @noindent
        !          4356: or (in the case where the calling function will simply return whatever
        !          4357: value the call produced, and no operation is needed to do this):
        !          4358: 
        !          4359: @example
        !          4360: (use (reg:@var{m} @var{r}))
        !          4361: @end example
        !          4362: 
        !          4363: @noindent
        !          4364: Between the call insn and this following insn there may intervene only a
        !          4365: stack-adjustment insn (and perhaps some @samp{note} insns).
        !          4366: 
        !          4367: When a subroutine returns a @code{BLKmode} value, it is handled by
        !          4368: passing to the subroutine the address of a place to store the value.
        !          4369: So the call insn itself does not ``return'' any value, and it has the
        !          4370: same RTL form as a call that returns nothing.
        !          4371: 
        !          4372: @node Sharing,, Calls, RTL
        !          4373: @section Structure Sharing Assumptions
        !          4374: 
        !          4375: The compiler assumes that certain kinds of RTL expressions are unique;
        !          4376: there do not exist two distinct objects representing the same value.
        !          4377: In other cases, it makes an opposite assumption: that no RTL expression
        !          4378: object of a certain kind appears in more than one place in the
        !          4379: containing structure.
        !          4380: 
        !          4381: These assumptions refer to a single function; except for the RTL
        !          4382: objects that describe global variables and external functions,
        !          4383: no RTL objects are common to two functions.
        !          4384: 
        !          4385: @itemize @bullet
        !          4386: @item
        !          4387: Each pseudo-register has only a single @samp{reg} object to represent it,
        !          4388: and therefore only a single machine mode.
        !          4389: 
        !          4390: @item
        !          4391: For any symbolic label, there is only one @samp{symbol_ref} object
        !          4392: referring to it.
        !          4393: 
        !          4394: @item
        !          4395: There is only one @samp{const_int} expression with value zero,
        !          4396: and only one with value one.
        !          4397: 
        !          4398: @item
        !          4399: There is only one @samp{pc} expression.
        !          4400: 
        !          4401: @item
        !          4402: There is only one @samp{cc0} expression.
        !          4403: 
        !          4404: @item
        !          4405: There is only one @samp{const_double} expression with mode
        !          4406: @code{SFmode} and value zero, and only one with mode @code{DFmode} and
        !          4407: value zero.
        !          4408: 
        !          4409: @item
        !          4410: No @samp{label_ref} appears in more than one place in the RTL
        !          4411: structure; in other words, it is safe to do a tree-walk of all the
        !          4412: insns in the function and assume that each time a @samp{label_ref} is
        !          4413: seen it is distinct from all others that are seen.
        !          4414: 
        !          4415: @item
        !          4416: Only one @samp{mem} object is normally created for each static
        !          4417: variable or stack slot, so these objects are frequently shared in all
        !          4418: the places they appear.  However, separate but equal objects for these
        !          4419: variables are occasionally made.
        !          4420: 
        !          4421: @item
        !          4422: No RTL object appears in more than one place in the RTL structure
        !          4423: except as described above.  Many passes of the compiler rely on this
        !          4424: by assuming that they can modify RTL objects in place without unwanted
        !          4425: side-effects on other insns.
        !          4426: 
        !          4427: @item
        !          4428: During initial RTL generation, shared structure is freely introduced.
        !          4429: After all the RTL for a function has been generated, all shared
        !          4430: structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
        !          4431: after which the above rules are guaranteed to be followed.
        !          4432: 
        !          4433: @item
        !          4434: During the combiner pass, shared structure with an insn can exist
        !          4435: temporarily.  However, the shared structure is copied before the
        !          4436: combiner is finished with the insn.  This is done by
        !          4437: @code{copy_substitutions} in @samp{combine.c}.
        !          4438: @end itemize
        !          4439: 
        !          4440: @node Machine Desc, Machine Macros, RTL, Top
        !          4441: @chapter Machine Descriptions
        !          4442: 
        !          4443: A machine description has two parts: a file of instruction patterns
        !          4444: (@file{.md} file) and a C header file of macro definitions.
        !          4445: 
        !          4446: The @file{.md} file for a target machine contains a pattern for each
        !          4447: instruction that the target machine supports (or at least each instruction
        !          4448: that is worth telling the compiler about).  It may also contain comments.
        !          4449: A semicolon causes the rest of the line to be a comment, unless the semicolon
        !          4450: is inside a quoted string.
        !          4451: 
        !          4452: See the next chapter for information on the C header file.
        !          4453: 
        !          4454: @menu
        !          4455: * Patterns::            How to write instruction patterns.
        !          4456: * Example::             An explained example of a @samp{define_insn} pattern.
        !          4457: * RTL Template::        The RTL template defines what insns match a pattern.
        !          4458: * Output Template::     The output template says how to make assembler code
        !          4459:                           from such an insn.
        !          4460: * Output Statement::    For more generality, write C code to output 
        !          4461:                           the assembler code.
        !          4462: * Constraints::         When not all operands are general operands.
        !          4463: * Standard Names::      Names mark patterns to use for code generation.
        !          4464: * Pattern Ordering::    When the order of patterns makes a difference.
        !          4465: * Dependent Patterns::  Having one pattern may make you need another.
        !          4466: * Jump Patterns::       Special considerations for patterns for jump insns.
        !          4467: * Peephole Definitions::Defining machine-specific peephole optimizations.
        !          4468: * Expander Definitions::Generating a sequence of several RTL insns
        !          4469:                          for a standard operation.
        !          4470: @end menu
        !          4471: 
        !          4472: @node Patterns, Example, Machine Desc, Machine Desc
        !          4473: @section Everything about Instruction Patterns
        !          4474: 
        !          4475: Each instruction pattern contains an incomplete RTL expression, with pieces
        !          4476: to be filled in later, operand constraints that restrict how the pieces can
        !          4477: be filled in, and an output pattern or C code to generate the assembler
        !          4478: output, all wrapped up in a @samp{define_insn} expression.
        !          4479: 
        !          4480: A @samp{define_insn} is an RTL expression containing four or five operands:
        !          4481: 
        !          4482: @enumerate
        !          4483: @item
        !          4484: An optional name.  The presence of a name indicate that this instruction
        !          4485: pattern can perform a certain standard job for the RTL-generation
        !          4486: pass of the compiler.  This pass knows certain names and will use
        !          4487: the instruction patterns with those names, if the names are defined
        !          4488: in the machine description.
        !          4489: 
        !          4490: The absence of a name is indicated by writing an empty string
        !          4491: where the name should go.  Nameless instruction patterns are never
        !          4492: used for generating RTL code, but they may permit several simpler insns
        !          4493: to be combined later on.
        !          4494: 
        !          4495: Names that are not thus known and used in RTL-generation have no
        !          4496: effect; they are equivalent to no name at all.
        !          4497: 
        !          4498: @item
        !          4499: The @dfn{RTL template} (@pxref{RTL Template}) is a vector of
        !          4500: incomplete RTL expressions which show what the instruction should look
        !          4501: like.  It is incomplete because it may contain @samp{match_operand}
        !          4502: and @samp{match_dup} expressions that stand for operands of the
        !          4503: instruction.
        !          4504: 
        !          4505: If the vector has only one element, that element is what the
        !          4506: instruction should look like.  If the vector has multiple elements,
        !          4507: then the instruction looks like a @samp{parallel} expression
        !          4508: containing that many elements as described.
        !          4509: 
        !          4510: @item
        !          4511: A condition.  This is a string which contains a C expression that is
        !          4512: the final test to decide whether an insn body matches this pattern.
        !          4513: 
        !          4514: For a named pattern, the condition (if present) may not depend on
        !          4515: the data in the insn being matched, but only the target-machine-type
        !          4516: flags.  The compiler needs to test these conditions during
        !          4517: initialization in order to learn exactly which named instructions are
        !          4518: available in a particular run.
        !          4519: 
        !          4520: For nameless patterns, the condition is applied only when matching an
        !          4521: individual insn, and only after the insn has matched the pattern's
        !          4522: recognition template.  The insn's operands may be found in the vector
        !          4523: @code{operands}.
        !          4524: 
        !          4525: @item
        !          4526: The @dfn{output template}: a string that says how to output matching
        !          4527: insns as assembler code.  @samp{%} in this string specifies where
        !          4528: to substitute the value of an operand.  @xref{Output Template}.
        !          4529: 
        !          4530: When simple substitution isn't general enough, you can specify a piece
        !          4531: of C code to compute the output.  @xref{Output Statement}.
        !          4532: 
        !          4533: @item
        !          4534: Optionally, some @dfn{machine-specific information}.  The meaning
        !          4535: of this information is defined only by an individual machine description;
        !          4536: typically it might say whether this insn alters the condition codes,
        !          4537: or how many bytes of output it generates.
        !          4538: 
        !          4539: This operand is written as a string containing a C initializer
        !          4540: (complete with braces) for the structure type @code{INSN_MACHINE_INFO},
        !          4541: whose definition is up to you (@pxref{Misc}).
        !          4542: @end enumerate
        !          4543: 
        !          4544: @node Example, RTL Template, Patterns, Machine Desc
        !          4545: @section Example of @samp{define_insn}
        !          4546: 
        !          4547: Here is an actual example of an instruction pattern, for the 68000/68020.
        !          4548: 
        !          4549: @example
        !          4550: (define_insn "tstsi"
        !          4551:   [(set (cc0)
        !          4552:         (match_operand:SI 0 "general_operand" "rm"))]
        !          4553:   ""
        !          4554:   "*
        !          4555: @{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
        !          4556:     return \"tstl %0\";
        !          4557:   return \"cmpl #0,%0\"; @}")
        !          4558: @end example
        !          4559: 
        !          4560: This is an instruction that sets the condition codes based on the value of
        !          4561: a general operand.  It has no condition, so any insn whose RTL description
        !          4562: has the form shown may be handled according to this pattern.  The name
        !          4563: @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
        !          4564: pass that, when it is necessary to test such a value, an insn to do so
        !          4565: can be constructed using this pattern.
        !          4566: 
        !          4567: The output control string is a piece of C code which chooses which
        !          4568: output template to return based on the kind of operand and the specific
        !          4569: type of CPU for which code is being generated.
        !          4570: 
        !          4571: @samp{"rm"} is an operand constraint.  Its meaning is explained below.
        !          4572: 
        !          4573: @node RTL Template, Output Template, Example, Machine Desc
        !          4574: @section RTL Template for Generating and Recognizing Insns
        !          4575: 
        !          4576: The RTL template is used to define which insns match the particular pattern
        !          4577: and how to find their operands.  For named patterns, the RTL template also
        !          4578: says how to construct an insn from specified operands.
        !          4579: 
        !          4580: Construction involves substituting specified operands into a copy of the
        !          4581: template.  Matching involves determining the values that serve as the
        !          4582: operands in the insn being matched.  Both of these activities are
        !          4583: controlled by special expression types that direct matching and
        !          4584: substitution of the operands.
        !          4585: 
        !          4586: @table @code
        !          4587: @item (match_operand:@var{m} @var{n} @var{testfn} @var{constraint})
        !          4588: This expression is a placeholder for operand number @var{n} of
        !          4589: the insn.  When constructing an insn, operand number @var{n}
        !          4590: will be substituted at this point.  When matching an insn, whatever
        !          4591: appears at this position in the insn will be taken as operand
        !          4592: number @var{n}; but it must satisfy @var{testfn} or this instruction
        !          4593: pattern will not match at all.
        !          4594: 
        !          4595: Operand numbers must be chosen consecutively counting from zero in
        !          4596: each instruction pattern.  There may be only one @samp{match_operand}
        !          4597: expression in the pattern for each operand number.  Usually operands
        !          4598: are numbered in the order of appearance in @samp{match_operand}
        !          4599: expressions.
        !          4600: 
        !          4601: @var{testfn} is a string that is the name of a C function that accepts
        !          4602: two arguments, a machine mode and an expression.  During matching,
        !          4603: the function will be called with @var{m} as the mode argument
        !          4604: and the putative operand as the other argument.  If it returns zero,
        !          4605: this instruction pattern fails to match.  @var{testfn} may be
        !          4606: an empty string; then it means no test is to be done on the operand.
        !          4607: 
        !          4608: @var{constraint} is explained later (@pxref{Constraints}).
        !          4609: 
        !          4610: Most often, @var{testfn} is @code{"general_operand"}.  It checks
        !          4611: that the putative operand is either a constant, a register or a
        !          4612: memory reference, and that it is valid for mode @var{m}.
        !          4613: 
        !          4614: For an operand that must be a register, @var{testfn} should be
        !          4615: @code{"register_operand"}.  It would be valid to use
        !          4616: @code{"general_operand"}, since the reload pass would copy any
        !          4617: non-register operands through registers, but this would make GNU CC do
        !          4618: extra work, and it would prevent the register allocator from doing the
        !          4619: best possible job.
        !          4620: 
        !          4621: For an operand that must be a constant, either @var{testfn} should be
        !          4622: @code{"immediate_operand"}, or the instruction pattern's extra
        !          4623: condition should check for constants, or both.  You cannot expect the
        !          4624: constraints to do this work!  If the constraints allow only constants,
        !          4625: but the predicate allows something else, the compiler will crash when
        !          4626: that case arises.
        !          4627: 
        !          4628: @item (match_dup @var{n})
        !          4629: This expression is also a placeholder for operand number @var{n}.
        !          4630: It is used when the operand needs to appear more than once in the
        !          4631: insn.
        !          4632: 
        !          4633: In construction, @samp{match_dup} behaves exactly like
        !          4634: @samp{match_operand}: the operand is substituted into the insn being
        !          4635: constructed.  But in matching, @samp{match_dup} behaves differently.
        !          4636: It assumes that operand number @var{n} has already been determined by
        !          4637: a @samp{match_operand} appearing earlier in the recognition template,
        !          4638: and it matches only an identical-looking expression.
        !          4639: 
        !          4640: @item (address (match_operand:@var{m} @var{n} "address_operand" ""))
        !          4641: This complex of expressions is a placeholder for an operand number
        !          4642: @var{n} in a ``load address'' instruction: an operand which specifies
        !          4643: a memory location in the usual way, but for which the actual operand
        !          4644: value used is the address of the location, not the contents of the
        !          4645: location.
        !          4646: 
        !          4647: @samp{address} expressions never appear in RTL code, only in machine
        !          4648: descriptions.  And they are used only in machine descriptions that do
        !          4649: not use the operand constraint feature.  When operand constraints are
        !          4650: in use, the letter @samp{p} in the constraint serves this purpose.
        !          4651: 
        !          4652: @var{m} is the machine mode of the @emph{memory location being
        !          4653: addressed}, not the machine mode of the address itself.  That mode is
        !          4654: always the same on a given target machine (it is @code{Pmode}, which
        !          4655: normally is @code{SImode}), so there is no point in mentioning it;
        !          4656: thus, no machine mode is written in the @samp{address} expression.  If
        !          4657: some day support is added for machines in which addresses of different
        !          4658: kinds of objects appear differently or are used differently (such as
        !          4659: the PDP-10), different formats would perhaps need different machine
        !          4660: modes and these modes might be written in the @samp{address}
        !          4661: expression.
        !          4662: @end table
        !          4663: 
        !          4664: @node Output Template, Output Statement, RTL Template, Machine Desc
        !          4665: @section Output Templates and Operand Substitution
        !          4666: 
        !          4667: The @dfn{output template} is a string which specifies how to output
        !          4668: the assembler code for an instruction pattern.  Most of the template
        !          4669: is a fixed string which is output literally.  The character @samp{%}
        !          4670: is used to specify where to substitute an operand; it can also be
        !          4671: used to identify places different variants of the assembler require
        !          4672: different syntax.
        !          4673: 
        !          4674: In the simplest case, a @samp{%} followed by a digit @var{n} says to output
        !          4675: operand @var{n} at that point in the string.
        !          4676: 
        !          4677: @samp{%} followed by a letter and a digit says to output an operand in an
        !          4678: alternate fashion.  Four letters have standard, built-in meanings described
        !          4679: below.  The machine description macro @code{PRINT_OPERAND} can define
        !          4680: additional letters with nonstandard meanings.
        !          4681: 
        !          4682: @samp{%c@var{digit}} can be used to substitute an operand that is a
        !          4683: constant value without the syntax that normally indicates an immediate
        !          4684: operand.
        !          4685: 
        !          4686: @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
        !          4687: the constant is negated before printing.
        !          4688: 
        !          4689: @samp{%a@var{digit}} can be used to substitute an operand as if it were a
        !          4690: memory reference, with the actual operand treated as the address.  This may
        !          4691: be useful when outputting a ``load address'' instruction, because often the
        !          4692: assembler syntax for such an instruction requires you to write the operand
        !          4693: as if it were a memory reference.
        !          4694: 
        !          4695: @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
        !          4696: instruction.
        !          4697: 
        !          4698: @samp{%} followed by a punctuation character specifies a substitution that
        !          4699: does not use an operand.  Only one case is standard: @samp{%%} outputs a
        !          4700: @samp{%} into the assembler code.  Other nonstandard cases can be
        !          4701: defined in the @code{PRINT_OPERAND} macro.
        !          4702: 
        !          4703: The template may generate multiple assembler instructions.  Write the text
        !          4704: for the instructions, with @samp{\;} between them.
        !          4705: 
        !          4706: When the RTL contains two operand which are required by constraint to match
        !          4707: each other, the output template must refer only to the lower-numbered operand.
        !          4708: Matching operands are not always identical, and the rest of the compiler
        !          4709: arranges to put the proper RTL expression for printing into the lower-numbered
        !          4710: operand.
        !          4711: 
        !          4712: One use of nonstandard letters or punctuation following @samp{%} is to
        !          4713: distinguish between different assembler languages for the same machine; for
        !          4714: example, Motorola syntax versus MIT syntax for the 68000.  Motorola syntax
        !          4715: requires periods in most opcode names, while MIT syntax does not.  For
        !          4716: example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
        !          4717: syntax.  The same file of patterns is used for both kinds of output syntax,
        !          4718: but the character sequence @samp{%.} is used in each place where Motorola
        !          4719: syntax wants a period.  The @code{PRINT_OPERAND} macro for Motorola syntax
        !          4720: defines the sequence to output a period; the macro for MIT syntax defines
        !          4721: it to do nothing.
        !          4722: 
        !          4723: @node Output Statement, Constraints, Output Template, Machine Desc
        !          4724: @section C Statements for Generating Assembler Output
        !          4725: 
        !          4726: Often a single fixed template string cannot produce correct and efficient
        !          4727: assembler code for all the cases that are recognized by a single
        !          4728: instruction pattern.  For example, the opcodes may depend on the kinds of
        !          4729: operands; or some unfortunate combinations of operands may require extra
        !          4730: machine instructions.
        !          4731: 
        !          4732: If the output control string starts with a @samp{*}, then it is not an
        !          4733: output template but rather a piece of C program that should compute a
        !          4734: template.  It should execute a @code{return} statement to return the
        !          4735: template-string you want.  Most such templates use C string literals, which
        !          4736: require doublequote characters to delimit them.  To include these
        !          4737: doublequote characters in the string, prefix each one with @samp{\}.
        !          4738: 
        !          4739: The operands may be found in the array @code{operands}, whose C data type
        !          4740: is @code{rtx []}.
        !          4741: 
        !          4742: It is possible to output an assembler instruction and then go on to output
        !          4743: or compute more of them, using the subroutine @code{output_asm_insn}.  This
        !          4744: receives two arguments: a template-string and a vector of operands.  The
        !          4745: vector may be @code{operands}, or it may be another array of @code{rtx}
        !          4746: that you declare locally and initialize yourself.
        !          4747: 
        !          4748: When an insn pattern has multiple alternatives in its constraints, often
        !          4749: the appearance of the assembler code determined mostly by which alternative
        !          4750: was matched.  When this is so, the C code can test the variable
        !          4751: @code{which_alternative}, which is the ordinal number of the alternative
        !          4752: that was actually satisfied (0 for the first, 1 for the second alternative,
        !          4753: etc.).
        !          4754: 
        !          4755: For example, suppose there are two opcodes for storing zero, @samp{clrreg}
        !          4756: for registers and @samp{clrmem} for memory locations.  Here is how
        !          4757: a pattern could use @code{which_alternative} to choose between them:
        !          4758: 
        !          4759: @example
        !          4760: (define_insn ""
        !          4761:   [(set (match_operand:SI 0 "general_operand" "r,m")
        !          4762:         (const_int 0))]
        !          4763:   ""
        !          4764:   "*
        !          4765:   return (which_alternative == 0
        !          4766:           ? \"clrreg %0\" : \"clrmem %0\");
        !          4767:   ")
        !          4768: @end example
        !          4769: 
        !          4770: @node Constraints, Standard Names, Output Statement, Machine Desc
        !          4771: @section Operand Constraints
        !          4772: 
        !          4773: Each @samp{match_operand} in an instruction pattern can specify a
        !          4774: constraint for the type of operands allowed.  Constraints can say whether
        !          4775: an operand may be in a register, and which kinds of register; whether the
        !          4776: operand can be a memory reference, and which kinds of address; whether the
        !          4777: operand may be an immediate constant, and which possible values it may
        !          4778: have.  Constraints can also require two operands to match.
        !          4779: 
        !          4780: @menu
        !          4781: * Simple Constraints::  Basic use of constraints.
        !          4782: * Multi-Alternative::   When an insn has two alternative constraint-patterns.
        !          4783: * Class Preferences::   Constraints guide which hard register to put things in.
        !          4784: * Modifiers::           More precise control over effects of constraints.
        !          4785: * No Constraints::      Describing a clean machine without constraints.
        !          4786: @end menu
        !          4787: 
        !          4788: @node Simple Constraints, Multi-Alternative, Constraints, Constraints
        !          4789: @subsection Simple Constraints
        !          4790: 
        !          4791: The simplest kind of constraint is a string full of letters, each of
        !          4792: which describes one kind of operand that is permitted.  Here are
        !          4793: the letters that are allowed:
        !          4794: 
        !          4795: @table @asis
        !          4796: @item @samp{m}
        !          4797: A memory operand is allowed, with any kind of address that the machine
        !          4798: supports in general.
        !          4799: 
        !          4800: @item @samp{o}
        !          4801: A memory operand is allowed, but only if the address is
        !          4802: @dfn{offsetable}.  This means that adding a small integer (actually,
        !          4803: the width in bytes of the operand, as determined by its machine mode)
        !          4804: may be added to the address and the result is also a valid memory
        !          4805: address.
        !          4806: 
        !          4807: For example, an address which is constant is offsetable; so is an
        !          4808: address that is the sum of a register and a constant (as long as a
        !          4809: slightly larger constant is also within the range of address-offsets
        !          4810: supported by the machine); but an autoincrement or autodecrement
        !          4811: address is not offsetable.  More complicated indirect/indexed
        !          4812: addresses may or may not be offsetable depending on the other
        !          4813: addressing modes that the machine supports.
        !          4814: 
        !          4815: Note that in an output operand which can be matched by another
        !          4816: operand, the constraint letter @samp{o} is valid only when accompanied
        !          4817: by both @samp{<} (if the target machine has predecrement addressing)
        !          4818: and @samp{>} (if the target machine has preincrement addressing).
        !          4819: 
        !          4820: When the constraint letter @samp{o} is used, the reload pass may
        !          4821: generate instructions which copy a nonoffsetable address into an index
        !          4822: register.  The idea is that the register can be used as a replacement
        !          4823: offsetable address.  But this method requires that there be patterns
        !          4824: to copy any kind of address into a register.  Auto-increment
        !          4825: and auto-decrement addresses are an exception; there need not be an
        !          4826: instruction that can copy such an address into a register, because
        !          4827: reload handles these cases specially.
        !          4828: 
        !          4829: Most older machine designs have ``load address'' instructions which do
        !          4830: just what is needed here.  Some RISC machines do not advertise such
        !          4831: instructions, but the possible addresses on these machines are very
        !          4832: limited, so it is easy to fake them.
        !          4833: 
        !          4834: @item @samp{<}
        !          4835: A memory operand with autodecrement addressing (either predecrement or
        !          4836: postdecrement) is allowed.
        !          4837: 
        !          4838: @item @samp{>}
        !          4839: A memory operand with autoincrement addressing (either preincrement or
        !          4840: postincrement) is allowed.
        !          4841: 
        !          4842: @item @samp{r}
        !          4843: A register operand is allowed provided that it is in a general
        !          4844: register.
        !          4845: 
        !          4846: @item @samp{d}, @samp{a}, @samp{f}, @dots{}
        !          4847: Other letters can be defined in machine-dependent fashion to stand for
        !          4848: particular classes of registers.  @samp{d}, @samp{a} and @samp{f} are
        !          4849: defined on the 68000/68020 to stand for data, address and floating
        !          4850: point registers.
        !          4851: 
        !          4852: @item @samp{i}
        !          4853: An immediate integer operand (one with constant value) is allowed.
        !          4854: This includes symbolic constants whose values will be known only at
        !          4855: assembly time.
        !          4856: 
        !          4857: @item @samp{n}
        !          4858: An immediate integer operand with a known numeric value is allowed.
        !          4859: Many systems cannot support assembly-time constants for operands less
        !          4860: than a word wide.  Constraints for these operands should use @samp{n}
        !          4861: rather than @samp{i}.
        !          4862: 
        !          4863: @item @samp{I}, @samp{J}, @samp{K}, @dots{}
        !          4864: Other letters in the range @samp{I} through @samp{M} may be defined in
        !          4865: a machine-dependent fashion to permit immediate integer operands with
        !          4866: explicit integer values in specified ranges.  For example, on the
        !          4867: 68000, @samp{I} is defined to stand for the range of values 1 to 8.
        !          4868: This is the range permitted as a shift count in the shift
        !          4869: instructions.
        !          4870: 
        !          4871: @item @samp{F}
        !          4872: An immediate floating operand (expression code @samp{const_double}) is
        !          4873: allowed.
        !          4874: 
        !          4875: @item @samp{G}, @samp{H}
        !          4876: @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
        !          4877: permit immediate floating operands in particular ranges of values.
        !          4878: 
        !          4879: @item @samp{s}
        !          4880: An immediate integer operand whose value is not an explicit integer is
        !          4881: allowed.
        !          4882: 
        !          4883: This might appear strange; if an insn allows a constant operand with a
        !          4884: value not known at compile time, it certainly must allow any known
        !          4885: value.  So why use @samp{s} instead of @samp{i}?  Sometimes it allows
        !          4886: better code to be generated.
        !          4887: 
        !          4888: For example, on the 68000 in a fullword instruction it is possible to
        !          4889: use an immediate operand; but if the immediate value is between -32
        !          4890: and 31, better code results from loading the value into a register and
        !          4891: using the register.  This is because the load into the register can be
        !          4892: done with a @samp{moveq} instruction.  We arrange for this to happen
        !          4893: by defining the letter @samp{K} to mean ``any integer outside the
        !          4894: range -32 to 31'', and then specifying @samp{Ks} in the operand
        !          4895: constraints.
        !          4896: 
        !          4897: @item @samp{g}
        !          4898: Any register, memory or immediate integer operand is allowed, except for
        !          4899: registers that are not general registers.
        !          4900: 
        !          4901: @item @samp{@var{n}} (a digit)
        !          4902: An operand that matches operand number @var{n} is allowed.
        !          4903: If a digit is used together with letters, the digit should come last.
        !          4904: 
        !          4905: This is called a @dfn{matching constraint} and what it really means is
        !          4906: that the assembler has only a single operand that fills two roles
        !          4907: considered separate in the RTL insn.  For example, an add insn has two
        !          4908: input operands and one output operand in the RTL, but on most machines
        !          4909: an add instruction really has only two operands, one of them an
        !          4910: input-output operand.
        !          4911: 
        !          4912: Matching constraints work only in circumstances like that add insn.
        !          4913: More precisely, the matching constraint must appear in an input-only
        !          4914: operand and the operand that it matches must be an output-only operand
        !          4915: with a lower number.
        !          4916: 
        !          4917: For operands to match in a particular case usually means that they
        !          4918: are identical-looking RTL expressions.  But in a few special cases
        !          4919: specific kinds of dissimilarity are allowed.  For example, @code{*x}
        !          4920: as an input operand will match @code{*x++} as an output operand.
        !          4921: For proper results in such cases, the output template should always
        !          4922: use the output-operand's number when printing the operand.
        !          4923: 
        !          4924: @item @samp{p}
        !          4925: An operand that is a valid memory address is allowed.  This is
        !          4926: for ``load address'' and ``push address'' instructions.
        !          4927: 
        !          4928: If @samp{p} is used in the constraint, the test-function in the
        !          4929: @samp{match_operand} must be @code{address_operand}.
        !          4930: @end table
        !          4931: 
        !          4932: In order to have valid assembler code, each operand must satisfy
        !          4933: its constraint.  But a failure to do so does not prevent the pattern
        !          4934: from applying to an insn.  Instead, it directs the compiler to modify
        !          4935: the code so that the constraint will be satisfied.  Usually this is
        !          4936: done by copying an operand into a register.
        !          4937: 
        !          4938: Contrast, therefore, the two instruction patterns that follow:
        !          4939: 
        !          4940: @example
        !          4941: (define_insn ""
        !          4942:   [(set (match_operand:SI 0 "general_operand" "r")
        !          4943:         (plus:SI (match_dup 0)
        !          4944:                  (match_operand:SI 1 "general_operand" "r")))]
        !          4945:   ""
        !          4946:   "@dots{}")
        !          4947: @end example
        !          4948: 
        !          4949: @noindent
        !          4950: which has two operands, one of which must appear in two places, and
        !          4951: 
        !          4952: @example
        !          4953: (define_insn ""
        !          4954:   [(set (match_operand:SI 0 "general_operand" "r")
        !          4955:         (plus:SI (match_operand:SI 1 "general_operand" "0")
        !          4956:                  (match_operand:SI 2 "general_operand" "r")))]
        !          4957:   ""
        !          4958:   "@dots{}")
        !          4959: @end example
        !          4960: 
        !          4961: @noindent
        !          4962: which has three operands, two of which are required by a constraint to be
        !          4963: identical.  If we are considering an insn of the form
        !          4964: 
        !          4965: @example
        !          4966: (insn @var{n} @var{prev} @var{next}
        !          4967:   (set (reg:SI 3)
        !          4968:        (plus:SI (reg:SI 6) (reg:SI 109)))
        !          4969:   @dots{})
        !          4970: @end example
        !          4971: 
        !          4972: @noindent
        !          4973: the first pattern would not apply at all, because this insn does not
        !          4974: contain two identical subexpressions in the right place.  The pattern would
        !          4975: say, ``That does not look like an add instruction; try other patterns.''
        !          4976: The second pattern would say, ``Yes, that's an add instruction, but there
        !          4977: is something wrong with it.''  It would direct the reload pass of the
        !          4978: compiler to generate additional insns to make the constraint true.  The
        !          4979: results might look like this:
        !          4980: 
        !          4981: @example
        !          4982: (insn @var{n2} @var{prev} @var{n}
        !          4983:   (set (reg:SI 3) (reg:SI 6))
        !          4984:   @dots{})
        !          4985: 
        !          4986: (insn @var{n} @var{n2} @var{next}
        !          4987:   (set (reg:SI 3)
        !          4988:        (plus:SI (reg:SI 3) (reg:SI 109)))
        !          4989:   @dots{})
        !          4990: @end example
        !          4991: 
        !          4992: It is up to you to make sure that each operand, in each pattern, has
        !          4993: constraints that can handle any RTL expression that could be present for
        !          4994: that operand.  (When multiple alternatives are in use, each pattern must,
        !          4995: for each possible combination of operand expressions, have at least one
        !          4996: alternative which can handle that combination of operands.)  The
        !          4997: constraints don't need to @emph{allow} any possible operand---when this is
        !          4998: the case, they do not constrain---but they must at least point the way to
        !          4999: reloading any possible operand so that it will fit.
        !          5000: 
        !          5001: @itemize @bullet
        !          5002: @item
        !          5003: If the constraint accepts whatever operands the predicate permits,
        !          5004: there is no problem: reloading is never necessary for this operand.
        !          5005: 
        !          5006: For example, an operand whose constraints permit everything except
        !          5007: registers is safe provided its predicate rejects registers.
        !          5008: 
        !          5009: An operand whose predicate accepts only constant values is safe
        !          5010: provided its constraints include the letter @samp{i}.  If any possible
        !          5011: constant value is accepted, then nothing less than @samp{i} will do;
        !          5012: if the predicate is more selective, than the constraints may also be
        !          5013: more selective.
        !          5014: 
        !          5015: @item
        !          5016: Any operand expression can be reloaded by copying it into a register.
        !          5017: So if an operand's constraints allow some kind of register, it is
        !          5018: certain to be safe.  It need not permit all classes of registers; the
        !          5019: compiler knows how to copy a register into another register of the
        !          5020: proper class in order to make an instruction valid.
        !          5021: 
        !          5022: @item
        !          5023: A nonoffsetable memory reference can be reloaded by copying the
        !          5024: address into a register.  So if the constraint uses the letter
        !          5025: @samp{o}, all memory references are taken care of.
        !          5026: 
        !          5027: @item
        !          5028: A constant operand can be reloaded by storing it in memory; it then
        !          5029: becomes an offsetable memory reference.  So if the constraint uses the
        !          5030: letters @samp{o} or @samp{m}, constant operands are not a problem.
        !          5031: @end itemize
        !          5032: 
        !          5033: If the operand's predicate can recognize registers, but the constraint does
        !          5034: not permit them, it can make the compiler crash.  When this operand happens
        !          5035: to be a register, the reload pass will be stymied, because it does not know
        !          5036: how to copy a register temporarily into memory.
        !          5037: 
        !          5038: @node Multi-Alternative, Class Preferences, Simple Constraints, Constraints
        !          5039: @subsection Multiple Alternative Constraints
        !          5040: 
        !          5041: Sometimes a single instruction has multiple alternative sets of possible
        !          5042: operands.  For example, on the 68000, a logical-or instruction can combine
        !          5043: register or an immediate value into memory, or it can combine any kind of
        !          5044: operand into a register; but it cannot combine one memory location into
        !          5045: another.
        !          5046: 
        !          5047: These constraints are represented as multiple alternatives.  An alternative
        !          5048: can be described by a series of letters for each operand.  The overall
        !          5049: constraint for an operand is made from the letters for this operand
        !          5050: from the first alternative, a comma, the letters for this operand from
        !          5051: the second alternative, a comma, and so on until the last alternative.
        !          5052: Here is how it is done for fullword logical-or on the 68000:
        !          5053: 
        !          5054: @example
        !          5055: (define_insn "iorsi3"
        !          5056:   [(set (match_operand:SI 0 "general_operand" "=%m,d")
        !          5057:         (ior:SI (match_operand:SI 1 "general_operand" "0,0")
        !          5058:                 (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
        !          5059:   @dots{})
        !          5060: @end example
        !          5061: 
        !          5062: The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
        !          5063: operand 1 (meaning it must match operand 0), and @samp{dKs} for operand 2.
        !          5064: The second alternative has @samp{d} (data register) for operand 0, @samp{0}
        !          5065: for operand 1, and @samp{dmKs} for operand 2.  The @samp{=} and @samp{%} in
        !          5066: the constraint for operand 0 are not part of any alternative; their meaning
        !          5067: is explained in the next section.
        !          5068: 
        !          5069: If all the operands fit any one alternative, the instruction is valid.
        !          5070: Otherwise, for each alternative, the compiler counts how many instructions
        !          5071: must be added to copy the operands so that that alternative applies.
        !          5072: The alternative requiring the least copying is chosen.  If two alternatives
        !          5073: need the same amount of copying, the one that comes first is chosen.
        !          5074: These choices can be altered with the @samp{?} and @samp{!} characters:
        !          5075: 
        !          5076: @table @samp
        !          5077: @item ?
        !          5078: Disparage slightly the alternative that the @samp{?} appears in,
        !          5079: as a choice when no alternative applies exactly.  The compiler regards
        !          5080: this alternative as one unit more costly for each @samp{?} that appears
        !          5081: in it.
        !          5082: 
        !          5083: @item !
        !          5084: Disparage severely the alternative that the @samp{!} appears in.
        !          5085: When operands must be copied into registers, the compiler will
        !          5086: never choose this alternative as the one to strive for.
        !          5087: @end table
        !          5088: 
        !          5089: When an insn pattern has multiple alternatives in its constraints,
        !          5090: often the appearance of the assembler code determined mostly by which
        !          5091: alternative was matched.  When this is so, the C code for writing the
        !          5092: assembler code can use the variable @code{which_alternative}, which is
        !          5093: the ordinal number of the alternative that was actually satisfied
        !          5094: (0 for the first, 1 for the second alternative, etc.).  For example:
        !          5095: 
        !          5096: @example
        !          5097: (define_insn ""
        !          5098:   [(set (match_operand:SI 0 "general_operand" "r,m")
        !          5099:         (const_int 0))]
        !          5100:   ""
        !          5101:   "*
        !          5102:   return (which_alternative == 0
        !          5103:           ? \"clrreg %0\" : \"clrmem %0\");
        !          5104:   ")
        !          5105: @end example
        !          5106: 
        !          5107: @node Class Preferences, Modifiers, Multi-Alternative, Constraints
        !          5108: @subsection Register Class Preferences
        !          5109: 
        !          5110: The operand constraints have another function: they enable the compiler
        !          5111: to decide which kind of hardware register a pseudo register is best
        !          5112: allocated to.  The compiler examines the constraints that apply to the
        !          5113: insns that use the pseudo register, looking for the machine-dependent
        !          5114: letters such as @samp{d} and @samp{a} that specify classes of registers.
        !          5115: The pseudo register is put in whichever class gets the most ``votes''.
        !          5116: The constraint letters @samp{g} and @samp{r} also vote: they vote in
        !          5117: favor of a general register.  The machine description says which registers
        !          5118: are considered general.
        !          5119: 
        !          5120: Of course, on some machines all registers are equivalent, and no register
        !          5121: classes are defined.  Then none of this complexity is relevant.
        !          5122: 
        !          5123: @node Modifiers, No Constraints, Class Preferences, Constraints
        !          5124: @subsection Constraint Modifier Characters
        !          5125: 
        !          5126: @table @samp
        !          5127: @item =
        !          5128: Means that this operand is write-only for this instruction: the previous
        !          5129: value is discarded and replaced by output data.
        !          5130: 
        !          5131: @item +
        !          5132: Means that this operand is both read and written by the instruction.
        !          5133: 
        !          5134: When the compiler fixes up the operands to satisfy the constraints,
        !          5135: it needs to know which operands are inputs to the instruction and
        !          5136: which are outputs from it.  @samp{=} identifies an output; @samp{+}
        !          5137: identifies an operand that is both input and output; all other operands
        !          5138: are assumed to be input only.
        !          5139: 
        !          5140: @item &
        !          5141: Means (in a particular alternative) that this operand is written
        !          5142: before the instruction is finished using the input operands.
        !          5143: Therefore, this operand may not lie in a register that is used as an
        !          5144: input operand or as part of any memory address.
        !          5145: 
        !          5146: @samp{&} applies only to the alternative in which it is written.  In
        !          5147: constraints with multiple alternatives, sometimes one alternative
        !          5148: requires @samp{&} while others do not.  See, for example, the
        !          5149: @samp{movdf} insn of the 68000.
        !          5150: 
        !          5151: @samp{&} does not obviate the need to write @samp{=}.
        !          5152: 
        !          5153: @item %
        !          5154: Declares the instruction to be commutative for this operand and the
        !          5155: following operand.  This means that the compiler may interchange the
        !          5156: two operands if that is the cheapest way to make all operands fit the
        !          5157: constraints.  This is often used in patterns for addition instructions
        !          5158: that really have only two operands: the result must go in one of the
        !          5159: arguments.  Here for example, is how the 68000 halfword-add
        !          5160: instruction is defined:
        !          5161: 
        !          5162: @example
        !          5163: (define_insn "addhi3"
        !          5164:   [(set (match_operand:HI 0 "general_operand" "=m,r")
        !          5165:      (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
        !          5166:               (match_operand:HI 2 "general_operand" "di,g")))]
        !          5167:   @dots{})
        !          5168: @end example
        !          5169: 
        !          5170: Note that in previous versions of GNU CC the @samp{%} constraint
        !          5171: modifier always applied to operands 1 and 2 regardless of which
        !          5172: operand it was written in.  The usual custom was to write it in
        !          5173: operand 0.  Now it must be in operand 1 if the operands to be
        !          5174: exchanged are 1 and 2.
        !          5175: 
        !          5176: @item #
        !          5177: Says that all following characters, up to the next comma, are to be
        !          5178: ignored as a constraint.  They are significant only for choosing
        !          5179: register preferences.
        !          5180: 
        !          5181: @item *
        !          5182: Says that the following character should be ignored when choosing
        !          5183: register preferences.  @samp{*} has no effect on the meaning of the
        !          5184: constraint as a constraint.
        !          5185: 
        !          5186: Here is an example: the 68000 has an instruction to sign-extend a
        !          5187: halfword in a data register, and can also sign-extend a value by
        !          5188: copying it into an address register.  While either kind of register is
        !          5189: acceptable, the constraints on an address-register destination are
        !          5190: less strict, so it is best if register allocation makes an address
        !          5191: register its goal.  Therefore, @samp{*} is used so that the @samp{d}
        !          5192: constraint letter (for data register) is ignored when computing
        !          5193: register preferences.
        !          5194: 
        !          5195: @example
        !          5196: (define_insn "extendhisi2"
        !          5197:   [(set (match_operand:SI 0 "general_operand" "=*d,a")
        !          5198:         (sign_extend:SI
        !          5199:          (match_operand:HI 1 "general_operand" "0,g")))]
        !          5200:   @dots{})
        !          5201: @end example
        !          5202: @end table
        !          5203: 
        !          5204: @node No Constraints,, Modifiers, Constraints
        !          5205: @subsection Not Using Constraints
        !          5206: 
        !          5207: Some machines are so clean that operand constraints are not required.  For
        !          5208: example, on the Vax, an operand valid in one context is valid in any other
        !          5209: context.  On such a machine, every operand constraint would be @samp{g},
        !          5210: excepting only operands of ``load address'' instructions which are
        !          5211: written as if they referred to a memory location's contents but actual
        !          5212: refer to its address.  They would have constraint @samp{p}.
        !          5213: 
        !          5214: For such machines, instead of writing @samp{g} and @samp{p} for all
        !          5215: the constraints, you can choose to write a description with empty constraints.
        !          5216: Then you write @samp{""} for the constraint in every @samp{match_operand}.
        !          5217: Address operands are identified by writing an @samp{address} expression
        !          5218: around the @samp{match_operand}, not by their constraints.
        !          5219: 
        !          5220: When the machine description has just empty constraints, certain parts
        !          5221: of compilation are skipped, making the compiler faster.
        !          5222: 
        !          5223: @node Standard Names, Pattern Ordering, Constraints, Machine Desc
        !          5224: @section Standard Names for Patterns Used in Generation
        !          5225: 
        !          5226: Here is a table of the instruction names that are meaningful in the RTL
        !          5227: generation pass of the compiler.  Giving one of these names to an
        !          5228: instruction pattern tells the RTL generation pass that it can use the
        !          5229: pattern in to accomplish a certain task.
        !          5230: 
        !          5231: @table @asis
        !          5232: @item @samp{mov@var{m}}
        !          5233: Here @var{m} is a two-letter machine mode name, in lower case.  This
        !          5234: instruction pattern moves data with that machine mode from operand 1 to
        !          5235: operand 0.  For example, @samp{movsi} moves full-word data.
        !          5236: 
        !          5237: If operand 0 is a @samp{subreg} with mode @var{m} of a register whose
        !          5238: natural mode is wider than @var{m}, the effect of this instruction is
        !          5239: to store the specified value in the part of the register that corresponds
        !          5240: to mode @var{m}.  The effect on the rest of the register is undefined.
        !          5241: 
        !          5242: This class of patterns is special in several ways.  First of all, each
        !          5243: of these names @emph{must} be defined, because there is no other way
        !          5244: to copy a datum from one place to another.
        !          5245: 
        !          5246: Second, these patterns are not used solely in the RTL generation pass.
        !          5247: Even the reload pass can generate move insns to copy values from stack
        !          5248: slots into temporary registers.  When it does so, one of the operands
        !          5249: is a hard register and the other is an operand that can have a reload.
        !          5250: 
        !          5251: Therefore, when given such a pair of operands, the pattern must
        !          5252: generate RTL which needs no temporary registers---no registers other
        !          5253: than the operands.  For example, if you support the pattern with a
        !          5254: @code{define_expand}, then in such a case you mustn't call
        !          5255: @code{force_reg} or any other such function which might generate new
        !          5256: pseudo registers.
        !          5257: 
        !          5258: This requirement exists even for subword modes on a RISC machine where
        !          5259: fetching those modes from memory normally requires several insns and
        !          5260: some temporary registers.  Look in @file{spur.md} to see how the
        !          5261: requirement is satisfied.
        !          5262: 
        !          5263: The variety of operands that have reloads depends on the rest of the
        !          5264: machine description, but typically on a RISC machine these can only be
        !          5265: pseudo registers that did not get hard registers, while on other
        !          5266: machines explicit memory references will get optional reloads.
        !          5267: 
        !          5268: In addition, the constraints must allow any hard register to be moved
        !          5269: to any other hard register (provided that @code{HARD_REGNO_MODE_OK}
        !          5270: permits mode @var{m} in each of the registers).
        !          5271: 
        !          5272: @item @samp{movstrict@var{m}}
        !          5273: Like @samp{mov@var{m}} except that if operand 0 is a @samp{subreg}
        !          5274: with mode @var{m} of a register whose natural mode is wider,
        !          5275: the @samp{movstrict@var{m}} instruction is guaranteed not to alter
        !          5276: any of the register except the part which belongs to mode @var{m}.
        !          5277: 
        !          5278: @item @samp{add@var{m}3}
        !          5279: Add operand 2 and operand 1, storing the result in operand 0.  All operands
        !          5280: must have mode @var{m}.  This can be used even on two-address machines, by
        !          5281: means of constraints requiring operands 1 and 0 to be the same location.
        !          5282: 
        !          5283: @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}
        !          5284: Similar, for other arithmetic operations.
        !          5285: 
        !          5286: There are special considerations for register classes for logical-and
        !          5287: instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}.
        !          5288: They apply not only to the patterns with these standard names, but to
        !          5289: any patterns that will match such an instruction.  @xref{Register
        !          5290: Classes}.
        !          5291: 
        !          5292: @item @samp{mulhisi3}
        !          5293: Multiply operands 1 and 2, which have mode @code{HImode}, and store
        !          5294: a @code{SImode} product in operand 0.
        !          5295: 
        !          5296: @item @samp{mulqihi3}, @samp{mulsidi3}
        !          5297: Similar widening-multiplication instructions of other widths.
        !          5298: 
        !          5299: @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
        !          5300: Similar widening-multiplication instructions that do unsigned
        !          5301: multiplication.
        !          5302: 
        !          5303: @item @samp{divmod@var{m}4}
        !          5304: Signed division that produces both a quotient and a remainder.
        !          5305: Operand 1 is divided by operand 2 to produce a quotient stored
        !          5306: in operand 0 and a remainder stored in operand 3.
        !          5307: 
        !          5308: @item @samp{udivmod@var{m}4}
        !          5309: Similar, but does unsigned division.
        !          5310: 
        !          5311: @item @samp{divmod@var{m}@var{n}4}
        !          5312: Like @samp{divmod@var{m}4} except that only the dividend has mode
        !          5313: @var{m}; the divisor, quotient and remainder have mode @var{n}.
        !          5314: For example, the Vax has a @samp{divmoddisi4} instruction
        !          5315: (but it is omitted from the machine description, because it
        !          5316: is so slow that it is faster to compute remainders by the
        !          5317: circumlocution that the compiler will use if this instruction is
        !          5318: not available).
        !          5319: 
        !          5320: @item @samp{ashl@var{m}3}
        !          5321: Arithmetic-shift operand 1 left by a number of bits specified by
        !          5322: operand 2, and store the result in operand 0.  Operand 2 has
        !          5323: mode @code{SImode}, not mode @var{m}.
        !          5324: 
        !          5325: @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}
        !          5326: Other shift and rotate instructions.
        !          5327: 
        !          5328: Logical and arithmetic left shift are the same.  Machines that do not
        !          5329: allow negative shift counts often have only one instruction for
        !          5330: shifting left.  On such machines, you should define a pattern named
        !          5331: @samp{ashl@var{m}3} and leave @samp{lshl@var{m}3} undefined.
        !          5332: 
        !          5333: There are special considerations for register classes for shift
        !          5334: instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}.
        !          5335: They apply not only to the patterns with these standard names, but to
        !          5336: any patterns that will match such an instruction.  @xref{Register
        !          5337: Classes}.
        !          5338: 
        !          5339: @item @samp{neg@var{m}2}
        !          5340: Negate operand 1 and store the result in operand 0.
        !          5341: 
        !          5342: @item @samp{abs@var{m}2}
        !          5343: Store the absolute value of operand 1 into operand 0.
        !          5344: 
        !          5345: @item @samp{sqrt@var{m}2}
        !          5346: Store the square root of operand 1 into operand 0.
        !          5347: 
        !          5348: @item @samp{ffs@var{m}2}
        !          5349: Store into operand 0 one plus the index of the least significant 1-bit
        !          5350: of operand 1.  If operand 1 is zero, store zero.  @var{m} is the mode
        !          5351: of operand 0; operand 1's mode is specified by the instruction
        !          5352: pattern, and the compiler will convert the operand to that mode before
        !          5353: generating the instruction.
        !          5354: 
        !          5355: @item @samp{one_cmpl@var{m}2}
        !          5356: Store the bitwise-complement of operand 1 into operand 0.
        !          5357: 
        !          5358: @item @samp{cmp@var{m}}
        !          5359: Compare operand 0 and operand 1, and set the condition codes.
        !          5360: The RTL pattern should look like this:
        !          5361: 
        !          5362: @example
        !          5363: (set (cc0) (minus (match_operand:@var{m} 0 @dots{})
        !          5364:                   (match_operand:@var{m} 1 @dots{})))
        !          5365: @end example
        !          5366: 
        !          5367: Each such definition in the machine description, for integer mode
        !          5368: @var{m}, must have a corresponding @samp{tst@var{m}} pattern, because
        !          5369: optimization can simplify the compare into a test when operand 1 is
        !          5370: zero.
        !          5371: 
        !          5372: @item @samp{tst@var{m}}
        !          5373: Compare operand 0 against zero, and set the condition codes.
        !          5374: The RTL pattern should look like this:
        !          5375: 
        !          5376: @example
        !          5377: (set (cc0) (match_operand:@var{m} 0 @dots{}))
        !          5378: @end example
        !          5379: 
        !          5380: @item @samp{movstr@var{m}}
        !          5381: Block move instruction.  The addresses of the destination and source
        !          5382: strings are the first two operands, and both are in mode @code{Pmode}.
        !          5383: The number of bytes to move is the third operand, in mode @var{m}.
        !          5384: 
        !          5385: @item @samp{cmpstr@var{m}}
        !          5386: Block compare instruction, with operands like @samp{movstr@var{m}}
        !          5387: except that the two memory blocks are compared byte by byte
        !          5388: in lexicographic order.  The effect of the instruction is to set
        !          5389: the condition codes.
        !          5390: 
        !          5391: @item @samp{float@var{m}@var{n}2}
        !          5392: Convert operand 1 (valid for fixed point mode @var{m}) to floating
        !          5393: point mode @var{n} and store in operand 0 (which has mode @var{n}).
        !          5394: 
        !          5395: @item @samp{fix@var{m}@var{n}2}
        !          5396: Convert operand 1 (valid for floating point mode @var{m}) to fixed
        !          5397: point mode @var{n} as a signed number and store in operand 0 (which
        !          5398: has mode @var{n}).  This instruction's result is defined only when
        !          5399: the value of operand 1 is an integer.
        !          5400: 
        !          5401: @item @samp{fixuns@var{m}@var{n}2}
        !          5402: Convert operand 1 (valid for floating point mode @var{m}) to fixed
        !          5403: point mode @var{n} as an unsigned number and store in operand 0 (which
        !          5404: has mode @var{n}).  This instruction's result is defined only when the
        !          5405: value of operand 1 is an integer.
        !          5406: 
        !          5407: @item @samp{ftrunc@var{m}2}
        !          5408: Convert operand 1 (valid for floating point mode @var{m}) to an
        !          5409: integer value, still represented in floating point mode @var{m}, and
        !          5410: store it in operand 0 (valid for floating point mode @var{m}).
        !          5411: 
        !          5412: @item @samp{fix_trunc@var{m}@var{n}2}
        !          5413: Like @samp{fix@var{m}@var{n}2} but works for any floating point value
        !          5414: of mode @var{m} by converting the value to an integer.
        !          5415: 
        !          5416: @item @samp{fixuns_trunc@var{m}@var{n}2}
        !          5417: Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
        !          5418: value of mode @var{m} by converting the value to an integer.
        !          5419: 
        !          5420: @item @samp{trunc@var{m}@var{n}}
        !          5421: Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
        !          5422: store in operand 0 (which has mode @var{n}).  Both modes must be fixed
        !          5423: point or both floating point.
        !          5424: 
        !          5425: @item @samp{extend@var{m}@var{n}}
        !          5426: Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
        !          5427: store in operand 0 (which has mode @var{n}).  Both modes must be fixed
        !          5428: point or both floating point.
        !          5429: 
        !          5430: @item @samp{zero_extend@var{m}@var{n}}
        !          5431: Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
        !          5432: store in operand 0 (which has mode @var{n}).  Both modes must be fixed
        !          5433: point.
        !          5434: 
        !          5435: @item @samp{extv}
        !          5436: Extract a bit-field from operand 1 (a register or memory operand),
        !          5437: where operand 2 specifies the width in bits and operand 3 the starting
        !          5438: bit, and store it in operand 0.  Operand 0 must have @code{Simode}.
        !          5439: Operand 1 may have mode @code{QImode} or @code{SImode}; often
        !          5440: @code{SImode} is allowed only for registers.  Operands 2 and 3 must be
        !          5441: valid for @code{SImode}.
        !          5442: 
        !          5443: The RTL generation pass generates this instruction only with constants
        !          5444: for operands 2 and 3.
        !          5445: 
        !          5446: The bit-field value is sign-extended to a full word integer
        !          5447: before it is stored in operand 0.
        !          5448: 
        !          5449: @item @samp{extzv}
        !          5450: Like @samp{extv} except that the bit-field value is zero-extended.
        !          5451: 
        !          5452: @item @samp{insv}
        !          5453: Store operand 3 (which must be valid for @code{SImode}) into a
        !          5454: bit-field in operand 0, where operand 1 specifies the width in bits
        !          5455: and operand 2 the starting bit.  Operand 0 may have mode @code{QImode}
        !          5456: or @code{SImode}; often @code{SImode} is allowed only for registers.
        !          5457: Operands 1 and 2 must be valid for @code{SImode}.
        !          5458: 
        !          5459: The RTL generation pass generates this instruction only with constants
        !          5460: for operands 1 and 2.
        !          5461: 
        !          5462: @item @samp{s@var{cond}}
        !          5463: Store zero or nonzero in the operand according to the condition codes.
        !          5464: Value stored is nonzero iff the condition @var{cond} is true.
        !          5465: @var{cond} is the name of a comparison operation expression code, such
        !          5466: as @samp{eq}, @samp{lt} or @samp{leu}.
        !          5467: 
        !          5468: You specify the mode that the operand must have when you write the
        !          5469: @code{match_operand} expression.  The compiler automatically sees
        !          5470: which mode you have used and supplies an operand of that mode.
        !          5471: 
        !          5472: The value stored for a true condition must have 1 as its low bit.
        !          5473: Otherwise the instruction is not suitable and must be omitted from the
        !          5474: machine description.  You must tell the compiler exactly which value
        !          5475: is stored by defining the macro @code{STORE_FLAG_VALUE}.
        !          5476: 
        !          5477: @item @samp{b@var{cond}}
        !          5478: Conditional branch instruction.  Operand 0 is a @samp{label_ref}
        !          5479: that refers to the label to jump to.  Jump if the condition codes
        !          5480: meet condition @var{cond}.
        !          5481: 
        !          5482: @item @samp{call}
        !          5483: Subroutine call instruction returning no value.  Operand 0 is the
        !          5484: function to call; operand 1 is the number of bytes of arguments pushed
        !          5485: (in mode @code{SImode}, except it is normally a @samp{const_int});
        !          5486: operand 2 is the number of registers used as operands.
        !          5487: 
        !          5488: On most machines, operand 2 is not actually stored into the RTL
        !          5489: pattern.  It is supplied for the sake of some RISC machines which need
        !          5490: to put this information into the assembler code; they can put it in
        !          5491: the RTL instead of operand 1.
        !          5492: 
        !          5493: Operand 0 should be a @samp{mem} RTX whose address is the address of
        !          5494: the function.
        !          5495: 
        !          5496: @item @samp{call_value}
        !          5497: Subroutine call instruction returning a value.  Operand 0 is the hard
        !          5498: register in which the value is returned.  There are three more
        !          5499: operands, the same as the three operands of the @samp{call}
        !          5500: instruction (but with numbers increased by one).
        !          5501: 
        !          5502: Subroutines that return @code{BLKmode} objects use the @samp{call}
        !          5503: insn.
        !          5504: 
        !          5505: @item @samp{return}
        !          5506: Subroutine return instruction.  This instruction pattern name should be
        !          5507: defined only if a single instruction can do all the work of returning
        !          5508: from a function.
        !          5509: 
        !          5510: @item @samp{casesi}
        !          5511: Instruction to jump through a dispatch table, including bounds checking.
        !          5512: This instruction takes five operands:
        !          5513: 
        !          5514: @enumerate
        !          5515: @item
        !          5516: The index to dispatch on, which has mode @code{SImode}.
        !          5517: 
        !          5518: @item
        !          5519: The lower bound for indices in the table, an integer constant.
        !          5520: 
        !          5521: @item
        !          5522: The upper bound for indices in the table, an integer constant.
        !          5523: 
        !          5524: @item
        !          5525: A label to jump to if the index has a value outside the bounds.
        !          5526: (If the machine-description macro @code{CASE_DROPS_THROUGH} is defined,
        !          5527: then an out-of-bounds index drops through to the code following
        !          5528: the jump table instead of jumping to this label.  In that case,
        !          5529: this label is not actually used by the @samp{casesi} instruction,
        !          5530: but it is always provided as an operand.)
        !          5531: 
        !          5532: @item
        !          5533: A label that precedes the table itself.
        !          5534: @end enumerate
        !          5535: 
        !          5536: The table is a @samp{addr_vec} or @samp{addr_diff_vec} inside of a
        !          5537: @samp{jump_insn}.  The number of elements in the table is one plus the
        !          5538: difference between the upper bound and the lower bound.
        !          5539: 
        !          5540: @item @samp{tablejump}
        !          5541: Instruction to jump to a variable address.  This is a low-level
        !          5542: capability which can be used to implement a dispatch table when there
        !          5543: is no @samp{casesi} pattern.
        !          5544: 
        !          5545: This pattern requires two operands: the address or offset, and a label
        !          5546: which should immediately precede the jump table.  If the macro
        !          5547: @code{CASE_VECTOR_PC_RELATIVE} is defined then the first operand is an
        !          5548: absolute address to jump to; otherwise, it is an offset which counts
        !          5549: from the address of the table.
        !          5550: 
        !          5551: The @samp{tablejump} insn is always the last insn before the jump
        !          5552: table it uses.  Its assembler code normally has no need to use the
        !          5553: second operand, but you should incorporate it in the RTL pattern so
        !          5554: that the jump optimizer will not delete the table as unreachable code.
        !          5555: @end table
        !          5556: 
        !          5557: @node Pattern Ordering, Dependent Patterns, Standard Names, Machine Desc
        !          5558: @section When the Order of Patterns Matters
        !          5559: 
        !          5560: Sometimes an insn can match more than one instruction pattern.  Then the
        !          5561: pattern that appears first in the machine description is the one used.
        !          5562: Therefore, more specific patterns (patterns that will match fewer things)
        !          5563: and faster instructions (those that will produce better code when they
        !          5564: do match) should usually go first in the description.
        !          5565: 
        !          5566: In some cases the effect of ordering the patterns can be used to hide
        !          5567: a pattern when it is not valid.  For example, the 68000 has an
        !          5568: instruction for converting a fullword to floating point and another
        !          5569: for converting a byte to floating point.  An instruction converting
        !          5570: an integer to floating point could match either one.  We put the
        !          5571: pattern to convert the fullword first to make sure that one will
        !          5572: be used rather than the other.  (Otherwise a large integer might
        !          5573: be generated as a single-byte immediate quantity, which would not work.)
        !          5574: Instead of using this pattern ordering it would be possible to make the
        !          5575: pattern for convert-a-byte smart enough to deal properly with any
        !          5576: constant value.
        !          5577: 
        !          5578: @node Dependent Patterns, Jump Patterns, Pattern Ordering, Machine Desc
        !          5579: @section Interdependence of Patterns
        !          5580: 
        !          5581: Every machine description must have a named pattern for each of the
        !          5582: conditional branch names @samp{b@var{cond}}.  The recognition template
        !          5583: must always have the form
        !          5584: 
        !          5585: @example
        !          5586: (set (pc)
        !          5587:      (if_then_else (@var{cond} (cc0) (const_int 0))
        !          5588:                    (label_ref (match_operand 0 "" ""))
        !          5589:                    (pc)))
        !          5590: @end example
        !          5591: 
        !          5592: @noindent
        !          5593: In addition, every machine description must have an anonymous pattern
        !          5594: for each of the possible reverse-conditional branches.  These patterns
        !          5595: look like
        !          5596: 
        !          5597: @example
        !          5598: (set (pc)
        !          5599:      (if_then_else (@var{cond} (cc0) (const_int 0))
        !          5600:                    (pc)
        !          5601:                    (label_ref (match_operand 0 "" ""))))
        !          5602: @end example
        !          5603: 
        !          5604: @noindent
        !          5605: They are necessary because jump optimization can turn direct-conditional
        !          5606: branches into reverse-conditional branches.
        !          5607: 
        !          5608: The compiler does more with RTL than just create it from patterns
        !          5609: and recognize the patterns: it can perform arithmetic expression codes
        !          5610: when constant values for their operands can be determined.  As a result,
        !          5611: sometimes having one pattern can require other patterns.  For example, the
        !          5612: Vax has no `and' instruction, but it has `and not' instructions.  Here
        !          5613: is the definition of one of them:
        !          5614: 
        !          5615: @example
        !          5616: (define_insn "andcbsi2"
        !          5617:   [(set (match_operand:SI 0 "general_operand" "")
        !          5618:         (and:SI (match_dup 0)
        !          5619:                 (not:SI (match_operand:SI
        !          5620:                           1 "general_operand" ""))))]
        !          5621:   ""
        !          5622:   "bicl2 %1,%0")
        !          5623: @end example
        !          5624: 
        !          5625: @noindent
        !          5626: If operand 1 is an explicit integer constant, an instruction constructed
        !          5627: using that pattern can be simplified into an `and' like this:
        !          5628: 
        !          5629: @example
        !          5630: (set (reg:SI 41)
        !          5631:      (and:SI (reg:SI 41)
        !          5632:              (const_int 0xffff7fff)))
        !          5633: @end example
        !          5634: 
        !          5635: @noindent
        !          5636: (where the integer constant is the one's complement of what
        !          5637: appeared in the original instruction).
        !          5638: 
        !          5639: To avoid a fatal error, the compiler must have a pattern that recognizes
        !          5640: such an instruction.  Here is what is used:
        !          5641: 
        !          5642: @example
        !          5643: (define_insn ""
        !          5644:   [(set (match_operand:SI 0 "general_operand" "")
        !          5645:         (and:SI (match_dup 0)
        !          5646:                 (match_operand:SI 1 "general_operand" "")))]
        !          5647:   "GET_CODE (operands[1]) == CONST_INT"
        !          5648:   "*
        !          5649: @{ operands[1]
        !          5650:     = gen_rtx (CONST_INT, VOIDmode, ~INTVAL (operands[1]));
        !          5651:   return \"bicl2 %1,%0\";
        !          5652: @}")
        !          5653: @end example
        !          5654: 
        !          5655: @noindent
        !          5656: Whereas a pattern to match a general `and' instruction is impossible to
        !          5657: support on the Vax, this pattern is possible because it matches only a
        !          5658: constant second argument: a special case that can be output as an `and not'
        !          5659: instruction.
        !          5660: 
        !          5661: A ``compare'' instruction whose RTL looks like this:
        !          5662: 
        !          5663: @example
        !          5664: (set (cc0) (minus @var{operand} (const_int 0)))
        !          5665: @end example
        !          5666: 
        !          5667: @noindent
        !          5668: may be simplified by optimization into a ``test'' like this:
        !          5669: 
        !          5670: @example
        !          5671: (set (cc0) @var{operand})
        !          5672: @end example
        !          5673: 
        !          5674: @noindent
        !          5675: So in the machine description, each ``compare'' pattern for an integer
        !          5676: mode must have a corresponding ``test'' pattern that will match the
        !          5677: result of such simplification.
        !          5678: 
        !          5679: In some cases machines support instructions identical except for the
        !          5680: machine mode of one or more operands.  For example, there may be
        !          5681: ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
        !          5682: patterns are
        !          5683: 
        !          5684: @example
        !          5685: (set (match_operand:SI 0 @dots{})
        !          5686:      (extend:SI (match_operand:HI 1 @dots{})))
        !          5687: 
        !          5688: (set (match_operand:SI 0 @dots{})
        !          5689:      (extend:SI (match_operand:QI 1 @dots{})))
        !          5690: @end example
        !          5691: 
        !          5692: @noindent
        !          5693: Constant integers do not specify a machine mode, so an instruction to
        !          5694: extend a constant value could match either pattern.  The pattern it
        !          5695: actually will match is the one that appears first in the file.  For correct
        !          5696: results, this must be the one for the widest possible mode (@code{HImode},
        !          5697: here).  If the pattern matches the @code{QImode} instruction, the results
        !          5698: will be incorrect if the constant value does not actually fit that mode.
        !          5699: 
        !          5700: Such instructions to extend constants are rarely generated because they are
        !          5701: optimized away, but they do occasionally happen in nonoptimized
        !          5702: compilations.
        !          5703: 
        !          5704: When an instruction has the constraint letter @samp{o}, the reload
        !          5705: pass may generate instructions which copy a nonoffsetable address into
        !          5706: an index register.  The idea is that the register can be used as a
        !          5707: replacement offsetable address.  In order for these generated
        !          5708: instructions to work, there must be patterns to copy any kind of valid
        !          5709: address into a register.
        !          5710: 
        !          5711: Most older machine designs have ``load address'' instructions which do
        !          5712: just what is needed here.  Some RISC machines do not advertise such
        !          5713: instructions, but the possible addresses on these machines are very
        !          5714: limited, so it is easy to fake them.
        !          5715: 
        !          5716: Auto-increment and auto-decrement addresses are an exception; there
        !          5717: need not be an instruction that can copy such an address into a
        !          5718: register, because reload handles these cases in a different manner.
        !          5719: 
        !          5720: @node Jump Patterns, Peephole Definitions, Dependent Patterns, Machine Desc
        !          5721: @section Defining Jump Instruction Patterns
        !          5722: 
        !          5723: GNU CC assumes that the machine has a condition code.  A comparison insn
        !          5724: sets the condition code, recording the results of both signed and unsigned
        !          5725: comparison of the given operands.  A separate branch insn tests the
        !          5726: condition code and branches or not according its value.  The branch insns
        !          5727: come in distinct signed and unsigned flavors.  Many common machines, such
        !          5728: as the Vax, the 68000 and the 32000, work this way.
        !          5729: 
        !          5730: Some machines have distinct signed and unsigned compare instructions, and
        !          5731: only one set of conditional branch instructions.  The easiest way to handle
        !          5732: these machines is to treat them just like the others until the final stage
        !          5733: where assembly code is written.  At this time, when outputting code for the
        !          5734: compare instruction, peek ahead at the following branch using
        !          5735: @code{NEXT_INSN (insn)}.  (The variable @code{insn} refers to the insn
        !          5736: being output, in the output-writing code in an instruction pattern.)  If
        !          5737: the RTL says that is an unsigned branch, output an unsigned compare;
        !          5738: otherwise output a signed compare.  When the branch itself is output, you
        !          5739: can treat signed and unsigned branches identically.
        !          5740: 
        !          5741: The reason you can do this is that GNU CC always generates a pair of
        !          5742: consecutive RTL insns, one to set the condition code and one to test it,
        !          5743: and keeps the pair inviolate until the end.
        !          5744: 
        !          5745: To go with this technique, you must define the machine-description macro
        !          5746: @code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no
        !          5747: compare instruction is superfluous.
        !          5748: 
        !          5749: Some machines have compare-and-branch instructions and no condition code.
        !          5750: A similar technique works for them.  When it is time to ``output'' a
        !          5751: compare instruction, record its operands in two static variables.  When
        !          5752: outputting the branch-on-condition-code instruction that follows, actually
        !          5753: output a compare-and-branch instruction that uses the remembered operands.
        !          5754: 
        !          5755: It also works to define patterns for compare-and-branch instructions.
        !          5756: In optimizing compilation, the pair of compare and branch instructions
        !          5757: will be combined accoprding to these patterns.  But this does not happen
        !          5758: if optimization is not requested.  So you must use one of the solutions
        !          5759: above in addition to any special patterns you define.
        !          5760: 
        !          5761: @node Peephole Definitions, Expander Definitions, Jump Patterns, Machine Desc
        !          5762: @section Defining Machine-Specific Peephole Optimizers
        !          5763: 
        !          5764: In addition to instruction patterns the @file{md} file may contain
        !          5765: definitions of machine-specific peephole optimizations.
        !          5766: 
        !          5767: The combiner does not notice certain peephole optimizations when the data
        !          5768: flow in the program does not suggest that it should try them.  For example,
        !          5769: sometimes two consecutive insns related in purpose can be combined even
        !          5770: though the second one does not appear to use a register computed in the
        !          5771: first one.  A machine-specific peephole optimizer can detect such
        !          5772: opportunities.
        !          5773: 
        !          5774: A definition looks like this:
        !          5775: 
        !          5776: @example
        !          5777: (define_peephole
        !          5778:   [@var{insn-pattern-1}
        !          5779:    @var{insn-pattern-2}
        !          5780:    @dots{}]
        !          5781:   "@var{condition}"
        !          5782:   "@var{template}"
        !          5783:   "@var{machine-specific info}")
        !          5784: @end example
        !          5785: 
        !          5786: @noindent
        !          5787: The last string operand may be omitted if you are not using any
        !          5788: machine-specific information in this machine description.  If present,
        !          5789: it must obey the same rules as in a @samp{define_insn}.
        !          5790: 
        !          5791: In this skeleton, @var{insn-pattern-1} and so on are patterns to match
        !          5792: consecutive instructions.  The optimization applies to a sequence of
        !          5793: instructions when @var{insn-pattern-1} matches the first one,
        !          5794: @var{insn-pattern-2} matches the next, and so on.@refill
        !          5795: 
        !          5796: @var{insn-pattern-1} and so on look @emph{almost} like the second operand
        !          5797: of @code{define_insn}.  There is one important difference: this pattern is
        !          5798: an RTX, not a vector.  If the @code{define_insn} pattern would be a vector
        !          5799: of one element, the @var{insn-pattern} should be just that element, no
        !          5800: vector.  If the @code{define_insn} pattern would have multiple elements
        !          5801: then the @var{insn-pattern} must place the vector inside an explicit
        !          5802: @code{parallel} RTX.@refill
        !          5803: 
        !          5804: The operands of the instructions are matched with @code{match_operands} and
        !          5805: @code{match_dup}, as usual).  What is not usual is that the operand numbers
        !          5806: apply to all the instruction patterns in the definition.  So, you can check
        !          5807: for identical operands in two instructions by using @code{match_operand}
        !          5808: in one instruction and @code{match_dup} in the other.
        !          5809: 
        !          5810: The operand constraints used in @code{match_operand} patterns do not have
        !          5811: any direct effect on the applicability of the optimization, but they will
        !          5812: be validated afterward, so write constraints that are sure to fit whenever
        !          5813: the optimization is applied.  It is safe to use @code{"g"} for each
        !          5814: operand.
        !          5815: 
        !          5816: Once a sequence of instructions matches the patterns, the @var{condition}
        !          5817: is checked.  This is a C expression which makes the final decision whether
        !          5818: to perform the optimization (do so if the expression is nonzero).  If
        !          5819: @var{condition} is omitted (in other words, the string is empty) then the
        !          5820: optimization is applied to every sequence of instructions that matches the
        !          5821: patterns.
        !          5822: 
        !          5823: The defined peephole optimizations are applied after register allocation is
        !          5824: complete.  Therefore, the optimizer can check which operands have ended up
        !          5825: in which kinds of registers, just by looking at the operands.
        !          5826: 
        !          5827: The way to refer to the operands in @var{condition} is to write
        !          5828: @code{operands[@var{i}]} for operand number @var{i} (as matched by
        !          5829: @code{(match_operand @var{i} @dots{})}).  Use the variable @code{insn} to
        !          5830: refer to the last of the insns being matched; use @code{PREV_INSN} to find
        !          5831: the preceding insns (but be careful to skip over any @samp{note} insns that
        !          5832: intervene).@refill
        !          5833: 
        !          5834: When optimizing computations with intermediate results, you can use
        !          5835: @var{condition} to match only when the intermediate results are not used
        !          5836: elsewhere.  Use the C expression @code{dead_or_set_p (@var{insn},
        !          5837: @var{op})}, where @var{insn} is the insn in which you expect the value to
        !          5838: be used for the last time (from the value of @code{insn}, together with use
        !          5839: of @code{PREV_INSN}), and @var{op} is the intermediate value (from
        !          5840: @code{operands[@var{i}]}).@refill
        !          5841: 
        !          5842: Applying the optimization means replacing the sequence of instructions with
        !          5843: one new instruction.  The @var{template} controls ultimate output of
        !          5844: assembler code for this combined instruction.  It works exactly like the
        !          5845: template of a @code{define_insn}.  Operand numbers in this template are the
        !          5846: same ones used in matching the original sequence of instructions.
        !          5847: 
        !          5848: The result of a defined peephole optimizer does not need to match any of
        !          5849: the instruction patterns, and it does not have an opportunity to match
        !          5850: them.  The peephole optimizer definition itself serves as the instruction
        !          5851: pattern to control how the instruction is output.
        !          5852: 
        !          5853: Defined peephole optimizers are run in the last jump optimization pass, so
        !          5854: the instructions they produce are never combined or rearranged
        !          5855: automatically in any way.
        !          5856: 
        !          5857: Here is an example, taken from the 68000 machine description:
        !          5858: 
        !          5859: @example
        !          5860: (define_peephole
        !          5861:   [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
        !          5862:    (set (match_operand:DF 0 "register_operand" "f")
        !          5863:         (match_operand:DF 1 "register_operand" "ad"))]
        !          5864:   "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
        !          5865:   "*
        !          5866: @{
        !          5867:   rtx xoperands[2];
        !          5868:   xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1);
        !          5869: #ifdef MOTOROLA
        !          5870:   output_asm_insn (\"move.l %1,(sp)\", xoperands);
        !          5871:   output_asm_insn (\"move.l %1,-(sp)\", operands);
        !          5872:   return \"fmove.d (sp)+,%0\";
        !          5873: #else
        !          5874:   output_asm_insn (\"movel %1,sp@@\", xoperands);
        !          5875:   output_asm_insn (\"movel %1,sp@@-\", operands);
        !          5876:   return \"fmoved sp@@+,%0\";
        !          5877: #endif
        !          5878: @}
        !          5879: ")
        !          5880: @end example
        !          5881: 
        !          5882: The effect of this optimization is to change
        !          5883: 
        !          5884: @example
        !          5885: jbsr _foobar
        !          5886: addql #4,sp
        !          5887: movel d1,sp@@-
        !          5888: movel d0,sp@@-
        !          5889: fmoved sp@@+,fp0
        !          5890: @end example
        !          5891: 
        !          5892: @noindent
        !          5893: into
        !          5894: 
        !          5895: @example
        !          5896: jbsr _foobar
        !          5897: movel d1,sp@@
        !          5898: movel d0,sp@@-
        !          5899: fmoved sp@@+,fp0
        !          5900: @end example
        !          5901: 
        !          5902: @node Expander Definitions,, Peephole Definitions, Machine Desc
        !          5903: @section Defining RTL Sequences for Code Generation
        !          5904: 
        !          5905: On some target machines, some standard pattern names for RTL generation
        !          5906: cannot be handled with single insn, but a sequence of RTL insns can
        !          5907: represent them.  For these target machines, you can write a
        !          5908: @samp{define_expand} to specify how to generate the sequence of RTL.
        !          5909: 
        !          5910: A @samp{define_expand} is an RTL expression that looks almost like a
        !          5911: @samp{define_insn}; but, unlike the latter, a @samp{define_expand} is used
        !          5912: only for RTL generation and it can produce more than one RTL insn.
        !          5913: 
        !          5914: A @samp{define_expand} RTX has four operands:
        !          5915: 
        !          5916: @itemize @bullet
        !          5917: @item
        !          5918: The name.  Each @samp{define_expand} must have a name, since the only
        !          5919: use for it is to refer to it by name.
        !          5920: 
        !          5921: @item
        !          5922: The RTL template.  This is just like the RTL template for a
        !          5923: @samp{define_peephole} in that it is a vector of RTL expressions
        !          5924: each being one insn.
        !          5925: 
        !          5926: @item
        !          5927: The condition, a string containing a C expression.  This expression is
        !          5928: used to express how the availability of this pattern depends on
        !          5929: subclasses of target machine, selected by command-line options when
        !          5930: GNU CC is run.  This is just like the condition of a
        !          5931: @samp{define_insn} that has a standard name.
        !          5932: 
        !          5933: @item
        !          5934: The preparation statements, a string containing zero or more C
        !          5935: statements which are to be executed before RTL code is generated from
        !          5936: the RTL template.
        !          5937: 
        !          5938: Usually these statements prepare temporary registers for use as
        !          5939: internal operands in the RTL template, but they can also generate RTL
        !          5940: insns directly by calling routines such as @samp{emit_insn}, etc.
        !          5941: Any such insns precede the ones that come from the RTL template.
        !          5942: @end itemize
        !          5943: 
        !          5944: The RTL template, in addition to controlling generation of RTL insns,
        !          5945: also describes the operands that need to be specified when this pattern
        !          5946: is used.  In particular, it gives a predicate for each operand.
        !          5947: 
        !          5948: A true operand, which need to be specified in order to generate RTL from
        !          5949: the pattern, should be described with a @samp{match_operand} in its first
        !          5950: occurrence in the RTL template.  This enters information on the operand's
        !          5951: predicate into the tables that record such things.  GNU CC uses the
        !          5952: information to preload the operand into a register if that is required for
        !          5953: valid RTL code.  If the operand is referred to more than once, subsequent
        !          5954: references should use @samp{match_dup}.
        !          5955: 
        !          5956: The RTL template may also refer to internal ``operands'' which are
        !          5957: temporary registers or labels used only within the sequence made by the
        !          5958: @samp{define_expand}.  Internal operands are substituted into the RTL
        !          5959: template with @samp{match_dup}, never with @samp{match_operand}.  The
        !          5960: values of the internal operands are not passed in as arguments by the
        !          5961: compiler when it requests use of this pattern.  Instead, they are computed
        !          5962: within the pattern, in the preparation statements.  These statements
        !          5963: compute the values and store them into the appropriate elements of
        !          5964: @code{operands} so that @samp{match_dup} can find them.
        !          5965: 
        !          5966: There are two special macros defined for use in the preparation statements:
        !          5967: @code{DONE} and @code{FAIL}.  Use them with a following semicolon,
        !          5968: as a statement.
        !          5969: 
        !          5970: @table @code
        !          5971: @item DONE
        !          5972: Use the @code{DONE} macro to end RTL generation for the pattern.  The
        !          5973: only RTL insns resulting from the pattern on this occasion will be
        !          5974: those already emitted by explicit calls to @code{emit_insn} within the
        !          5975: preparation statements; the RTL template will not be generated.
        !          5976: 
        !          5977: @item FAIL
        !          5978: Make the pattern fail on this occasion.  When a pattern fails, it means
        !          5979: that the pattern was not truly available.  The calling routines in the
        !          5980: compiler will try other strategies for code generation using other patterns.
        !          5981: 
        !          5982: Failure is currently supported only for binary operations (addition,
        !          5983: multiplication, shifting, etc.).
        !          5984: 
        !          5985: Do not emit any insns explicitly with @code{emit_insn} before failing.
        !          5986: @end table
        !          5987: 
        !          5988: Here is an example, the definition of left-shift for the SPUR chip:
        !          5989: 
        !          5990: @example
        !          5991: (define_expand "ashlsi3"
        !          5992:   [(set (match_operand:SI 0 "register_operand" "")
        !          5993:         (ashift:SI
        !          5994:           (match_operand:SI 1 "register_operand" "")
        !          5995:           (match_operand:SI 2 "nonmemory_operand" "")))]
        !          5996:   ""
        !          5997:   "
        !          5998: @{
        !          5999:   if (GET_CODE (operands[2]) != CONST_INT
        !          6000:       || (unsigned) INTVAL (operands[2]) > 3)
        !          6001:     FAIL;
        !          6002: @}")
        !          6003: @end example
        !          6004: 
        !          6005: @noindent
        !          6006: This example uses @samp{define_expand} so that it can generate an RTL insn
        !          6007: for shifting when the shift-count is in the supported range of 0 to 3 but
        !          6008: fail in other cases where machine insns aren't available.  When it fails,
        !          6009: the compiler tries another strategy using different patterns (such as, a
        !          6010: library call).
        !          6011: 
        !          6012: If the compiler were able to handle nontrivial condition-strings in
        !          6013: patterns with names, then there would be possible to use a
        !          6014: @samp{define_insn} in that case.  Here is another case (zero-extension on
        !          6015: the 68000) which makes more use of the power of @samp{define_expand}:
        !          6016: 
        !          6017: @example
        !          6018: (define_expand "zero_extendhisi2"
        !          6019:   [(set (match_operand:SI 0 "general_operand" "")
        !          6020:         (const_int 0))
        !          6021:    (set (strict_low_part 
        !          6022:           (subreg:HI
        !          6023:             (match_operand:SI 0 "general_operand" "")
        !          6024:             0))
        !          6025:         (match_operand:HI 1 "general_operand" ""))]
        !          6026:   ""
        !          6027:   "operands[1] = make_safe_from (operands[1], operands[0]);")
        !          6028: @end example
        !          6029: 
        !          6030: @noindent
        !          6031: Here two RTL insns are generated, one to clear the entire output operand
        !          6032: and the other to copy the input operand into its low half.  This sequence
        !          6033: is incorrect if the input operand refers to [the old value of] the output
        !          6034: operand, so the preparation statement makes sure this isn't so.  The
        !          6035: function @code{make_safe_from} copies the @code{operands[1]} into a
        !          6036: temporary register if it refers to @code{operands[0]}.  It does this
        !          6037: by emitting another RTL insn.
        !          6038: 
        !          6039: Finally, a third example shows the use of an internal operand.
        !          6040: Zero-extension on the SPUR chip is done by @samp{and}-ing the result
        !          6041: against a halfword mask.  But this mask cannot be represented by a
        !          6042: @samp{const_int} because the constant value is too large to be legitimate
        !          6043: on this machine.  So it must be copied into a register with
        !          6044: @code{force_reg} and then the register used in the @samp{and}.
        !          6045: 
        !          6046: @example
        !          6047: (define_expand "zero_extendhisi2"
        !          6048:   [(set (match_operand:SI 0 "register_operand" "")
        !          6049:         (and:SI (subreg:SI
        !          6050:                   (match_operand:HI 1 "register_operand" "")
        !          6051:                   0)
        !          6052:                 (match_dup 2)))]
        !          6053:   ""
        !          6054:   "operands[2]
        !          6055:      = force_reg (SImode, gen_rtx (CONST_INT,
        !          6056:                                    VOIDmode, 65535)); ")
        !          6057: @end example
        !          6058: 
        !          6059: @node Machine Macros, Config, Machine Desc, Top
        !          6060: @chapter Machine Description Macros
        !          6061: 
        !          6062: The other half of the machine description is a C header file conventionally
        !          6063: given the name @file{tm-@var{machine}.h}.  The file @file{tm.h} should be a
        !          6064: link to it.  The header file @file{config.h} includes @file{tm.h} and most
        !          6065: compiler source files include @file{config.h}.
        !          6066: 
        !          6067: @menu
        !          6068: * Run-time Target::     Defining -m options like -m68000 and -m68020.
        !          6069: * Storage Layout::      Defining sizes and alignments of data types.
        !          6070: * Registers::           Naming and describing the hardware registers.
        !          6071: * Register Classes::    Defining the classes of hardware registers.
        !          6072: * Stack Layout::        Defining which way the stack grows and by how much.
        !          6073: * Library Names::       Specifying names of subroutines to call automatically.
        !          6074: * Addressing Modes::    Defining addressing modes valid for memory operands.
        !          6075: * Condition Code::      Defining how insns update the condition code.
        !          6076: * Assembler Format::    Defining how to write insns and pseudo-ops to output.
        !          6077: * Misc::                Everything else.
        !          6078: @end menu
        !          6079: 
        !          6080: @node Run-time Target, Storage Layout, Machine Macros, Machine Macros
        !          6081: @section Run-time Target Specification
        !          6082: 
        !          6083: @table @code
        !          6084: @item CPP_PREDEFINES
        !          6085: Define this to be a string constant containing @samp{-D} options to
        !          6086: define the predefined macros that identify this machine and system.
        !          6087: These macros will be predefined unless the @samp{-ansi} option is
        !          6088: specified.
        !          6089: 
        !          6090: For example, on the Sun, one can use the value
        !          6091: 
        !          6092: @example
        !          6093: "-Dmc68000 -Dsun -Dunix"
        !          6094: @end example
        !          6095: 
        !          6096: @item CPP_SPEC
        !          6097: A C string constant that tells the GNU CC driver program options to
        !          6098: pass to CPP.  It can also specify how to translate options you
        !          6099: give to GNU CC into options for GNU CC to pass to the CPP.
        !          6100: 
        !          6101: Do not define this macro if it does not need to do anything.
        !          6102: 
        !          6103: @item CC1_SPEC
        !          6104: A C string constant that tells the GNU CC driver program options to
        !          6105: pass to CC1.  It can also specify how to translate options you
        !          6106: give to GNU CC into options for GNU CC to pass to the CC1.
        !          6107: 
        !          6108: Do not define this macro if it does not need to do anything.
        !          6109: 
        !          6110: @item extern int target_flags;
        !          6111: This declaration should be present.
        !          6112: 
        !          6113: @item TARGET_@dots{}
        !          6114: This series of macros is to allow compiler command arguments to
        !          6115: enable or disable the use of optional features of the target machine.
        !          6116: For example, one machine description serves both the 68000 and
        !          6117: the 68020; a command argument tells the compiler whether it should
        !          6118: use 68020-only instructions or not.  This command argument works
        !          6119: by means of a macro @code{TARGET_68020} that tests a bit in
        !          6120: @code{target_flags}.
        !          6121: 
        !          6122: Define a macro @code{TARGET_@var{featurename}} for each such option.
        !          6123: Its definition should test a bit in @code{target_flags}; for example:
        !          6124: 
        !          6125: @example
        !          6126: #define TARGET_68020 (target_flags & 1)
        !          6127: @end example
        !          6128: 
        !          6129: One place where these macros are used is in the condition-expressions
        !          6130: of instruction patterns.  Note how @code{TARGET_68020} appears
        !          6131: frequently in the 68000 machine description file, @file{m68k.md}.
        !          6132: Another place they are used is in the definitions of the other
        !          6133: macros in the @file{tm-@var{machine}.h} file.
        !          6134: 
        !          6135: @item TARGET_SWITCHES
        !          6136: This macro defines names of command options to set and clear
        !          6137: bits in @code{target_flags}.  Its definition is an initializer
        !          6138: with a subgrouping for each command option.
        !          6139: 
        !          6140: Each subgrouping contains a string constant, that defines the option
        !          6141: name, and a number, which contains the bits to set in
        !          6142: @code{target_flags}.  A negative number says to clear bits instead;
        !          6143: the negative of the number is which bits to clear.  The actual option
        !          6144: name is made by appending @samp{-m} to the specified name.
        !          6145: 
        !          6146: One of the subgroupings should have a null string.  The number in
        !          6147: this grouping is the default value for @code{target_flags}.  Any
        !          6148: target options act starting with that value.
        !          6149: 
        !          6150: Here is an example which defines @samp{-m68000} and @samp{-m68020}
        !          6151: with opposite meanings, and picks the latter as the default:
        !          6152: 
        !          6153: @example
        !          6154: #define TARGET_SWITCHES \
        !          6155:   @{ @{ "68020", 1@},      \
        !          6156:     @{ "68000", -1@},     \
        !          6157:     @{ "", 1@}@}
        !          6158: @end example
        !          6159: 
        !          6160: @item OVERRIDE_OPTIONS
        !          6161: Sometimes certain combinations of command options do not make sense on
        !          6162: a particular target machine.  You can define a macro
        !          6163: @code{OVERRIDE_OPTIONS} to take account of this.  This macro, if
        !          6164: defined, is executed once just after all the command options have been
        !          6165: parsed.
        !          6166: @end table
        !          6167: 
        !          6168: @node Storage Layout, Registers, Run-time Target, Machine Macros
        !          6169: @section Storage Layout
        !          6170: 
        !          6171: Note that the definitions of the macros in this table which are sizes or
        !          6172: alignments measured in bits do not need to be constant.  They can be C
        !          6173: expressions that refer to static variables, such as the @code{target_flags}.
        !          6174: @xref{Run-time Target}.
        !          6175: 
        !          6176: @table @code
        !          6177: @item BITS_BIG_ENDIAN
        !          6178: Define this macro if the most significant bit in a byte has the lowest
        !          6179: number.  This means that bit-field instructions count from the most
        !          6180: significant bit.  If the machine has no bit-field instructions, this
        !          6181: macro is irrelevant.
        !          6182: 
        !          6183: @item BYTES_BIG_ENDIAN
        !          6184: Define this macro if the most significant byte in a word has the
        !          6185: lowest number.
        !          6186: 
        !          6187: @item WORDS_BIG_ENDIAN
        !          6188: Define this macro if, in a multiword object, the most significant
        !          6189: word has the lowest number.
        !          6190: 
        !          6191: @item BITS_PER_UNIT
        !          6192: Number of bits in an addressable storage unit (byte); normally 8.
        !          6193: 
        !          6194: @item BITS_PER_WORD
        !          6195: Number of bits in a word; normally 32.
        !          6196: 
        !          6197: @item UNITS_PER_WORD
        !          6198: Number of storage units in a word; normally 4.
        !          6199: 
        !          6200: @item POINTER_SIZE
        !          6201: Width of a pointer, in bits.
        !          6202: 
        !          6203: @item POINTER_BOUNDARY
        !          6204: Alignment required for pointers stored in memory, in bits.
        !          6205: 
        !          6206: @item PARM_BOUNDARY
        !          6207: Alignment required for function parameters on the stack, in bits.
        !          6208: 
        !          6209: @item STACK_BOUNDARY
        !          6210: Define this macro if you wish to preserve a certain alignment for
        !          6211: the stack pointer at all times.  The definition is a C expression
        !          6212: for the desired alignment (measured in bits).
        !          6213: 
        !          6214: @item FUNCTION_BOUNDARY
        !          6215: Alignment required for a function entry point, in bits.
        !          6216: 
        !          6217: @item BIGGEST_ALIGNMENT
        !          6218: Biggest alignment that any data type can require on this machine, in bits.
        !          6219: 
        !          6220: @item EMPTY_FIELD_BOUNDARY
        !          6221: Alignment in bits to be given to a structure bit field that follows an
        !          6222: empty field such as @code{int : 0;}.
        !          6223: 
        !          6224: @item STRUCTURE_SIZE_BOUNDARY
        !          6225: Number of bits which any structure or union's size must be a multiple of.
        !          6226: Each structure or union's size is rounded up to a multiple of this.
        !          6227: 
        !          6228: If you do not define this macro, the default is the same as
        !          6229: @code{BITS_PER_UNIT}.
        !          6230: 
        !          6231: @item STRICT_ALIGNMENT
        !          6232: Define this if instructions will fail to work if given data not
        !          6233: on the nominal alignment.  If instructions will merely go slower
        !          6234: in that case, do not define this macro.
        !          6235: 
        !          6236: @item PCC_BITFIELD_TYPE_MATTERS
        !          6237: Define this if you wish to imitate a certain bizarre behavior pattern
        !          6238: of some instances of PCC: a bit field whose declared type is
        !          6239: @code{int} has the same effect on the size and alignment of a
        !          6240: structure as an actual @code{int} would have.
        !          6241: 
        !          6242: Just what effect that is in GNU CC depends on other parameters, but on
        !          6243: most machines it would force the structure's alignment and size to a
        !          6244: multiple of 32 or @code{BIGGEST_ALIGNMENT} bits.
        !          6245: 
        !          6246: @item CHECK_FLOAT_VALUE (@var{mode}, @var{value})
        !          6247: A C statement to validate the value @var{value} (or type
        !          6248: @code{double}) for mode @var{mode}.  This means that you check whether
        !          6249: @var{value} fits within the possible range of values for mode
        !          6250: @var{mode} on this target machine.  The mode @var{mode} is always
        !          6251: @code{SFmode} or @code{DFmode}.
        !          6252: 
        !          6253: If @var{value} is not valid, you should call @code{error} to print an
        !          6254: error message and then assign some valid value to @var{value}.
        !          6255: Allowing an invalid value to go through the compiler can produce
        !          6256: incorrect assembler code which may even cause Unix assemblers to
        !          6257: crash.
        !          6258: 
        !          6259: This macro need not be defined if there is no work for it to do.
        !          6260: @end table
        !          6261: 
        !          6262: @node Registers, Register Classes, Storage Layout, Machine Macros
        !          6263: @section Register Usage
        !          6264: 
        !          6265: @table @code
        !          6266: @item FIRST_PSEUDO_REGISTER
        !          6267: Number of hardware registers known to the compiler.  They receive
        !          6268: numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
        !          6269: pseudo register's number really is assigned the number
        !          6270: @code{FIRST_PSEUDO_REGISTER}.
        !          6271: 
        !          6272: @item FIXED_REGISTERS
        !          6273: An initializer that says which registers are used for fixed purposes
        !          6274: all throughout the compiled code and are therefore not available for
        !          6275: general allocation.  These would include the stack pointer, the frame
        !          6276: pointer (except on machines where that can be used as a general
        !          6277: register when no frame pointer is needed), the program counter on
        !          6278: machines where that is considered one of the addressable registers,
        !          6279: and any other numbered register with a standard use.
        !          6280: 
        !          6281: This information is expressed as a sequence of numbers, separated by
        !          6282: commas and surrounded by braces.  The @var{n}th number is 1 if
        !          6283: register @var{n} is fixed, 0 otherwise.
        !          6284: 
        !          6285: The table initialized from this macro, and the table initialized by
        !          6286: the following one, may be overridden at run time either automatically,
        !          6287: by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
        !          6288: the user with the command options @samp{-ffixed-@var{reg}},
        !          6289: @samp{-fcall-used-@var{reg}} and @samp{-fcall-saved-@var{reg}}.
        !          6290: 
        !          6291: @item CALL_USED_REGISTERS
        !          6292: Like @code{FIXED_REGISTERS} but has 1 for each register that is
        !          6293: clobbered (in general) by function calls as well as for fixed
        !          6294: registers.  This macro therefore identifies the registers that are not
        !          6295: available for general allocation of values that must live across
        !          6296: function calls.
        !          6297: 
        !          6298: If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
        !          6299: automatically saves it on function entry and restores it on function
        !          6300: exit, if the register is used within the function.
        !          6301: 
        !          6302: @item CONDITIONAL_REGISTER_USAGE
        !          6303: Zero or more C statements that may conditionally modify two variables
        !          6304: @code{fixed_regs} and @code{call_used_regs} (both of type @code{char
        !          6305: []}) after they have been initialized from the two preceding macros.
        !          6306: 
        !          6307: This is necessary in case the fixed or call-clobbered registers depend
        !          6308: on target flags.
        !          6309: 
        !          6310: You need not define this macro if it has no work to do.
        !          6311: 
        !          6312: If the usage of an entire class of registers depends on the target
        !          6313: flags, you may indicate this to gcc by using this macro to modify
        !          6314: @code{fixed_regs} and @code{call_used_regs} to 1 for each of the
        !          6315: registers in the classes which should not be used by gcc.  Also define
        !          6316: the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it
        !          6317: is called with a letter for a class that shouldn't be used.
        !          6318: 
        !          6319: (However, if this class is not included in @code{GENERAL_REGS} and all
        !          6320: of the insn patterns whose constraints permit this class are
        !          6321: controlled by target switches, then GCC will automatically avoid using
        !          6322: these registers when the target switches are opposed to them.)
        !          6323: 
        !          6324: @item OVERLAPPING_REGNO_P (@var{regno})
        !          6325: If defined, this is a C expression whose value is @var{regno} is
        !          6326: nonzero if hard register number @var{regno} is an overlapping
        !          6327: register.  This means a hard register which overlaps a hard register
        !          6328: with a different number.  (Such overlap is undesirable, but
        !          6329: occasionally it allows a machine to be supported which otherwise could
        !          6330: not be.)  This macro must return nonzero for @emph{all} the registers
        !          6331: which overlap each other.  GNU CC can use an overlapping register only
        !          6332: in certain limited ways.  It can be used for allocation within a basic
        !          6333: block, and may be spilled for reloading; that is all.
        !          6334: 
        !          6335: If this macro is not defined, it means that none of the hard registers
        !          6336: overlap each other.  This is the usual situation.
        !          6337: 
        !          6338: @item INSN_CLOBBERS_REGNO_P (@var{insn}, @var{regno})
        !          6339: If defined, this is a C expression whose value should be nonzero if
        !          6340: the insn @var{insn} has the effect of mysteriously clobbering the
        !          6341: contents of hard register number @var{regno}.  By ``mysterious'' we
        !          6342: mean that the insn's RTL expression doesn't describe such an effect.
        !          6343: 
        !          6344: If this macro is not defined, it means that no insn clobbers registers
        !          6345: mysteriously.  This is the usual situation; all else being equal,
        !          6346: it is best for the RTL expression to show all the activity.
        !          6347: 
        !          6348: @item PRESERVE_DEATH_INFO_REGNO_P (@var{regno})
        !          6349: If defined, this is a C expression whose value is nonzero if accurate
        !          6350: @code{REG_DEAD} notes are needed for hard register number @var{regno}
        !          6351: at the time of outputting the assembler code.  When this is so, a few
        !          6352: optimizations that take place after register allocation and could
        !          6353: invalidate the death notes are not done when this register is
        !          6354: involved.
        !          6355: 
        !          6356: You would arrange to preserve death info for a register when some
        !          6357: of the code in the machine description which is executed to write
        !          6358: the assembler code looks at the the death notes.  This is
        !          6359: necessary only when the actual hardware feature which GNU CC
        !          6360: thinks of as a register is not actually a register of the usual sort.
        !          6361: (It might, for example, be a hardware stack.)
        !          6362: 
        !          6363: If this macro is not defined, it means that no death notes need to be
        !          6364: preserved.  This is the usual situation.
        !          6365: 
        !          6366: @item HARD_REGNO_REGS (@var{regno}, @var{mode})
        !          6367: A C expression for the number of consecutive hard registers, starting
        !          6368: at register number @var{regno}, required to hold a value of mode
        !          6369: @var{mode}.
        !          6370: 
        !          6371: On a machine where all registers are exactly one word, a suitable
        !          6372: definition of this macro is
        !          6373: 
        !          6374: @example
        !          6375: #define HARD_REGNO_NREGS(REGNO, MODE)            \
        !          6376:    ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1)  \
        !          6377:     / UNITS_PER_WORD))
        !          6378: @end example
        !          6379: 
        !          6380: @item HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
        !          6381: A C expression that is nonzero if it is permissible to store a value
        !          6382: of mode @var{mode} in hard register number @var{regno} (or in several
        !          6383: registers starting with that one).  For a machine where all registers
        !          6384: are equivalent, a suitable definition is
        !          6385: 
        !          6386: @example
        !          6387: #define HARD_REGNO_MODE_OK(REGNO, MODE) 1
        !          6388: @end example
        !          6389: 
        !          6390: It is not necessary for this macro to check for fixed register numbers
        !          6391: because the allocation mechanism considers them to be always occupied.
        !          6392: 
        !          6393: Many machines have special registers for floating point arithmetic.
        !          6394: Often people assume that floating point machine modes are allowed only
        !          6395: in floating point registers.  This is not true.  Any registers that
        !          6396: can hold integers can safely @emph{hold} a floating point machine
        !          6397: mode, whether or not floating arithmetic can be done on it in those
        !          6398: registers.
        !          6399: 
        !          6400: The true significance of special floating registers is rather than
        !          6401: non-floating-point machine modes @emph{may not} go in those registers.
        !          6402: This is true if the floating registers normalize any value stored in
        !          6403: them, because storing a non-floating value there would garble it.  If
        !          6404: the floating registers do not automatically normalize, if you can
        !          6405: store any bit pattern in one and retrieve it unchanged without a trap,
        !          6406: then any machine mode may go in a floating register and this macro
        !          6407: should say so.
        !          6408: 
        !          6409: Sometimes there are floating registers that are especially slow to
        !          6410: access, so that it is better to store a value in a stack frame than in
        !          6411: such a register if floating point arithmetic is not being done.  As long
        !          6412: as the floating registers are not in class @code{GENERAL_REGS}, they
        !          6413: will not be used unless some insn's constraint asks for one.
        !          6414: 
        !          6415: It is obligatory to support floating point `move' instructions into
        !          6416: and out of any registers that can hold fixed point values, because
        !          6417: unions and structures (which have modes @samp{SImode} or
        !          6418: @samp{DImode}) can be in those registers and they may have floating
        !          6419: point members.
        !          6420: 
        !          6421: There may also be a need to support fixed point `move' instructions in
        !          6422: and out of floating point registers.  Unfortunately, I have forgotten
        !          6423: why this was so, and I don't know whether it is still true.  If
        !          6424: @code{HARD_REGNO_MODE_OK} rejects fixed point values in floating point
        !          6425: registers, then the constraints of the fixed point `move' instructions
        !          6426: must be designed to avoid ever trying to reload into a floating point
        !          6427: register.
        !          6428: 
        !          6429: @item MODES_TIEABLE_P (@var{mode1}, @var{mode2})
        !          6430: A C expression that is nonzero if it is desirable to choose register
        !          6431: allocation so as to avoid move instructions between a value of mode
        !          6432: @var{mode1} and a value of mode @var{mode2}.
        !          6433: 
        !          6434: If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
        !          6435: @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different
        !          6436: for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1},
        !          6437: @var{mode2})} must be zero.
        !          6438: 
        !          6439: @item PC_REGNUM
        !          6440: If the program counter has a register number, define this as that
        !          6441: register number.  Otherwise, do not define it.
        !          6442: 
        !          6443: @item STACK_POINTER_REGNUM
        !          6444: The register number of the stack pointer register, which must also be
        !          6445: a fixed register according to @code{FIXED_REGISTERS}.  On many
        !          6446: machines, the hardware determines which register this is.
        !          6447: 
        !          6448: @item FRAME_POINTER_REGNUM
        !          6449: The register number of the frame pointer register, which is used to
        !          6450: access automatic variables in the stack frame.  On some machines, the
        !          6451: hardware determines which register this is.  On other machines, you
        !          6452: can choose any register you wish for this purpose.
        !          6453: 
        !          6454: @item FRAME_POINTER_REQUIRED
        !          6455: A C expression which is nonzero if a function must have and use a
        !          6456: frame pointer.  This expression is evaluated in the reload pass, in
        !          6457: the function @code{reload}, and it can in principle examine the
        !          6458: current function and decide according to the facts, but on most
        !          6459: machines the constant 0 or the constant 1 suffices.  Use 0 when the
        !          6460: machine allows code to be generated with no frame pointer, and doing
        !          6461: so saves some time or space.  Use 1 when there is no possible
        !          6462: advantage to avoiding a frame pointer.
        !          6463: 
        !          6464: In certain cases, the compiler does not know how to do without a frame
        !          6465: pointer.  The compiler recognizes those cases and automatically gives
        !          6466: the function a frame pointer regardless of what
        !          6467: @code{FRAME_POINTER_REQUIRED} says.  You don't need to worry about
        !          6468: them.@refill
        !          6469: 
        !          6470: In a function that does not require a frame pointer, the frame pointer
        !          6471: register can be allocated for ordinary usage, unless you mark it as a
        !          6472: fixed register.  See @code{FIXED_REGISTERS} for more information.
        !          6473: 
        !          6474: @item ARG_POINTER_REGNUM
        !          6475: The register number of the arg pointer register, which is used to
        !          6476: access the function's argument list.  On some machines, this is the
        !          6477: same as the frame pointer register.  On some machines, the hardware
        !          6478: determines which register this is.  On other machines, you can choose
        !          6479: any register you wish for this purpose.  If this is not the same
        !          6480: register as the frame pointer register, then you must mark it as a
        !          6481: fixed register according to @code{FIXED_REGISTERS}.
        !          6482: 
        !          6483: @item STATIC_CHAIN_REGNUM
        !          6484: The register number used for passing a function's static chain
        !          6485: pointer.  This is needed for languages such as Pascal and Algol where
        !          6486: functions defined within other functions can access the local
        !          6487: variables of the outer functions; it is not currently used because C
        !          6488: does not provide this feature, but you must define the macro.
        !          6489: 
        !          6490: The static chain register need not be a fixed register.
        !          6491: 
        !          6492: @item STRUCT_VALUE_REGNUM
        !          6493: When a function's value's mode is @code{BLKmode}, the value is not
        !          6494: returned according to @code{FUNCTION_VALUE}.  Instead, the caller
        !          6495: passes the address of a block of memory in which the value should be
        !          6496: stored.
        !          6497: 
        !          6498: If this value is passed in a register, then @code{STRUCT_VALUE_REGNUM}
        !          6499: should be the number of that register.
        !          6500: 
        !          6501: @item STRUCT_VALUE
        !          6502: If the structure value address is not passed in a register, define
        !          6503: @code{STRUCT_VALUE} as an expression returning an RTX for the place
        !          6504: where the address is passed.  If it returns a @samp{mem} RTX, the
        !          6505: address is passed as an ``invisible'' first argument.
        !          6506: 
        !          6507: @item STRUCT_VALUE_INCOMING_REGNUM
        !          6508: On some architectures the place where the structure value address
        !          6509: is found by the called function is not the same place that the
        !          6510: caller put it.  This can be due to register windows, or it could
        !          6511: be because the function prologue moves it to a different place.
        !          6512: 
        !          6513: If the incoming location of the structure value address is in a
        !          6514: register, define this macro as the register number.
        !          6515: 
        !          6516: @item STRUCT_VALUE_INCOMING
        !          6517: If the incoming location is not a register, define
        !          6518: @code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the
        !          6519: called function should find the value.  If it should find the value on
        !          6520: the stack, define this to create a @samp{mem} which refers to the
        !          6521: frame pointer.  If the value is a @samp{mem}, the compiler assumes it
        !          6522: is for an invisible first argument, and leaves space for it when
        !          6523: finding the first real argument.
        !          6524: 
        !          6525: @item REG_ALLOC_ORDER
        !          6526: If defined, an initializer for a vector of integers, containing the
        !          6527: numbers of hard registers in the order in which the GNU CC should
        !          6528: prefer to use them (from most preferred to least).
        !          6529: 
        !          6530: If this macro is not defined, registers are used lowest numbered first
        !          6531: (all else being equal).
        !          6532: 
        !          6533: One use of this macro is on the 360, where the highest numbered
        !          6534: registers must always be saved and the save-multiple-registers
        !          6535: instruction supports only sequences of consecutive registers.  This
        !          6536: macro is defined to cause the highest numbered allocatable registers
        !          6537: to be used first.
        !          6538: @end table
        !          6539: 
        !          6540: @node Register Classes, Stack Layout, Registers, Machine Macros
        !          6541: @section Register Classes
        !          6542: 
        !          6543: On many machines, the numbered registers are not all equivalent.
        !          6544: For example, certain registers may not be allowed for indexed addressing;
        !          6545: certain registers may not be allowed in some instructions.  These machine
        !          6546: restrictions are described to the compiler using @dfn{register classes}.
        !          6547: 
        !          6548: You define a number of register classes, giving each one a name and saying
        !          6549: which of the registers belong to it.  Then you can specify register classes
        !          6550: that are allowed as operands to particular instruction patterns.
        !          6551: 
        !          6552: In general, each register will belong to several classes.  In fact, one
        !          6553: class must be named @code{ALL_REGS} and contain all the registers.  Another
        !          6554: class must be named @code{NO_REGS} and contain no registers.  Often the
        !          6555: union of two classes will be another class; however, this is not required.
        !          6556: 
        !          6557: One of the classes must be named @code{GENERAL_REGS}.  There is nothing
        !          6558: terribly special about the name, but the operand constraint letters
        !          6559: @samp{r} and @samp{g} specify this class.  If @code{GENERAL_REGS} is
        !          6560: the same as @code{ALL_REGS}, just define it as a macro which expands
        !          6561: to @code{ALL_REGS}.
        !          6562: 
        !          6563: The way classes other than @code{GENERAL_REGS} are specified in operand
        !          6564: constraints is through machine-dependent operand constraint letters.
        !          6565: You can define such letters to correspond to various classes, then use
        !          6566: them in operand constraints.
        !          6567: 
        !          6568: You should define a class for the union of two classes whenever some
        !          6569: instruction allows both classes.  For example, if an instruction allows
        !          6570: either a floating-point (coprocessor) register or a general register for a
        !          6571: certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
        !          6572: which includes both of them.  Otherwise you will get suboptimal code.
        !          6573: 
        !          6574: You must also specify certain redundant information about the register
        !          6575: classes: for each class, which classes contain it and which ones are
        !          6576: contained in it; for each pair of classes, the largest class contained
        !          6577: in their union.
        !          6578: 
        !          6579: Register classes used for input-operands of bitwise-and or shift
        !          6580: instructions have a special requirement: each such class must have, for
        !          6581: each fixed-point machine mode, a subclass whose registers can transfer that
        !          6582: mode to or from memory.  For example, on some machines, the operations for
        !          6583: single-byte values (@code{QImode}) are limited to certain registers.  When
        !          6584: this is so, each register class that is used in a bitwise-and or shift
        !          6585: instruction must have a subclass consisting of registers from which
        !          6586: single-byte values can be loaded or stored.  This is so that
        !          6587: @code{PREFERRED_RELOAD_CLASS} can always have a possible value to return.
        !          6588: 
        !          6589: @table @code
        !          6590: @item enum reg_class
        !          6591: An enumeral type that must be defined with all the register class names
        !          6592: as enumeral values.  @code{NO_REGS} must be first.  @code{ALL_REGS}
        !          6593: must be the last register class, followed by one more enumeral value,
        !          6594: @code{LIM_REG_CLASSES}, which is not a register class but rather
        !          6595: tells how many classes there are.
        !          6596: 
        !          6597: Each register class has a number, which is the value of casting
        !          6598: the class name to type @code{int}.  The number serves as an index
        !          6599: in many of the tables described below.
        !          6600: 
        !          6601: @item N_REG_CLASSES
        !          6602: The number of distinct register classes, defined as follows:
        !          6603: 
        !          6604: @example
        !          6605: #define N_REG_CLASSES (int) LIM_REG_CLASSES
        !          6606: @end example
        !          6607: 
        !          6608: @item REG_CLASS_NAMES
        !          6609: An initializer containing the names of the register classes as C string
        !          6610: constants.  These names are used in writing some of the debugging dumps.
        !          6611: 
        !          6612: @item REG_CLASS_CONTENTS
        !          6613: An initializer containing the contents of the register classes, as integers
        !          6614: which are bit masks.  The @var{n}th integer specifies the contents of class
        !          6615: @var{n}.  The way the integer @var{mask} is interpreted is that
        !          6616: register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
        !          6617: 
        !          6618: When the machine has more than 32 registers, an integer does not suffice.
        !          6619: Then the integers are replaced by sub-initializers, braced groupings containing
        !          6620: several integers.  Each sub-initializer must be suitable as an initializer
        !          6621: for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
        !          6622: 
        !          6623: @item REGNO_REG_CLASS (@var{regno})
        !          6624: A C expression whose value is a register class containing hard register
        !          6625: @var{regno}.  In general there is more that one such class; choose a class
        !          6626: which is @dfn{minimal}, meaning that no smaller class also contains the
        !          6627: register.
        !          6628: 
        !          6629: @item BASE_REG_CLASS
        !          6630: A macro whose definition is the name of the class to which a valid
        !          6631: base register must belong.  A base register is one used in an address
        !          6632: which is the register value plus a displacement.
        !          6633: 
        !          6634: @item INDEX_REG_CLASS
        !          6635: A macro whose definition is the name of the class to which a valid
        !          6636: index register must belong.  An index register is one used in an
        !          6637: address where its value is either multiplied by a scale factor or
        !          6638: added to another register (as well as added to a displacement).
        !          6639: 
        !          6640: @item REG_CLASS_FROM_LETTER (@var{char})
        !          6641: A C expression which defines the machine-dependent operand constraint
        !          6642: letters for register classes.  If @var{char} is such a letter, the
        !          6643: value should be the register class corresponding to it.  Otherwise,
        !          6644: the value should be @code{NO_REGS}.
        !          6645: 
        !          6646: @item REGNO_OK_FOR_BASE_P (@var{num})
        !          6647: A C expression which is nonzero if register number @var{num} is
        !          6648: suitable for use as a base register in operand addresses.  It may be
        !          6649: either a suitable hard register or a pseudo register that has been
        !          6650: allocated such a hard register.
        !          6651: 
        !          6652: @item REGNO_OK_FOR_INDEX_P (@var{num})
        !          6653: A C expression which is nonzero if register number @var{num} is
        !          6654: suitable for use as an index register in operand addresses.  It may be
        !          6655: either a suitable hard register or a pseudo register that has been
        !          6656: allocated such a hard register.
        !          6657: 
        !          6658: The difference between an index register and a base register is that
        !          6659: the index register may be scaled.  If an address involves the sum of
        !          6660: two registers, neither one of them scaled, then either one may be
        !          6661: labeled the ``base'' and the other the ``index''; but whichever
        !          6662: labeling is used must fit the machine's constraints of which registers
        !          6663: may serve in each capacity.  The compiler will try both labelings,
        !          6664: looking for one that is valid, and will reload one or both registers
        !          6665: only if neither labeling works.
        !          6666: 
        !          6667: @item PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
        !          6668: A C expression that places additional restrictions on the register class
        !          6669: to use when it is necessary to copy value @var{x} into a register in class
        !          6670: @var{class}.  The value is a register class; perhaps @var{class}, or perhaps
        !          6671: another, smaller class.  On many machines, the definition
        !          6672: 
        !          6673: @example
        !          6674: #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
        !          6675: @end example
        !          6676: 
        !          6677: @noindent
        !          6678: is safe.
        !          6679: 
        !          6680: Sometimes returning a more restrictive class makes better code.  For
        !          6681: example, on the 68000, when @var{x} is an integer constant that is in range
        !          6682: for a @samp{moveq} instruction, the value of this macro is always
        !          6683: @code{DATA_REGS} as long as @var{class} includes the data registers.
        !          6684: Requiring a data register guarantees that a @samp{moveq} will be used.
        !          6685: 
        !          6686: If @var{x} is a @samp{const_double}, by returning @code{NO_REGS}
        !          6687: you can force @var{x} into a memory constant.  This is useful on
        !          6688: certain machines where immediate floating values cannot be loaded into
        !          6689: certain kinds of registers.
        !          6690: 
        !          6691: In a shift instruction or a bitwise-and instruction, the mode of @var{x},
        !          6692: the value being reloaded, may not be the same as the mode of the
        !          6693: instruction's operand.  (They will both be fixed-point modes, however.)  In
        !          6694: such a case, @var{class} may not be a safe value to return.  @var{class} is
        !          6695: certainly valid for the instruction, but it may not be valid for reloading
        !          6696: @var{x}.  This problem can occur on machines such as the 68000 and 80386
        !          6697: where some registers can handle full-word values but cannot handle
        !          6698: single-byte values.
        !          6699: 
        !          6700: On such machines, this macro must examine the mode of @var{x} and return a
        !          6701: subclass of @var{class} which can handle loads and stores of that mode.  On
        !          6702: the 68000, where address registers cannot handle @code{QImode}, if @var{x}
        !          6703: has @code{QImode} then you must return @code{DATA_REGS}.  If @var{class} is
        !          6704: @code{ADDR_REGS}, then there is no correct value to return; but the shift
        !          6705: and bitwise-and instructions don't use @code{ADDR_REGS}, so this fatal case
        !          6706: never arises.
        !          6707: 
        !          6708: @item CLASS_MAX_NREGS (@var{class}, @var{mode})
        !          6709: A C expression for the maximum number of consecutive registers
        !          6710: of class @var{class} needed to hold a value of mode @var{mode}.
        !          6711: 
        !          6712: This is closely related to the macro @code{HARD_REGNO_NREGS}.
        !          6713: In fact, the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
        !          6714: should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, @var{mode})}
        !          6715: for all @var{regno} values in the class @var{class}.
        !          6716: 
        !          6717: This macro helps control the handling of multiple-word values
        !          6718: in the reload pass.
        !          6719: @end table
        !          6720: 
        !          6721: Two other special macros describe which constants fit which constraint
        !          6722: letters.
        !          6723: 
        !          6724: @table @code
        !          6725: @item CONST_OK_FOR_LETTER_P (@var{value}, @var{c})
        !          6726: A C expression that defines the machine-dependent operand constraint letters
        !          6727: that specify particular ranges of integer values.  If @var{c} is one
        !          6728: of those letters, the expression should check that @var{value}, an integer,
        !          6729: is in the appropriate range and return 1 if so, 0 otherwise.  If @var{c} is
        !          6730: not one of those letters, the value should be 0 regardless of @var{value}.
        !          6731: 
        !          6732: @item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c})
        !          6733: A C expression that defines the machine-dependent operand constraint
        !          6734: letters that specify particular ranges of floating values.  If @var{c} is
        !          6735: one of those letters, the expression should check that @var{value}, an RTX
        !          6736: of code @samp{const_double}, is in the appropriate range and return 1 if
        !          6737: so, 0 otherwise.  If @var{c} is not one of those letters, the value should
        !          6738: be 0 regardless of @var{value}.
        !          6739: @end table
        !          6740: 
        !          6741: @node Stack Layout, Library Names, Register Classes, Machine Macros
        !          6742: @section Describing Stack Layout
        !          6743: 
        !          6744: @table @code
        !          6745: @item STACK_GROWS_DOWNWARD
        !          6746: Define this macro if pushing a word onto the stack moves the stack
        !          6747: pointer to a smaller address.
        !          6748: 
        !          6749: When we say, ``define this macro if @dots{},'' it means that the
        !          6750: compiler checks this macro only with @code{#ifdef} so the precise
        !          6751: definition used does not matter.
        !          6752: 
        !          6753: @item FRAME_GROWS_DOWNWARD
        !          6754: Define this macro if the addresses of local variable slots are at negative
        !          6755: offsets from the frame pointer.
        !          6756: 
        !          6757: @item STARTING_FRAME_OFFSET
        !          6758: Offset from the frame pointer to the first local variable slot to be allocated.
        !          6759: 
        !          6760: If @code{FRAME_GROWS_DOWNWARD}, the next slot's offset is found by
        !          6761: subtracting the length of the first slot from @code{STARTING_FRAME_OFFSET}.
        !          6762: Otherwise, it is found by adding the length of the first slot to
        !          6763: the value @code{STARTING_FRAME_OFFSET}.
        !          6764: 
        !          6765: @item PUSH_ROUNDING (@var{npushed})
        !          6766: A C expression that is the number of bytes actually pushed onto the
        !          6767: stack when an instruction attempts to push @var{npushed} bytes.
        !          6768: 
        !          6769: If the target machine does not have a push instruction, do not define
        !          6770: this macro.  That directs GNU CC to use an alternate strategy: to
        !          6771: allocate the entire argument block and then store the arguments into
        !          6772: it.
        !          6773: 
        !          6774: On some machines, the definition
        !          6775: 
        !          6776: @example
        !          6777: #define PUSH_ROUNDING(BYTES) (BYTES)
        !          6778: @end example
        !          6779: 
        !          6780: @noindent
        !          6781: will suffice.  But on other machines, instructions that appear
        !          6782: to push one byte actually push two bytes in an attempt to maintain
        !          6783: alignment.  Then the definition should be
        !          6784: 
        !          6785: @example
        !          6786: #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
        !          6787: @end example
        !          6788: 
        !          6789: @item FIRST_PARM_OFFSET (@var{fundecl})
        !          6790: Offset from the argument pointer register to the first argument's
        !          6791: address.  On some machines it may depend on the data type of the
        !          6792: function.  (In the next version of GNU CC, the argument will be
        !          6793: changed to the function data type rather than its declaration.)
        !          6794: 
        !          6795: @item FIRST_PARM_CALLER_OFFSET (@var{fundecl})
        !          6796: Define this macro on machines where register parameters have shadow
        !          6797: locations on the stack, at addresses below the nominal parameter.
        !          6798: This matters because certain arguments cannot be passed on the stack.
        !          6799: On these machines, such arguments must be stored into the shadow
        !          6800: locations.
        !          6801: 
        !          6802: This macro should expand into a C expression whose value is the offset
        !          6803: of the first parameter's shadow location from the nominal stack
        !          6804: pointer value.  (That value is itself computed by adding the value of
        !          6805: @code{STACK_POINTER_OFFSET} to the stack pointer register.)
        !          6806: 
        !          6807: @item RETURN_POPS_ARGS (@var{funtype})
        !          6808: A C expression that should be 1 if a function pops its own arguments
        !          6809: on returning, or 0 if the function pops no arguments and the caller
        !          6810: must therefore pop them all after the function returns.
        !          6811: 
        !          6812: @var{funtype} is a C variable whose value is a tree node that
        !          6813: describes the function in question.  Normally it is a node of type
        !          6814: @code{FUNCTION_TYPE} that describes the data type of the function.
        !          6815: From this it is possible to obtain the data types of the value and
        !          6816: arguments (if known).
        !          6817: 
        !          6818: When a call to a library function is being considered, @var{funtype}
        !          6819: will contain an identifier node for the library function.  Thus, if
        !          6820: you need to distinguish among various library functions, you can do so
        !          6821: by their names.  Note that ``library function'' in this context means
        !          6822: a function used to perform arithmetic, whose name is known specially
        !          6823: in the compiler and was not mentioned in the C code being compiled.
        !          6824: 
        !          6825: On the Vax, all functions always pop their arguments, so the
        !          6826: definition of this macro is 1.  On the 68000, using the standard
        !          6827: calling convention, no functions pop their arguments, so the value of
        !          6828: the macro is always 0 in this case.  But an alternative calling
        !          6829: convention is available in which functions that take a fixed number of
        !          6830: arguments pop them but other functions (such as @code{printf}) pop
        !          6831: nothing (the caller pops all).  When this convention is in use,
        !          6832: @var{funtype} is examined to determine whether a function takes a
        !          6833: fixed number of arguments.
        !          6834: 
        !          6835: @item FUNCTION_VALUE (@var{valtype}, @var{func})
        !          6836: A C expression to create an RTX representing the place where a
        !          6837: function returns a value of data type @var{valtype}.  @var{valtype} is
        !          6838: a tree node representing a data type.  Write @code{TYPE_MODE
        !          6839: (@var{valtype})} to get the machine mode used to represent that type.
        !          6840: On many machines, only the mode is relevant.  (Actually, on most
        !          6841: machines, scalar values are returned in the same place regardless of
        !          6842: mode).@refill
        !          6843: 
        !          6844: If the precise function being called is known, @var{func} is a tree
        !          6845: node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
        !          6846: pointer.  This makes it possible to use a different value-returning
        !          6847: convention for specific functions when all their calls are
        !          6848: known.@refill
        !          6849: 
        !          6850: @item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func})
        !          6851: Define this macro if the target machine has ``register windows''
        !          6852: so that the register in which a function returns its value is not
        !          6853: the same as the one in which the caller sees the value.
        !          6854: 
        !          6855: For such machines, @code{FUNCTION_VALUE} computes the register in
        !          6856: which the caller will see the value, and
        !          6857: @code{FUNCTION_OUTGOING_VALUE} should be defined in a similar fashion
        !          6858: to tell the function where to put the value.@refill
        !          6859: 
        !          6860: If @code{FUNCTION_OUTGOING_VALUE} is not defined,
        !          6861: @code{FUNCTION_VALUE} serves both purposes.@refill
        !          6862: 
        !          6863: @item LIBCALL_VALUE (@var{mode})
        !          6864: A C expression to create an RTX representing the place where a library
        !          6865: function returns a value of mode @var{mode}.  If the precise function
        !          6866: being called is known, @var{func} is a tree node
        !          6867: (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
        !          6868: pointer.  This makes it possible to use a different value-returning
        !          6869: convention for specific functions when all their calls are
        !          6870: known.@refill
        !          6871: 
        !          6872: Note that ``library function'' in this context means a compiler
        !          6873: support routine, used to perform arithmetic, whose name is known
        !          6874: specially by the compiler and was not mentioned in the C code being
        !          6875: compiled.
        !          6876: 
        !          6877: @item FUNCTION_VALUE_REGNO_P (@var{regno})
        !          6878: A C expression that is nonzero if @var{regno} is the number of a hard
        !          6879: register in which the values of called function may come back.
        !          6880: 
        !          6881: A register whose use for returning values is limited to serving as the
        !          6882: second of a pair (for a value of type @code{double}, say) need not be
        !          6883: recognized by this macro.  So for most machines, this definition
        !          6884: suffices:
        !          6885: 
        !          6886: @example
        !          6887: #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
        !          6888: @end example
        !          6889: 
        !          6890: If the machine has register windows, so that the caller and the called
        !          6891: function use different registers for the return value, this macro
        !          6892: should recognize only the caller's register numbers.
        !          6893: 
        !          6894: @item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
        !          6895: A C expression that controls whether a function argument is passed
        !          6896: in a register, and which register.
        !          6897: 
        !          6898: The arguments are @var{cum}, which summarizes all the previous
        !          6899: arguments; @var{mode}, the machine mode of the argument; @var{type},
        !          6900: the data type of the argument as a tree node or 0 if that is not known
        !          6901: (which happens for C support library functions); and @var{named},
        !          6902: which is 1 for an ordinary argument and 0 for nameless arguments that
        !          6903: correspond to @samp{...} in the called function's prototype.
        !          6904: 
        !          6905: The value of the expression should either be a @samp{reg} RTX for the
        !          6906: hard register in which to pass the argument, or zero to pass the
        !          6907: argument on the stack.
        !          6908: 
        !          6909: For the Vax and 68000, where normally all arguments are pushed, zero
        !          6910: suffices as a definition.
        !          6911: 
        !          6912: @item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
        !          6913: Define this macro if the target machine has ``register windows'', so
        !          6914: that the register in which a function sees an arguments is not
        !          6915: necessarily the same as the one in which the caller passed the
        !          6916: argument.
        !          6917: 
        !          6918: For such machines, @code{FUNCTION_ARG} computes the register in which
        !          6919: the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should
        !          6920: be defined in a similar fashion to tell the function being called
        !          6921: where the arguments will arrive.
        !          6922: 
        !          6923: If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG}
        !          6924: serves both purposes.@refill
        !          6925: 
        !          6926: @item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named})
        !          6927: A C expression for the number of words, at the beginning of an
        !          6928: argument, must be put in registers.  The value must be zero for
        !          6929: arguments that are passed entirely in registers or that are entirely
        !          6930: pushed on the stack.
        !          6931: 
        !          6932: On some machines, certain arguments must be passed partially in
        !          6933: registers and partially in memory.  On these machines, typically the
        !          6934: first @var{n} words of arguments are passed in registers, and the rest
        !          6935: on the stack.  If a multi-word argument (a @code{double} or a
        !          6936: structure) crosses that boundary, its first few words must be passed
        !          6937: in registers and the rest must be pushed.  This macro tells the
        !          6938: compiler when this occurs, and how many of the words should go in
        !          6939: registers.
        !          6940: 
        !          6941: @code{FUNCTION_ARG} for these arguments should return the first
        !          6942: register to be used by the caller for this argument; likewise
        !          6943: @code{FUNCTION_INCOMING_ARG}, for the called function.
        !          6944: 
        !          6945: @item CUMULATIVE_ARGS
        !          6946: A C type for declaring a variable that is used as the first argument
        !          6947: of @code{FUNCTION_ARG} and other related values.  For some target
        !          6948: machines, the type @code{int} suffices and can hold the number of
        !          6949: bytes of argument so far.
        !          6950: 
        !          6951: @item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype})
        !          6952: A C statement (sans semicolon) for initializing the variable @var{cum}
        !          6953: for the state at the beginning of the argument list.  The variable has
        !          6954: type @code{CUMULATIVE_ARGS}.  The value of @var{fntype} is the tree node
        !          6955: for the data type of the function which will receive the args, or 0
        !          6956: if the args are to a compiler support library function.
        !          6957: 
        !          6958: @item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named})
        !          6959: Update the summarizer variable @var{cum} to advance past an argument
        !          6960: in the argument list.  The values @var{mode}, @var{type} and
        !          6961: @var{named} describe that argument.  Once this is done, the variable
        !          6962: @var{cum} is suitable for analyzing the @emph{following} argument
        !          6963: with @code{FUNCTION_ARG}, etc.@refill
        !          6964: 
        !          6965: @item FUNCTION_ARG_REGNO_P (@var{regno})
        !          6966: A C expression that is nonzero if @var{regno} is the number of a hard
        !          6967: register in which function arguments are sometimes passed.  This does
        !          6968: @emph{not} include implicit arguments such as the static chain and
        !          6969: the structure-value address.  On many machines, no registers can be
        !          6970: used for this purpose since all function arguments are pushed on the
        !          6971: stack.
        !          6972: 
        !          6973: @item FUNCTION_ARG_PADDING (@var{mode}, @var{size})
        !          6974: If defined, a C expression which determines whether, and in which direction,
        !          6975: to pad out an argument with extra space.  The value should be of type
        !          6976: @code{enum direction}: either @code{upward} to pad above the argument,
        !          6977: @code{downward} to pad below, or @code{none} to inhibit padding.
        !          6978: 
        !          6979: The argument @var{size} is an RTX which describes the size of the
        !          6980: argument, in bytes.  It should be used only if @var{mode} is
        !          6981: @code{BLKmode}.  Otherwise, @var{size} is 0.
        !          6982: 
        !          6983: This macro does not control the @emph{amount} of padding; that is
        !          6984: always just enough to reach the next multiple of @code{PARM_BOUNDARY}.
        !          6985: 
        !          6986: This macro has a default definition which is right for most systems.
        !          6987: For little-endian machines, the default is to pad upward.  For
        !          6988: big-endian machines, the default is to pad downward for an argument of
        !          6989: constant size shorter than an @code{int}, and upward otherwise.
        !          6990: 
        !          6991: @item FUNCTION_PROLOGUE (@var{file}, @var{size})
        !          6992: A C compound statement that outputs the assembler code for entry to a
        !          6993: function.  The prologue is responsible for setting up the stack frame,
        !          6994: initializing the frame pointer register, saving registers that must be
        !          6995: saved, and allocating @var{size} additional bytes of storage for the
        !          6996: local variables.  @var{size} is an integer.  @var{file} is a stdio
        !          6997: stream to which the assembler code should be output.
        !          6998: 
        !          6999: The label for the beginning of the function need not be output by this
        !          7000: macro.  That has already been done when the macro is run.
        !          7001: 
        !          7002: To determine which registers to save, the macro can refer to the array
        !          7003: @code{regs_ever_live}: element @var{r} is nonzero if hard register
        !          7004: @var{r} is used anywhere within the function.  This implies the
        !          7005: function prologue should save register @var{r}, but not if it is one
        !          7006: of the call-used registers.
        !          7007: 
        !          7008: On machines where functions may or may not have frame-pointers, the
        !          7009: function entry code must vary accordingly; it must set up the frame
        !          7010: pointer if one is wanted, and not otherwise.  To determine whether a
        !          7011: frame pointer is in wanted, the macro can refer to the variable
        !          7012: @code{frame_pointer_needed}.  The variable's value will be 1 at run
        !          7013: time in a function that needs a frame pointer.
        !          7014: 
        !          7015: @item FUNCTION_PROFILER (@var{file}, @var{labelno})
        !          7016: A C statement or compound statement to output to @var{file} some
        !          7017: assembler code to call the profiling subroutine @code{mcount}.
        !          7018: Before calling, the assembler code must load the address of a
        !          7019: counter variable into a register where @code{mcount} expects to
        !          7020: find the address.  The name of this variable is @samp{LP} followed
        !          7021: by the number @var{labelno}, so you would generate the name using
        !          7022: @samp{LP%d} in a @code{fprintf}.
        !          7023: 
        !          7024: The details of how the address should be passed to @code{mcount} are
        !          7025: determined by your operating system environment, not by GNU CC.  To
        !          7026: figure them out, compile a small program for profiling using the
        !          7027: system's installed C compiler and look at the assembler code that
        !          7028: results.
        !          7029: 
        !          7030: @item EXIT_IGNORES_STACK
        !          7031: Define this macro as a C expression that is nonzero if the return
        !          7032: instruction or the function epilogue ignores the value of the stack
        !          7033: pointer; in other words, if it is safe to delete an instruction to
        !          7034: adjust the stack pointer before a return from the function.
        !          7035: 
        !          7036: Note that this macro's value is relevant only for for which frame
        !          7037: pointers are maintained.  It is never possible to delete a final stack
        !          7038: adjustment in a function that has no frame pointer, and the compiler
        !          7039: knows this regardless of @code{EXIT_IGNORES_STACK}.
        !          7040: 
        !          7041: @item FUNCTION_EPILOGUE (@var{file}, @var{size})
        !          7042: A C compound statement that outputs the assembler code for exit from a
        !          7043: function.  The epilogue is responsible for restoring the saved
        !          7044: registers and stack pointer to their values when the function was
        !          7045: called, and returning control to the caller.  This macro takes the
        !          7046: same arguments as the macro @code{FUNCTION_PROLOGUE}, and the
        !          7047: registers to restore are determined from @code{regs_ever_live} and
        !          7048: @code{CALL_USED_REGISTERS} in the same way.
        !          7049: 
        !          7050: On some machines, there is a single instruction that does all the work
        !          7051: of returning from the function.  On these machines, give that
        !          7052: instruction the name @samp{return} and do not define the macro
        !          7053: @code{FUNCTION_EPILOGUE} at all.
        !          7054: 
        !          7055: Do not define a pattern named @samp{return} if you want the
        !          7056: @code{FUNCTION_EPILOGUE} to be used.  If you want the target switches
        !          7057: to control whether return instructions or epilogues are used, define a
        !          7058: @samp{return} pattern with a validity condition that tests the target
        !          7059: switches appropriately.  If the @samp{return} pattern's validity
        !          7060: condition is false, epilogues will be used.
        !          7061: 
        !          7062: On machines where functions may or may not have frame-pointers, the
        !          7063: function exit code must vary accordingly.  Sometimes the code for
        !          7064: these two cases is completely different.  To determine whether a frame
        !          7065: pointer is in wanted, the macro can refer to the variable
        !          7066: @code{frame_pointer_needed}.  The variable's value will be 1 at run
        !          7067: time in a function that needs a frame pointer.
        !          7068: 
        !          7069: On some machines, some functions pop their arguments on exit while
        !          7070: others leave that for the caller to do.  For example, the 68020 when
        !          7071: given @samp{-mrtd} pops arguments in functions that take a fixed
        !          7072: number of arguments.
        !          7073: 
        !          7074: Your definition of the macro @code{RETURN_POPS_ARGS} decides which
        !          7075: functions pop their own arguments.  @code{FUNCTION_EPILOGUE} needs to
        !          7076: know what was decided.  The variable @code{current_function_pops_args}
        !          7077: is nonzero if the function should pop its own arguments.  If so, use
        !          7078: the variable @code{current_function_args_size} as the number of bytes
        !          7079: to pop.
        !          7080: 
        !          7081: @item FIX_FRAME_POINTER_ADDRESS (@var{addr}, @var{depth})
        !          7082: A C compound statement to alter a memory address that uses the frame
        !          7083: pointer register so that it uses the stack pointer register instead.
        !          7084: This must be done in the instructions that load parameter values into
        !          7085: registers, when the reload pass determines that a frame pointer is not
        !          7086: necessary for the function.  @var{addr} will be a C variable name, and
        !          7087: the updated address should be stored in that variable.  @var{depth}
        !          7088: will be the current depth of stack temporaries (number of bytes of
        !          7089: arguments currently pushed).  The change in offset between a
        !          7090: frame-pointer-relative address and a stack-pointer-relative address
        !          7091: must include @var{depth}.
        !          7092: 
        !          7093: Even if your machine description specifies there will always be a
        !          7094: frame pointer in the frame pointer register, you must still define
        !          7095: @code{FIX_FRAME_POINTER_ADDRESS}, but the definition will never be
        !          7096: executed at run time, so it may be empty.
        !          7097: @end table
        !          7098: 
        !          7099: @node Library Names, Addressing Modes, Stack Layout, Machine Macros
        !          7100: @section Library Subroutine Names
        !          7101: 
        !          7102: @table @code
        !          7103: @item UDIVSI3_LIBCALL
        !          7104: A C string constant giving the name of the function to call for
        !          7105: division of a full-word by a full-word.  If you do not define this
        !          7106: macro, the default name is used, which is @code{_udivsi3}, a function
        !          7107: defined in @file{gnulib}.
        !          7108: 
        !          7109: @item UMODSI3_LIBCALL
        !          7110: A C string constant giving the name of the function to call for the
        !          7111: remainder in division of a full-word by a full-word.  If you do not
        !          7112: define this macro, the default name is used, which is @code{_umodsi3},
        !          7113: a function defined in @file{gnulib}.
        !          7114: 
        !          7115: @item TARGET_MEM_FUNCTIONS
        !          7116: Define this macro if GNU CC should generate calls to the System V
        !          7117: (and ANSI C) library functions @code{memcpy} and @code{memset}
        !          7118: rather than the BSD functions @code{bcopy} and @code{bzero}.
        !          7119: @end table
        !          7120: 
        !          7121: @node Addressing Modes, Misc, Library Names, Machine Macros
        !          7122: @section Addressing Modes
        !          7123: 
        !          7124: @table @code
        !          7125: @item HAVE_POST_INCREMENT
        !          7126: Define this macro if the machine supports post-increment addressing.
        !          7127: 
        !          7128: @item HAVE_PRE_INCREMENT
        !          7129: @itemx HAVE_POST_DECREMENT
        !          7130: @itemx HAVE_PRE_DECREMENT
        !          7131: Similar for other kinds of addressing.
        !          7132: 
        !          7133: @item CONSTANT_ADDRESS_P (@var{x})
        !          7134: A C expression that is 1 if the RTX @var{x} is a constant whose value
        !          7135: is an integer.  This includes integers whose values are not explicitly
        !          7136: known, such as @samp{symbol_ref} and @samp{label_ref} expressions and
        !          7137: @samp{const} arithmetic expressions.
        !          7138: 
        !          7139: On most machines, this can be defined as @code{CONSTANT_P (@var{x})},
        !          7140: but a few machines are more restrictive in which constant addresses
        !          7141: are supported.
        !          7142: 
        !          7143: @item MAX_REGS_PER_ADDRESS
        !          7144: A number, the maximum number of registers that can appear in a valid
        !          7145: memory address.
        !          7146: 
        !          7147: @item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label})
        !          7148: A C compound statement with a conditional @code{goto @var{label};}
        !          7149: executed if @var{x} (an RTX) is a legitimate memory address on the
        !          7150: target machine for a memory operand of mode @var{mode}.
        !          7151: 
        !          7152: It usually pays to define several simpler macros to serve as
        !          7153: subroutines for this one.  Otherwise it may be too complicated to
        !          7154: understand.
        !          7155: 
        !          7156: This macro must exist in two variants: a strict variant and a
        !          7157: non-strict one.  The strict variant is used in the reload pass.  It
        !          7158: must be defined so that any pseudo-register that has not been
        !          7159: allocated a hard register is considered a memory reference.  In
        !          7160: contexts where some kind of register is required, a pseudo-register
        !          7161: with no hard register must be rejected.
        !          7162: 
        !          7163: The non-strict variant is used in other passes.  It must be defined to
        !          7164: accept all pseudo-registers in every context where some kind of
        !          7165: register is required.
        !          7166: 
        !          7167: Compiler source files that want to use the strict variant of this
        !          7168: macro define the macro @code{REG_OK_STRICT}.  You should use an
        !          7169: @code{#ifdef REG_OK_STRICT} conditional to define the strict variant
        !          7170: in that case and the non-strict variant otherwise.
        !          7171: 
        !          7172: Typically among the subroutines used to define
        !          7173: @code{GO_IF_LEGITIMATE_ADDRESS} are subroutines to check for
        !          7174: acceptable registers for various purposes (one for base registers, one
        !          7175: for index registers, and so on).  Then only these subroutine macros
        !          7176: need have two variants; the higher levels of macros may be the same
        !          7177: whether strict or not.@refill
        !          7178: 
        !          7179: @item REG_OK_FOR_BASE_P (@var{x})
        !          7180: A C expression that is nonzero if @var{x} (asumed to be a @code{reg}
        !          7181: RTX) is valid for use as a base register.  For hard registers, it
        !          7182: should always accept those which the hardware permits and reject the
        !          7183: others.  Whether the macro accepts or rejects pseudo registers must be
        !          7184: controlled by @code{REG_OK_STRICT} as described above.  This usually
        !          7185: requires two variant definitions, of which @code{REG_OK_STRICT}
        !          7186: controls the one actually used.
        !          7187: 
        !          7188: @item REG_OK_FOR_INDEX_P (@var{x})
        !          7189: A C expression that is nonzero if @var{x} (asumed to be a @code{reg}
        !          7190: RTX) is valid for use as an index register.
        !          7191: 
        !          7192: The difference between an index register and a base register is that
        !          7193: the index register may be scaled.  If an address involves the sum of
        !          7194: two registers, neither one of them scaled, then either one may be
        !          7195: labeled the ``base'' and the other the ``index''; but whichever
        !          7196: labeling is used must fit the machine's constraints of which registers
        !          7197: may serve in each capacity.  The compiler will try both labelings,
        !          7198: looking for one that is valid, and will reload one or both registers
        !          7199: only if neither labeling works.
        !          7200: 
        !          7201: @item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win})
        !          7202: A C compound statement that attempts to replace @var{x} with a valid
        !          7203: memory address for an operand of mode @var{mode}.  @var{win} will be a
        !          7204: C statement label elsewhere in the code; the macro definition may use
        !          7205: 
        !          7206: @example
        !          7207: GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win});
        !          7208: @end example
        !          7209: 
        !          7210: @noindent
        !          7211: to avoid further processing if the address has become legitimate.
        !          7212: 
        !          7213: @var{x} will always be the result of a call to @code{break_out_memory_refs},
        !          7214: and @var{oldx} will be the operand that was given to that function to produce
        !          7215: @var{x}.
        !          7216: 
        !          7217: The code generated by this macro should not alter the substructure of
        !          7218: @var{x}.  If it transforms @var{x} into a more legitimate form, it
        !          7219: should assign @var{x} (which will always be a C variable) a new value.
        !          7220: 
        !          7221: It is not necessary for this macro to come up with a legitimate
        !          7222: address.  The compiler has standard ways of doing so in all cases.  In
        !          7223: fact, it is safe for this macro to do nothing.  But often a
        !          7224: machine-dependent strategy can generate better code.
        !          7225: 
        !          7226: @item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label})
        !          7227: A C statement or compound statement with a conditional @code{goto
        !          7228: @var{label};} executed if memory address @var{x} (an RTX) can have
        !          7229: different meanings depending on the machine mode of the memory
        !          7230: reference it is used for.
        !          7231: 
        !          7232: Autoincrement and autodecrement addresses typically have mode-dependent
        !          7233: effects because the amount of the increment or decrement is the size
        !          7234: of the operand being addressed.  Some machines have other mode-dependent
        !          7235: addresses.  Many RISC machines have no mode-dependent addresses.
        !          7236: 
        !          7237: You may assume that @var{addr} is a valid address for the machine.
        !          7238: 
        !          7239: @item LEGITIMATE_CONSTANT_P (@var{x})
        !          7240: A C expression that is nonzero if @var{x} is a legitimate constant for
        !          7241: an immediate operand on the target machine.  You can assume that
        !          7242: either @var{x} is a @samp{const_double} or it satisfies
        !          7243: @code{CONSTANT_P}, so you need not check these things.  In fact,
        !          7244: @samp{1} is a suitable definition for this macro on machines where any
        !          7245: @samp{const_double} is valid and anything @code{CONSTANT_P} is valid.@refill
        !          7246: @end table
        !          7247: 
        !          7248: @node Misc, Condition Code, Addressing Modes, Machine Macros
        !          7249: @section Miscellaneous Parameters
        !          7250: 
        !          7251: @table @code
        !          7252: @item CASE_VECTOR_MODE
        !          7253: An alias for a machine mode name.  This is the machine mode that
        !          7254: elements of a jump-table should have.
        !          7255: 
        !          7256: @item CASE_VECTOR_PC_RELATIVE
        !          7257: Define this macro if jump-tables should contain relative addresses.
        !          7258: 
        !          7259: @item CASE_DROPS_THROUGH
        !          7260: Define this if control falls through a @code{case} insn when the index
        !          7261: value is out of range.  This means the specified default-label is
        !          7262: actually ignored by the @code{case} insn proper.
        !          7263: 
        !          7264: @item IMPLICIT_FIX_EXPR
        !          7265: An alias for a tree code that should be used by default for conversion
        !          7266: of floating point values to fixed point.  Normally,
        !          7267: @code{FIX_ROUND_EXPR} is used.@refill
        !          7268: 
        !          7269: @item FIXUNS_TRUNC_LIKE_FIX_TRUNC
        !          7270: Define this macro if the same instructions that convert a floating
        !          7271: point number to a signed fixed point number also convert validly to an
        !          7272: unsigned one.
        !          7273: 
        !          7274: @item EASY_DIV_EXPR
        !          7275: An alias for a tree code that is the easiest kind of division to
        !          7276: compile code for in the general case.  It may be
        !          7277: @code{TRUNC_DIV_EXPR}, @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or
        !          7278: @code{ROUND_DIV_EXPR}.  These four division operators differ in how
        !          7279: they round the result to an integer.  @code{EASY_DIV_EXPR} is used
        !          7280: when it is permissible to use any of those kinds of division and the
        !          7281: choice should be made on the basis of efficiency.@refill
        !          7282: 
        !          7283: @item DEFAULT_SIGNED_CHAR
        !          7284: An expression whose value is 1 or 0, according to whether the type
        !          7285: @code{char} should be signed or unsigned by default.  The user can
        !          7286: always override this default with the options @samp{-fsigned-char}
        !          7287: and @samp{-funsigned-char}.
        !          7288: 
        !          7289: @item SCCS_DIRECTIVE
        !          7290: Define this if the preprocessor should ignore @code{#sccs} directives
        !          7291: and print no error message.
        !          7292: 
        !          7293: @item IDENT_DIRECTIVE
        !          7294: Define this if the preprocessor should ignore @code{#ident} directives
        !          7295: and print no error message.
        !          7296: 
        !          7297: @item MOVE_MAX
        !          7298: The maximum number of bytes that a single instruction can move quickly
        !          7299: from memory to memory.
        !          7300: 
        !          7301: @item INT_TYPE_SIZE
        !          7302: A C expression for the size in bits of the type @code{int} on the
        !          7303: target machine.
        !          7304: 
        !          7305: @item SLOW_BYTE_ACCESS
        !          7306: Define this macro as a C expression which is nonzero if accessing less
        !          7307: than a word of memory (i.e. a @code{char} or a @code{short}) is slow
        !          7308: (requires more than one instruction).
        !          7309: 
        !          7310: @item SLOW_ZERO_EXTEND
        !          7311: Define this macro if zero-extension (of a @code{char} or @code{short}
        !          7312: to an @code{int}) can be done faster if the destination is a register
        !          7313: that is known to be zero.
        !          7314: 
        !          7315: If you define this macro, you must have instruction patterns that
        !          7316: recognize RTL structures like this:
        !          7317: 
        !          7318: @example
        !          7319: (set (strict-low-part (subreg:QI (reg:SI @dots{}) 0)) @dots{})
        !          7320: @end example
        !          7321: 
        !          7322: @noindent
        !          7323: and likewise for @code{HImode}.
        !          7324: 
        !          7325: @item SHIFT_COUNT_TRUNCATED
        !          7326: Define this macro if shift instructions ignore all but the lowest few
        !          7327: bits of the shift count.  It implies that a sign-extend or zero-extend
        !          7328: instruction for the shift count can be omitted.
        !          7329: 
        !          7330: @item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec})
        !          7331: A C expression which is nonzero if on this machine it is safe to
        !          7332: ``convert'' an integer of @var{inprec} bits to one of @var{outprec}
        !          7333: bits (where @var{outprec} is smaller than @var{inprec}) by merely
        !          7334: operating on it as if it had only @var{outprec} bits.
        !          7335: 
        !          7336: On many machines, this expression can be 1.
        !          7337: 
        !          7338: @item NO_FUNCTION_CSE
        !          7339: Define this macro if it is as good or better to call a constant
        !          7340: function address than to call an address kept in a register.
        !          7341: 
        !          7342: @item PROMOTE_PROTOTYPES
        !          7343: Define this macro if an argument declared as @code{char} or
        !          7344: @code{short} in a prototype should actually be passed as an
        !          7345: @code{int}.  In addition to avoiding errors in certain cases of
        !          7346: mismatch, it also makes for better code on certain machines.
        !          7347: 
        !          7348: @item STORE_FLAG_VALUE
        !          7349: A C expression for the value stored by a store-flag instruction
        !          7350: (@code{s@var{cond}}) when the condition is true.  This is usually 1 or
        !          7351: -1; it is required to be an odd number.
        !          7352: 
        !          7353: Do not define @code{STORE_FLAG_VALUE} if the machine has no store-flag
        !          7354: instructions.
        !          7355: 
        !          7356: @item Pmode
        !          7357: An alias for the machine mode for pointers.  Normally the definition
        !          7358: can be
        !          7359: 
        !          7360: @example
        !          7361: #define Pmode SImode
        !          7362: @end example
        !          7363: 
        !          7364: @item FUNCTION_MODE
        !          7365: An alias for the machine mode used for memory references to functions
        !          7366: being called, in @samp{call} RTL expressions.  On most machines this
        !          7367: should be @code{QImode}.
        !          7368: 
        !          7369: @item INSN_MACHINE_INFO
        !          7370: This macro should expand into a C structure type to use for the
        !          7371: machine-dependent info field specified with the optional last argument
        !          7372: in @samp{define_insn} and @samp{define_peephole} patterns.  For example,
        !          7373: it might expand into @samp{struct machine_info}; then it would be up
        !          7374: to you to define this structure in the @file{tm.h} file.
        !          7375: 
        !          7376: You do not need to define this macro if you do not write the optional
        !          7377: last argument in any of the patterns in the machine description.
        !          7378: 
        !          7379: @item CONST_COSTS (@var{x}, @var{code})
        !          7380: A part of a C @code{switch} statement that describes the relative
        !          7381: costs of constant RTL expressions.  It must contain @code{case} labels
        !          7382: for expression codes @samp{const_int}, @samp{const}, @samp{symbol_ref}, @samp{label_ref}
        !          7383: and @samp{const_double}.  Each case must ultimately reach a
        !          7384: @code{return} statement to return the relative cost of the use of that
        !          7385: kind of constant value in an expression.  The cost may depend on the
        !          7386: precise value of the constant, which is available for examination in
        !          7387: @var{x}.
        !          7388: 
        !          7389: @var{code} is the expression code---redundant, since it can be
        !          7390: obtained with @code{GET_CODE (@var{x})}.
        !          7391: 
        !          7392: @item DOLLARS_IN_IDENTIFIERS
        !          7393: Define this to be nonzero if the character @samp{$} should be allowed
        !          7394: by default in identifier names.
        !          7395: @end table
        !          7396: 
        !          7397: @node Condition Code, Assembler Format, Misc, Machine Macros
        !          7398: @section Condition Code Information
        !          7399: 
        !          7400: The file @file{conditions.h} defines a variable @code{cc_status} to
        !          7401: describe how the condition code was computed (in case the interpretation of
        !          7402: the condition code depends on the instruction that it was set by).  This
        !          7403: variable contains the RTL expressions on which the condition code is
        !          7404: currently based, and several standard flags.
        !          7405: 
        !          7406: Sometimes additional machine-specific flags must be defined in the machine
        !          7407: description header file.  It can also add additional machine-specific
        !          7408: information by defining @code{CC_STATUS_MDEP}.
        !          7409: 
        !          7410: @table @code
        !          7411: @item CC_STATUS_MDEP
        !          7412: C code for a data type which is used for declaring the @code{mdep}
        !          7413: component of @code{cc_status}.  It defaults to @code{int}.
        !          7414: 
        !          7415: @item CC_STATUS_MDEP_INIT
        !          7416: A C expression for the initial value of the @code{mdep} field.  It
        !          7417: defaults to 0.
        !          7418: 
        !          7419: @item NOTICE_UPDATE_CC (@var{exp}, @var{insn})
        !          7420: A C compound statement to set the components of @code{cc_status}
        !          7421: appropriately for an insn @var{insn} whose body is @var{exp}.  It is
        !          7422: this macro's responsibility to recognize insns that set the condition
        !          7423: code as a byproduct of other activity as well as those that explicitly
        !          7424: set @code{(cc0)}.
        !          7425: 
        !          7426: If there are insn that do not set the condition code but do alter
        !          7427: other machine registers, this macro must check to see whether they
        !          7428: invalidate the expressions that the condition code is recorded as
        !          7429: reflecting.  For example, on the 68000, insns that store in address
        !          7430: registers do not set the condition code, which means that usually
        !          7431: @code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such
        !          7432: insns.  But suppose that the previous insn set the condition code
        !          7433: based on location @samp{a4@@(102)} and the current insn stores a new
        !          7434: value in @samp{a4}.  Although the condition code is not changed by
        !          7435: this, it will no longer be true that it reflects the contents of
        !          7436: @samp{a4@@(102)}.  Therefore, @code{NOTICE_UPDATE_CC} must alter
        !          7437: @code{cc_status} in this case to say that nothing is known about the
        !          7438: condition code value.
        !          7439: 
        !          7440: The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal
        !          7441: with the results of peephole optimization: insns whose patterns are
        !          7442: @samp{parallel} RTXs containing various @samp{reg}, @samp{mem} or
        !          7443: constants which are just the operands.  The RTL structure of these
        !          7444: insns is not sufficient to indicate what the insns actually do.  What
        !          7445: @code{NOTICE_UPDATE_CC} should do when it sees one is just to run
        !          7446: @code{CC_STATUS_INIT}.
        !          7447: @end table
        !          7448: 
        !          7449: @node Assembler Format,, Condition Code, Machine Macros
        !          7450: @section Output of Assembler Code
        !          7451: 
        !          7452: @table @code
        !          7453: @item ASM_SPEC
        !          7454: A C string constant that tells the GNU CC driver program options to
        !          7455: pass to the assembler.  It can also specify how to translate options
        !          7456: you give to GNU CC into options for GNU CC to pass to the assembler.
        !          7457: See the file @file{tm-sun3.h} for an example of this.
        !          7458: 
        !          7459: Do not define this macro if it does not need to do anything.
        !          7460: 
        !          7461: @item LINK_SPEC
        !          7462: A C string constant that tells the GNU CC driver program options to
        !          7463: pass to the linker.  It can also specify how to translate options you
        !          7464: give to GNU CC into options for GNU CC to pass to the linker.
        !          7465: 
        !          7466: Do not define this macro if it does not need to do anything.
        !          7467: 
        !          7468: @item LIB_SPEC
        !          7469: Another C string constant used much like @code{LINK_SPEC}.  The difference
        !          7470: between the two is that @code{LIBS_SPEC} is used at the end of the
        !          7471: command given to the linker.
        !          7472: 
        !          7473: If this macro is not defined, a default is provided that
        !          7474: loads the standard C library from the usual place.  See @file{gcc.c}.
        !          7475: 
        !          7476: @item STARTFILE_SPEC
        !          7477: Another C string constant used much like @code{LINK_SPEC}.  The
        !          7478: difference between the two is that @code{STARTFILE_SPEC} is used at
        !          7479: the very beginning of the command given to the linker.
        !          7480: 
        !          7481: If this macro is not defined, a default is provided that loads the
        !          7482: standard C startup file from the usual place.  See @file{gcc.c}.
        !          7483: 
        !          7484: @item ASM_FILE_START (@var{stream})
        !          7485: A C expression which outputs to the stdio stream @var{stream}
        !          7486: some appropriate text to go at the start of an assembler file.
        !          7487: 
        !          7488: Normally this macro is defined to output a line containing
        !          7489: @samp{#NO_APP}, which is a comment that has no effect on most
        !          7490: assemblers but tells the GNU assembler that it can save time by not
        !          7491: checking for certain assembler constructs.
        !          7492: 
        !          7493: On systems that use SDB, it is necessary to output certain commands;
        !          7494: see @file{tm-attasm.h}.
        !          7495: 
        !          7496: @item ASM_APP_ON
        !          7497: A C string constant for text to be output before each @code{asm}
        !          7498: statement or group of consecutive ones.  Normally this is
        !          7499: @code{"#APP"}, which is a comment that has no effect on most
        !          7500: assemblers but tells the GNU assembler that it must check the lines
        !          7501: that follow for all valid assembler constructs.
        !          7502: 
        !          7503: @item ASM_APP_OFF
        !          7504: A C string constant for text to be output after each @code{asm}
        !          7505: statement or group of consecutive ones.  Normally this is
        !          7506: @code{"#NO_APP"}, which tells the GNU assembler to resume making the
        !          7507: time-saving assumptions that are valid for ordinary compiler output.
        !          7508: 
        !          7509: @item TEXT_SECTION_ASM_OP
        !          7510: A C string constant for the assembler operation that should precede
        !          7511: instructions and read-only data.  Normally @code{".text"} is right.
        !          7512: 
        !          7513: @item DATA_SECTION_ASM_OP
        !          7514: A C string constant for the assembler operation to identify the
        !          7515: following data as writable initialized data.  Normally @code{".data"}
        !          7516: is right.
        !          7517: 
        !          7518: @item REGISTER_NAMES
        !          7519: A C initializer containing the assembler's names for the machine
        !          7520: registers, each one as a C string constant.  This is what translates
        !          7521: register numbers in the compiler into assembler language.
        !          7522: 
        !          7523: @item DBX_REGISTER_NUMBER (@var{regno})
        !          7524: A C expression that returns the DBX register number for the compiler
        !          7525: register number @var{regno}.  In simple cases, the value of this
        !          7526: expression may be @var{regno} itself.  But sometimes there are some
        !          7527: registers that the compiler knows about and DBX does not, or vice
        !          7528: versa.  In such cases, some register may need to have one number in
        !          7529: the compiler and another for DBX.
        !          7530: 
        !          7531: @item DBX_DEBUGGING_INFO
        !          7532: Define this macro if GNU CC should produce debugging output for DBX
        !          7533: in response to the @samp{-g} option.
        !          7534: 
        !          7535: @item SDB_DEBUGGING_INFO
        !          7536: Define this macro if GNU CC should produce debugging output for SDB
        !          7537: in response to the @samp{-g} option.
        !          7538: 
        !          7539: @item PUT_SDB_@var{op}
        !          7540: Define these macros to override the assembler syntax for the special
        !          7541: SDB assembler directives.  See @file{sdbout.c} for a list of these
        !          7542: macros and their arguments.  If the standard syntax is used, you need
        !          7543: not define them yourself.
        !          7544: 
        !          7545: @item SDB_GENERATE_FAKE
        !          7546: Define this macro to override the usual method of constructing a dummy
        !          7547: name for anonymous structure and union types.  See @file{sdbout.c} for
        !          7548: more infomation.
        !          7549: 
        !          7550: @item DBX_NO_XREFS
        !          7551: Define this macro if DBX on your system does not support the construct
        !          7552: @samp{xs@var{tagname}}.  On some systems, this construct is used to
        !          7553: describe a forward reference to a structure named @var{tagname}.
        !          7554: On other systems, this construct is not supported at all.
        !          7555: 
        !          7556: @item DBX_CONTIN_LENGTH
        !          7557: A symbol name in DBX-format debugging information is normally
        !          7558: continued (split into two separate @code{.stabs} directives) when it
        !          7559: exceeds a certain length (by default, 80 characters).  On some
        !          7560: operating systems, DBX requires this splitting; on others, splitting
        !          7561: must not be done.  You can inhibit splitting by defining this macro
        !          7562: with the value zero.  You can override the default splitting-length by
        !          7563: defining this macro as an expression for the length you desire.
        !          7564: 
        !          7565: @item DBX_CONTIN_CHAR
        !          7566: Normally continuation is indicated by adding a @samp{\} character to
        !          7567: the end of a @code{.stabs} string when a continuation follows.  To use
        !          7568: a different character instead, define this macro as a character
        !          7569: constant for the character you want to use.  Do not define this macro
        !          7570: if backslash is correct for your system.
        !          7571: 
        !          7572: @item ASM_OUTPUT_LABEL (@var{stream}, @var{name})
        !          7573: A C statement (sans semicolon) to output to the stdio stream
        !          7574: @var{stream} the assembler definition of a label named @var{name}.  Use
        !          7575: the expression @code{assemble_name (@var{stream}, @var{name})} to output
        !          7576: the name itself; before and after that, output the additional
        !          7577: assembler syntax for defining the name, and a newline.
        !          7578: 
        !          7579: @item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl})
        !          7580: A C statement (sans semicolon) to output to the stdio stream
        !          7581: @var{stream} any text necessary for declaring the name @var{name} of a
        !          7582: function which is being defined.  This macro is responsible for
        !          7583: outputting the label definition (perhaps using
        !          7584: @code{ASM_OUTPUT_LABEL}).  The argument @var{decl} is the
        !          7585: @code{FUNCTION_DECL} tree node representing the function.
        !          7586: 
        !          7587: If this macro is not defined, then the function name is defined in the
        !          7588: usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
        !          7589: 
        !          7590: @item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name})
        !          7591: A C statement (sans semicolon) to output to the stdio stream
        !          7592: @var{stream} some commands that will make the label @var{name} global;
        !          7593: that is, available for reference from other files.  Use the expression
        !          7594: @code{assemble_name (@var{stream}, @var{name})} to output the name
        !          7595: itself; before and after that, output the additional assembler syntax
        !          7596: for making that name global, and a newline.
        !          7597: 
        !          7598: @item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{name}, @var{decl})
        !          7599: A C statement (sans semicolon) to output to the stdio stream
        !          7600: @var{stream} any text necessary for declaring the name of an external
        !          7601: symbol named @var{name} which is referenced in this compilation but
        !          7602: not defined.  The value of @var{decl} is the tree node for the
        !          7603: declaration.
        !          7604: 
        !          7605: This macro need not be defined if it does not need to output anything.
        !          7606: The GNU assembler and most Unix assemblers don't require anything.
        !          7607: 
        !          7608: @item ASM_OUTPUT_LABELREF (@var{stream}, @var{name})
        !          7609: A C statement to output to the stdio stream @var{stream} a reference in
        !          7610: assembler syntax to a label named @var{name}.  The character @samp{_}
        !          7611: should be added to the front of the name, if that is customary on your
        !          7612: operating system, as it is in most Berkeley Unix systems.  This macro
        !          7613: is used in @code{assemble_name}.
        !          7614: 
        !          7615: @item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num})
        !          7616: A C statement to store into the string @var{string} a label whose
        !          7617: name is made from the string @var{prefix} and the number @var{num}.
        !          7618: 
        !          7619: This string, when output subsequently by @code{ASM_OUTPUT_LABELREF},
        !          7620: should produce the same output that @code{ASM_OUTPUT_INTERNAL_LABEL}
        !          7621: would produce with the same @var{prefix} and @var{num}.
        !          7622: 
        !          7623: @item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num})
        !          7624: A C statement to output to the stdio stream @var{stream} a label whose
        !          7625: name is made from the string @var{prefix} and the number @var{num}.
        !          7626: These labels are used for internal purposes, and there is no reason
        !          7627: for them to appear in the symbol table of the object file.  On many
        !          7628: systems, the letter @samp{L} at the beginning of a label has this
        !          7629: effect.  The usual definition of this macro is as follows:
        !          7630: 
        !          7631: @example
        !          7632: fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num})
        !          7633: @end example
        !          7634: 
        !          7635: @item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table})
        !          7636: Define this if the label before a jump-table needs to be output
        !          7637: specially.  The first three arguments are the same as for
        !          7638: @code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the
        !          7639: jump-table which follows (a @samp{jump_insn} containing an
        !          7640: @samp{addr_vec} or @samp{addr_diff_vec}).
        !          7641: 
        !          7642: This feature is used on system V to output a @code{swbeg} statement
        !          7643: for the table.
        !          7644: 
        !          7645: If this macro is not defined, these labels are output with
        !          7646: @code{ASM_OUTPUT_INTERNAL_LABEL}.
        !          7647: 
        !          7648: @item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table})
        !          7649: Define this if something special must be output at the end of a jump-table.
        !          7650: The definition should be a C statement to be executed after the assembler
        !          7651: code for the table is written.  It should write the appropriate code to
        !          7652: stdio stream @var{stream}.  The argument @var{table} is the jump-table
        !          7653: insn, and @var{num} is the label-number of the preceding label.
        !          7654: 
        !          7655: If this macro is not defined, nothing special is output at the end of
        !          7656: the jump-table.
        !          7657: 
        !          7658: @item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number})
        !          7659: A C expression to assign to @var{outvar} (which is a variable of type
        !          7660: @code{char *}) a newly allocated string made from the string
        !          7661: @var{name} and the number @var{number}, with some suitable punctuation
        !          7662: added.  Use @code{alloca} to get space for the string.
        !          7663: 
        !          7664: This string will be used as the argument to @code{ASM_OUTPUT_LABELREF}
        !          7665: to produce an assembler label for an internal static variable whose
        !          7666: name is @var{name}.  Therefore, the string must be such as to result
        !          7667: in valid assembler code.  The argument @var{number} is different each
        !          7668: time this macro is executed; it prevents conflicts between
        !          7669: similarly-named internal static variables in different scopes.
        !          7670: 
        !          7671: Ideally this string should not be a valid C identifier, to prevent any
        !          7672: conflict with the user's own symbols.  Most assemblers allow periods
        !          7673: or percent signs in assembler symbols; putting at least one of these
        !          7674: between the name and the number will suffice.
        !          7675: 
        !          7676: @item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno})
        !          7677: A C expression to output to @var{stream} some assembler code
        !          7678: which will push hard register number @var{regno} onto the stack.
        !          7679: The code need not be optimal, since this macro is used only when
        !          7680: profiling.
        !          7681: 
        !          7682: @item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno})
        !          7683: A C expression to output to @var{stream} some assembler code
        !          7684: which will pop hard register number @var{regno} off of the stack.
        !          7685: The code need not be optimal, since this macro is used only when
        !          7686: profiling.
        !          7687: 
        !          7688: @item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{value}, @var{rel})
        !          7689: This macro should be provided on machines where the addresses
        !          7690: in a dispatch table are relative to the table's own address.
        !          7691: 
        !          7692: The definition should be a C statement to output to the stdio stream
        !          7693: @var{stream} an assembler pseudo-instruction to generate a difference
        !          7694: between two labels.  @var{value} and @var{rel} are the numbers of two
        !          7695: internal labels.  The definitions of these labels are output using
        !          7696: @code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same
        !          7697: way here.  For example,
        !          7698: 
        !          7699: @example
        !          7700: fprintf (@var{stream}, "\t.word L%d-L%d\n",
        !          7701:          @var{value}, @var{rel})
        !          7702: @end example
        !          7703: 
        !          7704: @item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value})
        !          7705: This macro should be provided on machines where the addresses
        !          7706: in a dispatch table are absolute.
        !          7707: 
        !          7708: The definition should be a C statement to output to the stdio stream
        !          7709: @var{stream} an assembler pseudo-instruction to generate a reference to
        !          7710: a label.  @var{value} is the number of an internal label whose
        !          7711: definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}.
        !          7712: For example,
        !          7713: 
        !          7714: @example
        !          7715: fprintf (@var{stream}, "\t.word L%d\n", @var{value})
        !          7716: @end example
        !          7717: 
        !          7718: @item ASM_OUTPUT_DOUBLE (@var{stream}, @var{value})
        !          7719: A C statement to output to the stdio stream @var{stream} an assembler
        !          7720: instruction to assemble a @code{double} constant whose value is
        !          7721: @var{value}.  @var{value} will be a C expression of type
        !          7722: @code{double}.
        !          7723: 
        !          7724: @item ASM_OUTPUT_FLOAT (@var{stream}, @var{value})
        !          7725: A C statement to output to the stdio stream @var{stream} an assembler
        !          7726: instruction to assemble a @code{float} constant whose value is
        !          7727: @var{value}.  @var{value} will be a C expression of type @code{float}.
        !          7728: 
        !          7729: @item ASM_OUTPUT_INT (@var{stream}, @var{exp})
        !          7730: @itemx ASM_OUTPUT_SHORT (@var{stream}, @var{exp})
        !          7731: @itemx ASM_OUTPUT_CHAR (@var{stream}, @var{exp})
        !          7732: A C statement to output to the stdio stream @var{stream} an assembler
        !          7733: instruction to assemble a @code{int}, @code{short} or @code{char}
        !          7734: constant whose value is @var{value}.  The argument @var{exp} will be
        !          7735: an RTL expression which represents a constant value.  Use
        !          7736: @samp{output_addr_const (@var{exp})} to output this value as an
        !          7737: assembler expression.@refill
        !          7738: 
        !          7739: @item ASM_OUTPUT_BYTE (@var{stream}, @var{value})
        !          7740: A C statement to output to the stdio stream @var{stream} an assembler
        !          7741: instruction to assemble a single byte containing the number @var{value}.
        !          7742: 
        !          7743: @item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len})
        !          7744: A C statement to output to the stdio stream @var{stream} an assembler
        !          7745: instruction to assemble a string constant containing the @var{len}
        !          7746: bytes at @var{ptr}.  @var{ptr} will be a C expression of type
        !          7747: @code{char *} and @var{len} a C expression of type @code{int}.
        !          7748: 
        !          7749: If the assembler has a @code{.ascii} pseudo-op as found in the
        !          7750: Berkeley Unix assembler, do not define the macro
        !          7751: @code{ASM_OUTPUT_ASCII}.
        !          7752: 
        !          7753: @item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes})
        !          7754: A C statement to output to the stdio stream @var{stream} an assembler
        !          7755: instruction to advance the location counter by @var{nbytes} bytes.
        !          7756: @var{nbytes} will be a C expression of type @code{int}.
        !          7757: 
        !          7758: @item ASM_OUTPUT_ALIGN (@var{stream}, @var{power})
        !          7759: A C statement to output to the stdio stream @var{stream} an assembler
        !          7760: instruction to advance the location counter to a multiple of 2 to the
        !          7761: @var{power} bytes.  @var{power} will be a C expression of type @code{int}.
        !          7762: 
        !          7763: @item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size})
        !          7764: A C statement (sans semicolon) to output to the stdio stream
        !          7765: @var{stream} the assembler definition of a common-label named @var{name}
        !          7766: whose size is @var{size} bytes.  Use the expression
        !          7767: @code{assemble_name (@var{stream}, @var{name})} to output the name
        !          7768: itself; before and after that, output the additional assembler syntax
        !          7769: for defining the name, and a newline.
        !          7770: 
        !          7771: This macro controls how the assembler definitions of uninitialized
        !          7772: global variables are output.
        !          7773: 
        !          7774: @item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size})
        !          7775: A C statement (sans semicolon) to output to the stdio stream
        !          7776: @var{stream} the assembler definition of a local-common-label named
        !          7777: @var{name} whose size is @var{size} bytes.  Use the expression
        !          7778: @code{assemble_name (@var{stream}, @var{name})} to output the name
        !          7779: itself; before and after that, output the additional assembler syntax
        !          7780: for defining the name, and a newline.
        !          7781: 
        !          7782: This macro controls how the assembler definitions of uninitialized
        !          7783: static variables are output.
        !          7784: 
        !          7785: @item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line})
        !          7786: A C statment to output DBX or SDB debugging information before code
        !          7787: for line number @var{line} of the current source file to the
        !          7788: stdio stream @var{stream}.
        !          7789: 
        !          7790: This macro need not be defined if the standard form of debugging
        !          7791: information for the debugger in use is appropriate.
        !          7792: 
        !          7793: @item ASM_OUTPUT_IDENT (@var{stream}, @var{string})
        !          7794: A C statement to output something to the assembler file to handle a
        !          7795: @samp{#ident} directive containing the text @var{string}.  If this
        !          7796: macro is not defined, the assembler code @samp{.ident "@var{string}"}
        !          7797: will be output by default.
        !          7798: 
        !          7799: This macro is significant only if @code{IDENT_DIRECTIVE} is defined.
        !          7800: 
        !          7801: @item TARGET_BELL
        !          7802: A C constant expression for the integer value for escape sequence
        !          7803: @samp{\a}.
        !          7804: 
        !          7805: @item TARGET_BS
        !          7806: @itemx TARGET_TAB
        !          7807: @itemx TARGET_NEWLINE
        !          7808: C constant expressions for the integer values for escape sequences
        !          7809: @samp{\b}, @samp{\t} and @samp{\n}.
        !          7810: 
        !          7811: @item TARGET_VT
        !          7812: @itemx TARGET_FF
        !          7813: @itemx TARGET_CR
        !          7814: C constant expressions for the integer values for escape sequences
        !          7815: @samp{\v}, @samp{\f} and @samp{\r}.
        !          7816: 
        !          7817: @item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr})
        !          7818: Define this macro if you are using an unusual assembler that
        !          7819: requires different names for the machine instructions.
        !          7820: 
        !          7821: The definition is a C statement or statements which output an
        !          7822: assembler instruction opcode to the stdio stream @var{stream}.  The
        !          7823: macro-operand @var{ptr} is a variable of type @code{char *} which
        !          7824: points to the opcode name in its ``internal'' form---the form that is
        !          7825: written in the machine description.  The definition should output the
        !          7826: opcode name to @var{stream}, performing any translation you desire, and
        !          7827: increment the variable @var{ptr} to point at the end of the opcode
        !          7828: so that it will not be output twice.
        !          7829: 
        !          7830: In fact, your macro definition may process less than the entire opcode
        !          7831: name, or more than the opcode name; but if you want to process text
        !          7832: that includes @samp{%}-sequences to substitute operands, you must take
        !          7833: care of the substitution yourself.  Just be sure to increment
        !          7834: @var{ptr} over whatever text should not be output normally.
        !          7835: 
        !          7836: If the macro definition does nothing, the instruction is output
        !          7837: in the usual way.
        !          7838: 
        !          7839: @item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands})
        !          7840: If defined, a C statement to be executed just prior to the output of
        !          7841: assembler code for @var{insn}, to modify the extracted operands so
        !          7842: they will be output differently.
        !          7843: 
        !          7844: Here the argument @var{opvec} is the vector containing the operands
        !          7845: extracted from @var{insn}, and @var{noperands} is the number of
        !          7846: elements of the vector which contain meaningful data for this insn.
        !          7847: The contents of this vector are what will be used to convert the insn
        !          7848: template into assembler code, so you can change the assembler output
        !          7849: by changing the contents of the vector.
        !          7850: 
        !          7851: This macro is useful when various assembler syntaxes share a single
        !          7852: file of instruction patterns; by defining this macro differently, you
        !          7853: can cause a large class of instructions to be output differently (such
        !          7854: as with rearranged operands).  Naturally, variations in assembler
        !          7855: syntax affecting individual insn patterns ought to be handled by
        !          7856: writing conditional output routines in those patterns.
        !          7857: 
        !          7858: If this macro is not defined, it is equivalent to a null statement.
        !          7859: 
        !          7860: @item PRINT_OPERAND (@var{stream}, @var{x}, @var{code})
        !          7861: A C compound statement to output to stdio stream @var{stream} the
        !          7862: assembler syntax for an instruction operand @var{x}.  @var{x} is an
        !          7863: RTL expression.
        !          7864: 
        !          7865: @var{code} is a value that can be used to specify one of several ways
        !          7866: of printing the operand.  It is used when identical operands must be
        !          7867: printed differently depending on the context.  @var{code} comes from
        !          7868: the @samp{%} specification that was used to request printing of the
        !          7869: operand.  If the specification was just @samp{%@var{digit}} then
        !          7870: @var{code} is 0; if the specification was @samp{%@var{ltr}
        !          7871: @var{digit}} then @var{code} is the ASCII code for @var{ltr}.
        !          7872: 
        !          7873: If @var{x} is a register, this macro should print the register's name.
        !          7874: The names can be found in an array @code{reg_names} whose type is
        !          7875: @code{char *[]}.  @code{reg_names} is initialized from
        !          7876: @code{REGISTER_NAMES}.
        !          7877: 
        !          7878: When the machine description has a specification @samp{%@var{punct}}
        !          7879: (a @samp{%} followed by a punctuation character), this macro is called
        !          7880: with a null pointer for @var{x} and the punctuation character for
        !          7881: @var{code}.
        !          7882: 
        !          7883: @item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x})
        !          7884: A C compound statement to output to stdio stream @var{stream} the
        !          7885: assembler syntax for an instruction operand that is a memory reference
        !          7886: whose address is @var{x}.  @var{x} is an RTL expression.
        !          7887: 
        !          7888: @item ASM_OPEN_PAREN
        !          7889: @itemx ASM_CLOSE_PAREN
        !          7890: These macros are defined as C string constant, describing the syntax
        !          7891: in the assembler for grouping arithmetic expressions.  The following
        !          7892: definitions are correct for most assemblers:
        !          7893: 
        !          7894: @example
        !          7895: #define ASM_OPEN_PAREN "("
        !          7896: #define ASM_CLOSE_PAREN ")"
        !          7897: @end example
        !          7898: @end table
        !          7899: 
        !          7900: @node Config,, Machine Macros, Top
        !          7901: @chapter The Configuration File
        !          7902: 
        !          7903: The configuration file @file{config-@var{machine}.h} contains macro
        !          7904: definitions that describe the machine and system on which the compiler is
        !          7905: running.  Most of the values in it are actually the same on all machines
        !          7906: that GNU CC runs on, so most all configuration files are identical.  But
        !          7907: there are some macros that vary:
        !          7908: 
        !          7909: @table @code
        !          7910: @item FAILURE_EXIT_CODE
        !          7911: A C expression for the status code to be returned when the compiler
        !          7912: exits after serious errors.
        !          7913: 
        !          7914: @item SUCCESS_EXIT_CODE
        !          7915: A C expression for the status code to be returned when the compiler
        !          7916: exits without serious errors.
        !          7917: @end table
        !          7918: 
        !          7919: @contents
        !          7920: @bye

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.