diff options
Diffstat (limited to 'gcc-1.40/gcc.texinfo')
| -rw-r--r-- | gcc-1.40/gcc.texinfo | 10363 |
1 files changed, 10363 insertions, 0 deletions
diff --git a/gcc-1.40/gcc.texinfo b/gcc-1.40/gcc.texinfo new file mode 100644 index 0000000..2e3792e --- /dev/null +++ b/gcc-1.40/gcc.texinfo @@ -0,0 +1,10363 @@ +\input texinfo @c -*-texinfo-*- + +@settitle Using and Porting GNU CC +@setfilename gcc.info + +@ifinfo +This file documents the use and the internals of the GNU compiler. + +Copyright (C) 1988, 1989, 1990 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``GNU General Public License'' and ``Protect Your +Freedom---Fight `Look And Feel'@w{}'' are included exactly as in the +original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this +one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the sections entitled ``GNU General Public License'' and +``Protect Your Freedom---Fight `Look And Feel'@w{}'' and this permission +notice may be included in translations approved by the Free Software +Foundation instead of in the original English. +@end ifinfo + +@setchapternewpage odd + +@titlepage +@center @titlefont{Using and Porting GNU CC} +@sp 2 +@center Richard M. Stallman +@sp 3 +@center last updated 3 June 1991 +@sp 1 +@center for version 1.40 +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1988, 1989, 1990, 1991 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``GNU General Public License'' and ``Protect Your +Freedom---Fight `Look And Feel'@w{}'' are included exactly as in the +original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this +one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the sections entitled ``GNU General Public License'' and +``Protect Your Freedom---Fight `Look And Feel'@w{}'' and this permission +notice may be included in translations approved by the Free Software +Foundation instead of in the original English. +@end titlepage +@page + +@ifinfo +@node Top, Copying,, (DIR) +@ichapter Introduction + +This manual documents how to run, install and port the GNU C compiler, as +well as its new features and incompatibilities, and how to report bugs. + +@end ifinfo +@menu +* Copying:: GNU General Public License says + how you can copy and share GNU CC. +* Contributors:: People who have contributed to GNU CC. +* Boycott:: Protect your freedom---fight ``look and feel''. +* Options:: Command options supported by @samp{gcc}. +* Installation:: How to configure, compile and install GNU CC. +* Trouble:: If you have trouble installing GNU CC. +* Service:: How to find suppliers of services for GNU CC users. +* Incompatibilities:: Incompatibilities of GNU CC. +* Extensions:: GNU extensions to the C language. +* Bugs:: How to report bugs (if you want to get them fixed). +* Portability:: Goals of GNU CC's portability features. +* Interface:: Function-call interface of GNU CC output. +* Passes:: Order of passes, what they do, and what each file is for. +* RTL:: The intermediate representation that most passes work on. +* Machine Desc:: How to write machine description instruction patterns. +* Machine Macros:: How to write the machine description C macros. +* Config:: Writing the @file{xm-@var{machine}.h} file. +@end menu + +@node Copying, Contributors, Top, Top +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 1, February 1989 + +@display +Copyright @copyright{} 1989 Free Software Foundation, Inc. +675 Mass Ave, Cambridge, MA 02139, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The license agreements of most software companies try to keep users +at the mercy of those companies. By contrast, our General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. The +General Public License applies to the Free Software Foundation's +software and to any other program whose authors commit to using it. +You can use it for your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Specifically, the General Public License is designed to make +sure that you have the freedom to give away or sell copies of free +software, that you receive source code or can get it if you want it, +that you can change the software or use pieces of it in new free +programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of a such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must tell them their rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS +@end iftex +@ifinfo +@center TERMS AND CONDITIONS +@end ifinfo + +@enumerate +@item +This License Agreement applies to any program or other work which +contains a notice placed by the copyright holder saying it may be +distributed under the terms of this General Public License. The +``Program'', below, refers to any such program or work, and a ``work based +on the Program'' means either the Program or any work containing the +Program or a portion of it, either verbatim or with modifications. Each +licensee is addressed as ``you''. + +@item +You may copy and distribute verbatim copies of the Program's source +code as you receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice and +disclaimer of warranty; keep intact all the notices that refer to this +General Public License and to the absence of any warranty; and give any +other recipients of the Program a copy of this General Public License +along with the Program. You may charge a fee for the physical act of +transferring a copy. + +@item +You may modify your copy or copies of the Program or any portion of +it, and copy and distribute such modifications under the terms of Paragraph +1 above, provided that you also do the following: + +@itemize @bullet +@item +cause the modified files to carry prominent notices stating that +you changed the files and the date of any change; and + +@item +cause the whole of any work that you distribute or publish, that +in whole or in part contains the Program or any part thereof, either +with or without modifications, to be licensed at no charge to all +third parties under the terms of this General Public License (except +that you may choose to grant warranty protection to some or all +third parties, at your option). + +@item +If the modified program normally reads commands interactively when +run, you must cause it, when started running for such interactive use +in the simplest and most usual way, to print or display an +announcement including an appropriate copyright notice and a notice +that there is no warranty (or else, saying that you provide a +warranty) and that users may redistribute the program under these +conditions, and telling the user how to view a copy of this General +Public License. + +@item +You may charge a fee for the physical act of transferring a +copy, and you may at your option offer warranty protection in +exchange for a fee. +@end itemize + +Mere aggregation of another independent work with the Program (or its +derivative) on a volume of a storage or distribution medium does not bring +the other work under the scope of these terms. + +@item +You may copy and distribute the Program (or a portion or derivative of +it, under Paragraph 2) in object code or executable form under the terms of +Paragraphs 1 and 2 above provided that you also do one of the following: + +@itemize @bullet +@item +accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of +Paragraphs 1 and 2 above; or, + +@item +accompany it with a written offer, valid for at least three +years, to give any third party free (except for a nominal charge +for the cost of distribution) a complete machine-readable copy of the +corresponding source code, to be distributed under the terms of +Paragraphs 1 and 2 above; or, + +@item +accompany it with the information you received as to where the +corresponding source code may be obtained. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form alone.) +@end itemize + +Source code for a work means the preferred form of the work for making +modifications to it. For an executable file, complete source code means +all the source code for all modules it contains; but, as a special +exception, it need not include source code for modules which are standard +libraries that accompany the operating system on which the executable +file runs, or for standard header files or definitions files that +accompany that operating system. + +@item +You may not copy, modify, sublicense, distribute or transfer the +Program except as expressly provided under this General Public License. +Any attempt otherwise to copy, modify, sublicense, distribute or transfer +the Program is void, and will automatically terminate your rights to use +the Program under this License. However, parties who have received +copies, or rights to use copies, from you under this General Public +License will not have their licenses terminated so long as such parties +remain in full compliance. + +@item +By copying, distributing or modifying the Program (or any work based +on the Program) you indicate your acceptance of this license to do so, +and all its terms and conditions. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the original +licensor to copy, distribute or modify the Program subject to these +terms and conditions. You may not impose any further restrictions on the +recipients' exercise of the rights granted herein. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of the license which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +the license, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL +ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT +LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES +SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE +WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN +ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec Appendix: How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to humanity, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest to +attach them to the start of each source file to most effectively convey +the exclusion of warranty; and each file should have at least the +``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 1, or (at your option) +any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `show c' for details. +@end smallexample + +The hypothetical commands `show w' and `show c' should show the +appropriate parts of the General Public License. Of course, the +commands you use may be called something other than `show w' and `show +c'; they could even be mouse-clicks or menu items---whatever suits your +program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here a sample; alter the names: + +@example +Yoyodyne, Inc., hereby disclaims all copyright interest in the +program `Gnomovision' (a program to direct compilers to make passes +at assemblers) written by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end example + +That's all there is to it! + +@node Contributors, Boycott, Copying, Top +@unnumbered Contributors to GNU CC + +In addition to Richard Stallman, several people have written parts +of GNU CC. + +@itemize @bullet +@item +The idea of using RTL and some of the optimization ideas came from the +U. of Arizona Portable Optimizer, written by Jack Davidson and +Christopher Fraser. See ``Register Allocation and Exhaustive Peephole +Optimization'', Software Practice and Experience 14 (9), Sept. 1984, +857-866. + +@item +Paul Rubin wrote most of the preprocessor. + +@item +Leonard Tower wrote parts of the parser, RTL generator, and RTL +definitions, and of the Vax machine description. + +@item +Ted Lemon wrote parts of the RTL reader and printer. + +@item +Jim Wilson implemented loop strength reduction and some other +loop optimizations. + +@item +Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed +the support for the Sony NEWS machine. + +@item +Charles LaBrec contributed the support for the Integrated Solutions +68020 system. + +@item +Michael Tiemann of MCC wrote most of the description of the National +Semiconductor 32000 series cpu. He also wrote the code for inline +function integration and for the SPARC cpu and Motorola 88000 cpu +and part of the Sun FPA support. + +@item +Jan Stein of the Chalmers Computer Society provided support for +Genix, as well as part of the 32000 machine description. + +@item +Randy Smith finished the Sun FPA support. + +@item +Robert Brown implemented the support for Encore 32000 systems. + +@item +David Kashtan of SRI adapted GNU CC to the Vomit-Making System. + +@item +Alex Crain provided changes for the 3b1. + +@item +Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for +the 9000 series 300. + +@item +William Schelter did most of the work on the Intel 80386 support. + +@item +Christopher Smith did the port for Convex machines. + +@item +Paul Petersen wrote the machine description for the Alliant FX/8. + +@item +Alain Lichnewsky ported GNU CC to the Mips cpu. + +@item +Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the Tahoe. + +@item +Jonathan Stone wrote the machine description for the Pyramid computer. +@end itemize + +@node Boycott, Options, Contributors, Top +@chapter Protect Your Freedom---Fight ``Look And Feel'' + +@quotation +@i{This section is a political message from the League for Programming +Freedom to the users of GNU CC. It is included here as an expression +of support for the League on the part of the Free Software Foundation +and Richard Stallman.} +@end quotation + +Ashton-Tate, Apple, Lotus and Xerox are trying to create a new form of +legal monopoly: a copyright on a class of user interfaces. These +monopolies would cause serious problems for users and developers of +computer software and systems. + +Until a few years ago, the law seemed clear: no one could restrict +others from using a user interface; programmers were free to implement +any interface they chose. Imitating interfaces, sometimes with changes, +was standard practice in the computer field. The interfaces we know +evolved gradually in this way; for example, the Macintosh user interface +drew ideas from the Xerox interface, which in turn drew on work done at +Stanford and SRI. 1-2-3 imitated VisiCalc, and dBase imitated a +database program from JPL. + +Most computer companies, and nearly all computer users, were happy with +this state of affairs. The companies that are suing say it does not +offer ``enough incentive'' to develop their products, but they must have +considered it ``enough'' when they made their decision to do so. It +seems they are not satisfied with the opportunity to continue to compete +in the marketplace---not even with a head start. + +If Xerox, Lotus, Apple and Ashton-Tate are permitted to make law through +the courts, the precedent will hobble the software industry: + +@itemize @bullet +@item +Gratuitous incompatibilities will burden users. Imagine if each +car manufacturer had to arrange the pedals in a different order. + +@item +Software will become and remain more expensive. Users will be +``locked in'' to proprietary interfaces, for which there is no real +competition. + +@item +Large companies have an unfair advantage wherever lawsuits become +commonplace. Since they can easily afford to sue, they can intimidate +small companies with threats even when they don't really have a case. + +@item +User interface improvements will come slower, since incremental +evolution through creative imitation will no longer be permitted. + +@item +Even Apple, etc., will find it harder to make improvements if +they can no longer adapt the good ideas that others introduce, for +fear of weakening their own legal positions. Some users suggest that +this stagnation may already have started. + +@item +If you use GNU software, you might find it of some concern that user +interface copyright will make it hard for the Free Software Foundation +to develop programs compatible with the interfaces that you already +know. +@end itemize + +To protect our freedom from lawsuits like these, a group of programmers +and users have formed a new grass-roots political organization, the +League for Programming Freedom. + +The purpose of the League is to oppose new monopolistic practices such +as user-interface copyright and software patents; it calls for a return +to the legal policies of the recent past, in which these practices were +not allowed. The League is not concerned with free software as an +issue, and not affiliated with the Free Software Foundation. + +The League's membership rolls include John McCarthy, inventor of Lisp, +Marvin Minsky, founder of the Artificial Intelligence lab, Guy L. +Steele, Jr., author of well-known books on Lisp and C, as well as +Richard Stallman, the developer of GNU CC. Please join and add your +name to the list. Membership dues in the League are $42 per year for +programmers, managers and professionals; $10.50 for students; $21 for +others. + +The League needs both activist members and members who only pay their +dues. + +To join, or for more information, phone (617) 492-0023 or write to: + +@example +League for Programming Freedom +1 Kendall Square #143 +P.O. Box 9171 +Cambridge, MA 02139 league@@prep.ai.mit.edu +@end example + +Here are some suggestions from the League for how you can protect your +freedom to write programs: + +@itemize @bullet +@item +Don't buy from Xerox, Lotus, Apple or Ashton-Tate. Buy from their +competitors or from the defendants they are suing. + +@item +Don't develop software to work with the systems made by these companies. + +@item +Port your existing software to competing systems, so that you encourage +users to switch. + +@item +Write letters to company presidents to let them know their conduct +is unacceptable. + +@item +Tell your friends and colleagues about this issue and how it threatens +to ruin the computer industry. + +@item +Above all, don't work for the look-and-feel plaintiffs, and don't +accept contracts from them. + +@item +Write to Congress to explain the importance of this issue. + +@example +House Subcommittee on Intellectual Property +2137 Rayburn Bldg +Washington, DC 20515 + +Senate Subcommittee on Patents, Trademarks and Copyrights +United States Senate +Washington, DC 20510 +@end example +@end itemize + +Express your opinion! You can make a difference. + +@node Options, Installation, Boycott, Top +@chapter GNU CC Command Options + +The GNU C compiler uses a command syntax much like the Unix C compiler. +The @code{gcc} program accepts options and file names as operands. +Multiple single-letter options may @emph{not} be grouped: @samp{-dr} is +very different from @w{@samp{-d -r}}. + +When you invoke GNU CC, it normally does preprocessing, compilation, +assembly and linking. File names which end in @samp{.c} are taken as C +source to be preprocessed and compiled; file names ending in @samp{.i} +are taken as preprocessor output to be compiled; compiler output files +plus any input files with names ending in @samp{.s} are assembled; then +the resulting object files, plus any other input files, are linked +together to produce an executable. + +Command options allow you to stop this process at an intermediate stage. +For example, the @samp{-c} option says not to run the linker. Then the +output consists of object files output by the assembler. + +Other command options are passed on to one stage of processing. Some +options control the preprocessor and others the compiler itself. Yet +other options control the assembler and linker; these are not documented +here, but you rarely need to use any of them. + +Here are the options to control the overall compilation process, including +those that say whether to link, whether to assemble, and so on. + +@table @samp +@item -o @var{file} +Place output in file @var{file}. This applies regardless to whatever +sort of output is being produced, whether it be an executable file, +an object file, an assembler file or preprocessed C code. + +If @samp{-o} is not specified, the default is to put an executable file +in @file{a.out}, the object file @file{@var{source}.c} in +@file{@var{source}.o}, an assembler file in @file{@var{source}.s}, and +preprocessed C on standard output.@refill + +@item -c +Compile or assemble the source files, but do not link. Produce object +files with names made by replacing @samp{.c} or @samp{.s} with +@samp{.o} at the end of the input file names. Do nothing at all for +object files specified as input. + +@item -S +Compile into assembler code but do not assemble. The assembler output +file name is made by replacing @samp{.c} with @samp{.s} at the end of +the input file name. Do nothing at all for assembler source files or +object files specified as input. + +@item -E +Run only the C preprocessor. Preprocess all the C source files +specified and output the results to standard output. + +@item -v +Compiler driver program prints the commands it executes as it runs +the preprocessor, compiler proper, assembler and linker. Some of +these are directed to print their own version numbers. + +@item -pipe +Use pipes rather than temporary files for communication between the +various stages of compilation. This fails to work on some systems +where the assembler is unable to read from a pipe; but the GNU +assembler has no trouble. + +@item -B@var{prefix} +Compiler driver program tries @var{prefix} as a prefix for each +program it tries to run. These programs are @file{cpp}, @file{cc1}, +@file{as} and @file{ld}. + +For each subprogram to be run, the compiler driver first tries the +@samp{-B} prefix, if any. If that name is not found, or if @samp{-B} +was not specified, the driver tries two standard prefixes, which are +@file{/usr/lib/gcc-} and @file{/usr/local/lib/gcc-}. If neither of +those results in a file name that is found, the unmodified program +name is searched for using the directories specified in your +@samp{PATH} environment variable. + +The run-time support file @file{gnulib} is also searched for using +the @samp{-B} prefix, if needed. If it is not found there, the two +standard prefixes above are tried, and that is all. The file is left +out of the link if it is not found by those means. Most of the time, +on most machines, you can do without it. + +You can get a similar result from the environment variable; +@code{GCC_EXEC_PREFIX} if it is defined, its value is used as a prefix +in the same way. If both the @samp{-B} option and the +@code{GCC_EXEC_PREFIX} variable are present, the @samp{-B} option is +used first and the environment variable value second. + +@item -b@var{prefix} +The argument @var{prefix} is used as a second prefix for the compiler +executables and libraries. This prefix is optional: the compiler tries +each file first with it, then without it. This prefix follows the +prefix specified with @samp{-B} or the default prefixes. + +Thus, @samp{-bvax- -Bcc/} in the presence of environment variable +@code{GCC_EXEC_PREFIX} with definition @file{/u/foo/} causes GNU CC to +try the following file names for the preprocessor executable: + +@example +cc/vax-cpp +cc/cpp +/u/foo/vax-cpp +/u/foo/cpp +/usr/local/lib/gcc-vax-cpp +/usr/local/lib/gcc-cpp +/usr/lib/gcc-vax-cpp +/usr/lib/gcc-cpp +@end example +@end table + +These options control the details of C compilation itself. + +@table @samp +@item -ansi +Support all ANSI standard C programs. + +This turns off certain features of GNU C that are incompatible with +ANSI C, such as the @code{asm}, @code{inline} and @code{typeof} +keywords, and predefined macros such as @code{unix} and @code{vax} +that identify the type of system you are using. It also enables the +undesirable and rarely used ANSI trigraph feature. + +The alternate keywords @code{__asm__}, @code{__inline__} and +@code{__typeof__} continue to work despite @samp{-ansi}. You would not +want to use them in an ANSI C program, of course, but it useful to put +them in header files that might be included in compilations done with +@samp{-ansi}. Alternate predefined macros such as @code{__unix__} and +@code{__vax__} are also available, with or without @samp{-ansi}. + +The @samp{-ansi} option does not cause non-ANSI programs to be +rejected gratuitously. For that, @samp{-pedantic} is required in +addition to @samp{-ansi}. + +The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi} +option is used. Some header files may notice this macro and refrain +from declaring certain functions or defining certain macros that the +ANSI standard doesn't call for; this is to avoid interfering with any +programs that might use these names for other things. + +@item -traditional +Attempt to support some aspects of traditional C compilers. +Specifically: + +@itemize @bullet +@item +All @code{extern} declarations take effect globally even if they +are written inside of a function definition. This includes implicit +declarations of functions. + +@item +The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const} +and @code{volatile} are not recognized. (You can still use the alternative +keywords such as @code{__typeof__}, @code{__inline__}, and so on.) + +@item +Comparisons between pointers and integers are always allowed. + +@item +Integer types @code{unsigned short} and @code{unsigned char} promote +to @code{unsigned int}. + +@item +Out-of-range floating point literals are not an error. + +@item +String ``constants'' are not necessarily constant; they are stored in +writable space, and identical looking constants are allocated +separately. + +@item +All automatic variables not declared @code{register} are preserved by +@code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables +not declared @code{volatile} may be clobbered. + +@item +In the preprocessor, comments convert to nothing at all, rather than +to a space. This allows traditional token concatenation. + +@item +In the preprocessor, macro arguments are recognized within string +constants in a macro definition (and their values are stringified, +though without additional quote marks, when they appear in such a +context). The preprocessor always considers a string constant to end +at a newline. + +@item +The predefined macro @code{__STDC__} is not defined when you use +@samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions +which @code{__GNUC__} indicates are not affected by +@samp{-traditional}). If you need to write header files that work +differently depending on whether @samp{-traditional} is in use, by +testing both of these predefined macros you can distinguish four +situations: GNU C, traditional GNU C, other ANSI C compilers, and +other old C compilers. +@end itemize + +@item -O +Optimize. Optimizing compilation takes somewhat more time, and a lot +more memory for a large function. + +Without @samp{-O}, the compiler's goal is to reduce the cost of +compilation and to make debugging produce the expected results. +Statements are independent: if you stop the program with a breakpoint +between statements, you can then assign a new value to any variable or +change the program counter to any other statement in the function and +get exactly the results you would expect from the source code. + +Without @samp{-O}, only variables declared @code{register} are +allocated in registers. The resulting compiled code is a little worse +than produced by PCC without @samp{-O}. + +With @samp{-O}, the compiler tries to reduce code size and execution +time. + +Some of the @samp{-f} options described below turn specific kinds of +optimization on or off. + +@item -g +Produce debugging information in the operating system's native format +(for DBX or SDB). GDB also can work with this debugging information. + +Unlike most other C compilers, GNU CC allows you to use @samp{-g} with +@samp{-O}. The shortcuts taken by optimized code may occasionally +produce surprising results: some variables you declared may not exist +at all; flow of control may briefly move where you did not expect it; +some statements may not be executed because they compute constant +results or their values were already at hand; some statements may +execute in different places because they were moved out of loops. +Nevertheless it proves possible to debug optimized output. This makes +it reasonable to use the optimizer for programs that might have bugs. + +@item -gg +Produce debugging information in the old GDB format. This is obsolete. + +@item -w +Inhibit all warning messages. + +@item -W +Print extra warning messages for these events: + +@itemize @bullet +@item +An automatic variable is used without first being initialized. + +These warnings are possible only in optimizing compilation, +because they require data flow information that is computed only +when optimizing. If you don't specify @samp{-O}, you simply won't +get these warnings. + +These warnings occur only for variables that are candidates for +register allocation. Therefore, they do not occur for a variable that +is declared @code{volatile}, or whose address is taken, or whose size +is other than 1, 2, 4 or 8 bytes. Also, they do not occur for +structures, unions or arrays, even when they are in registers. + +Note that there may be no warning about a variable that is used only +to compute a value that itself is never used, because such +computations may be deleted by data flow analysis before the warnings +are printed. + +These warnings are made optional because GNU CC is not smart +enough to see all the reasons why the code might be correct +despite appearing to have an error. Here is one example of how +this can happen: + +@example +@{ + int x; + switch (y) + @{ + case 1: x = 1; + break; + case 2: x = 4; + break; + case 3: x = 5; + @} + foo (x); +@} +@end example + +@noindent +If the value of @code{y} is always 1, 2 or 3, then @code{x} is +always initialized, but GNU CC doesn't know this. Here is +another common case: + +@example +@{ + int save_y; + if (change_y) save_y = y, y = new_y; + @dots{} + if (change_y) y = save_y; +@} +@end example + +@noindent +This has no bug because @code{save_y} is used only if it is set. + +Some spurious warnings can be avoided if you declare as +@code{volatile} all the functions you use that never return. +@xref{Function Attributes}. + +@item +A nonvolatile automatic variable might be changed by a call to +@code{longjmp}. These warnings as well are possible only in +optimizing compilation. + +The compiler sees only the calls to @code{setjmp}. It cannot know +where @code{longjmp} will be called; in fact, a signal handler could +call it at any point in the code. As a result, you may get a warning +even when there is in fact no problem because @code{longjmp} cannot +in fact be called at the place which would cause a problem. + +@item +A function can return either with or without a value. (Falling +off the end of the function body is considered returning without +a value.) For example, this function would evoke such a +warning: + +@example +foo (a) +@{ + if (a > 0) + return a; +@} +@end example + +Spurious warnings can occur because GNU CC does not realize that +certain functions (including @code{abort} and @code{longjmp}) +will never return. + +@item +An expression-statement contains no side effects. +@end itemize + +In the future, other useful warnings may also be enabled by this +option. + +@item -Wimplicit +Warn whenever a function is implicitly declared. + +@item -Wreturn-type +Warn whenever a function is defined with a return-type that defaults +to @code{int}. Also warn about any @code{return} statement with no +return-value in a function whose return-type is not @code{void}. + +@item -Wunused +Warn whenever a local variable is unused aside from its declaration, +whenever a function is declared static but never defined, and whenever +a statement computes a result that is explicitly not used. + +@item -Wswitch +Warn whenever a @code{switch} statement has an index of enumeral type +and lacks a @code{case} for one or more of the named codes of that +enumeration. (The presence of a @code{default} label prevents this +warning.) @code{case} labels outside the enumeration range also +provoke warnings when this option is used. + +@item -Wcomment +Warn whenever a comment-start sequence @samp{/*} appears in a comment. + +@item -Wtrigraphs +Warn if any trigraphs are encountered (assuming they are enabled). + +@item -Wall +All of the above @samp{-W} options combined. These are all the +options which pertain to usage that we recommend avoiding and that we +believe is easy to avoid, even in conjunction with macros. + +The other @samp{-W@dots{}} options below are not implied by @samp{-Wall} +because certain kinds of useful macros are almost impossible to write +without causing those warnings. + +@item -Wshadow +Warn whenever a local variable shadows another local variable. + +@item -Wid-clash-@var{len} +Warn whenever two distinct identifiers match in the first @var{len} +characters. This may help you prepare a program that will compile +with certain obsolete, brain-damaged compilers. + +@item -Wpointer-arith +Warn about anything that depends on the ``size of'' a function type or +of @code{void}. GNU C assigns these types a size of 1, for +convenience in calculations with @code{void *} pointers and pointers +to functions. + +@item -Wcast-qual +Warn whenever a pointer is cast so as to remove a type qualifier from +the target type. For example, warn if a @code{const char *} is cast +to an ordinary @code{char *}. + +@item -Wwrite-strings +Give string constants the type @code{const char[@var{length}]} so that +copying the address of one into a non-@code{const} @code{char *} +pointer will get a warning. These warnings will help you find at +compile time code that can try to write into a string constant, but +only if you have been very careful about using @code{const} in +declarations and prototypes. Otherwise, it will just be a nuisance; +this is why we did not make @samp{-Wall} request these warnings. + +@item -p +Generate extra code to write profile information suitable for the +analysis program @code{prof}. + +@item -pg +Generate extra code to write profile information suitable for the +analysis program @code{gprof}. + +@item -a +Generate extra code to write profile information for basic blocks, which +will record the number of times each basic block is executed. This data +could be analyzed by a program like @code{tcov}. Note, however, that +the format of the data is not what @code{tcov} expects. Eventually GNU +@code{gprof} should be extended to process this data. + +@item -l@var{library} +Search a standard list of directories for a library named +@var{library}, which is actually a file named +@file{lib@var{library}.a}. The linker uses this file as if it +had been specified precisely by name. + +The directories searched include several standard system directories +plus any that you specify with @samp{-L}. + +Normally the files found this way are library files---archive files +whose members are object files. The linker handles an archive file by +scanning through it for members which define symbols that have so far +been referenced but not defined. But if the file that is found is an +ordinary object file, it is linked in the usual fashion. The only +difference between using an @samp{-l} option and specifying a file name +is that @samp{-l} searches several directories. + +@item -L@var{dir} +Add directory @var{dir} to the list of directories to be searched +for @samp{-l}. + +@item -nostdlib +Don't use the standard system libraries and startup files when linking. +Only the files you specify will be passed to the linker. + +@item -m@var{machinespec} +Machine-dependent option specifying something about the type of target +machine. These options are defined by the macro +@code{TARGET_SWITCHES} in the machine description. The default for +the options is also defined by that macro, which enables you to change +the defaults.@refill + +These are the @samp{-m} options defined in the 68000 machine +description: + +@table @samp +@item -m68020 +@itemx -mc68020 +Generate output for a 68020 (rather than a 68000). This is the +default if you use the unmodified sources. + +@item -m68000 +@item -mc68000 +Generate output for a 68000 (rather than a 68020). + +@item -m68881 +Generate output containing 68881 instructions for floating point. +This is the default if you use the unmodified sources. + +@item -mfpa +Generate output containing Sun FPA instructions for floating point. + +@item -msoft-float +Generate output containing library calls for floating point. + +@item -mshort +Consider type @code{int} to be 16 bits wide, like @code{short int}. + +@item -mnobitfield +Do not use the bit-field instructions. @samp{-m68000} implies +@samp{-mnobitfield}. + +@item -mbitfield +Do use the bit-field instructions. @samp{-m68020} implies +@samp{-mbitfield}. This is the default if you use the unmodified +sources. + +@item -mrtd +Use a different function-calling convention, in which functions +that take a fixed number of arguments return with the @code{rtd} +instruction, which pops their arguments while returning. This +saves one instruction in the caller since there is no need to pop +the arguments there. + +This calling convention is incompatible with the one normally +used on Unix, so you cannot use it if you need to call libraries +compiled with the Unix compiler. + +Also, you must provide function prototypes for all functions that +take variable numbers of arguments (including @code{printf}); +otherwise incorrect code will be generated for calls to those +functions. + +In addition, seriously incorrect code will result if you call a +function with too many arguments. (Normally, extra arguments are +harmlessly ignored.) + +The @code{rtd} instruction is supported by the 68010 and 68020 +processors, but not by the 68000. +@end table + +These @samp{-m} options are defined in the Vax machine description: + +@table @samp +@item -munix +Do not output certain jump instructions (@code{aobleq} and so on) +that the Unix assembler for the Vax cannot handle across long +ranges. + +@item -mgnu +Do output those jump instructions, on the assumption that you +will assemble with the GNU assembler. + +@item -mg +Output code for g-format floating point numbers instead of d-format. +@end table + +These @samp{-m} switches are supported on the Sparc: + +@table @samp +@item -mfpu +Generate output containing floating point instructions. This is the +default if you use the unmodified sources. + +@ignore +@item -msoft-float +Generate output containing library calls for floating point. + +@end ignore +@item -mno-epilogue +Generate separate return instructions for @code{return} statements. +This has both advantages and disadvantages; I don't recall what they +are. +@end table + +These @samp{-m} options are defined in the Convex machine description: + +@table @samp +@item -mc1 +Generate output for a C1. This is the default when the compiler is +configured for a C1. + +@item -mc2 +Generate output for a C2. This is the default when the compiler is +configured for a C2. + +@item -margcount +Generate code which puts an argument count in the word preceding each +argument list. Some nonportable Convex and Vax programs need this +word. (Debuggers don't; this info is in the symbol table.) + +@item -mnoargcount +Omit the argument count word. This is the default if you use the +unmodified sources. +@end table + +@item -f@var{flag} +Specify machine-independent flags. Most flags have both positive and +negative forms; the negative form of @samp{-ffoo} would be +@samp{-fno-foo}. In the table below, only one of the forms is +listed---the one which is not the default. You can figure out the +other form by either removing @samp{no-} or adding it. + +@table @samp +@item -fpcc-struct-return +Use the same convention for returning @code{struct} and @code{union} +values that is used by the usual C compiler on your system. This +convention is less efficient for small structures, and on many +machines it fails to be reentrant; but it has the advantage of +allowing intercallability between GCC-compiled code and PCC-compiled +code. + +@item -ffloat-store +Do not store floating-point variables in registers. This +prevents undesirable excess precision on machines such as the +68000 where the floating registers (of the 68881) keep more +precision than a @code{double} is supposed to have. + +For most programs, the excess precision does only good, but a few +programs rely on the precise definition of IEEE floating point. +Use @samp{-ffloat-store} for such programs. + +@item -fno-asm +Do not recognize @code{asm}, @code{inline} or @code{typeof} as a +keyword. These words may then be used as identifiers. You can +use @code{__asm__}, @code{__inline__} and @code{__typeof__} instead. + +@item -fno-defer-pop +Always pop the arguments to each function call as soon as that +function returns. Normally the compiler (when optimizing) lets +arguments accumulate on the stack for several function calls and +pops them all at once. + +@item -fstrength-reduce +Perform the optimizations of loop strength reduction and +elimination of iteration variables. + +@item -fcombine-regs +Allow the combine pass to combine an instruction that copies one +register into another. This might or might not produce better +code when used in addition to @samp{-O}. I am interested in +hearing about the difference this makes. + +@item -fforce-mem +Force memory operands to be copied into registers before doing +arithmetic on them. This may produce better code by making all +memory references potential common subexpressions. When they are +not common subexpressions, instruction combination should +eliminate the separate register-load. I am interested in hearing +about the difference this makes. + +@item -fforce-addr +Force memory address constants to be copied into registers before +doing arithmetic on them. This may produce better code just as +@samp{-fforce-mem} may. I am interested in hearing about the +difference this makes. + +@item -fomit-frame-pointer +Don't keep the frame pointer in a register for functions that +don't need one. This avoids the instructions to save, set up and +restore frame pointers; it also makes an extra register available +in many functions. @strong{It also makes debugging impossible.} + +On some machines, such as the Vax, this flag has no effect, +because the standard calling sequence automatically handles the +frame pointer and nothing is saved by pretending it doesn't +exist. The machine-description macro +@code{FRAME_POINTER_REQUIRED} controls whether a target machine +supports this flag. @xref{Registers}.@refill + +@item -finline-functions +Integrate all simple functions into their callers. The compiler +heuristically decides which functions are simple enough to be +worth integrating in this way. + +If all calls to a given function are integrated, and the function +is declared @code{static}, then the function is normally not +output as assembler code in its own right. + +@item -fcaller-saves +Enable values to be allocated in registers that will be clobbered by +function calls, by emitting extra instructions to save and restore the +registers around such calls. Such allocation is done only when it +seems to result in better code than would otherwise be produced. + +This option is enabled by default on certain machines, usually those +which have no call-preserved registers to use instead. + +@item -fkeep-inline-functions +Even if all calls to a given function are integrated, and the +function is declared @code{static}, nevertheless output a +separate run-time callable version of the function. + +@item -fwritable-strings +Store string constants in the writable data segment and don't uniquize +them. This is for compatibility with old programs which assume they can +write into string constants. @samp{-traditional} also has this effect. + +Writing into string constants is a very bad idea; ``constants'' should +be constant. + +@item -fcond-mismatch +Allow conditional expressions with mismatched types in the second and +third arguments. The value of such an expression is void. + +@item -fno-function-cse +Do not put function addresses in registers; make each instruction +that calls a constant function contain the function's address +explicitly. + +This option results in less efficient code, but some strange +hacks that alter the assembler output may be confused by the +optimizations performed when this option is not used. + +@item -fvolatile +Consider all memory references through pointers to be volatile. + +@item -fshared-data +Requests that the data and non-@code{const} variables of this +compilation be shared data rather than private data. The distinction +makes sense only on certain operating systems, where shared data is +shared between processes running the same program, while private data +exists in one copy per process. + +@item -funsigned-char +Let the type @code{char} be the unsigned, like @code{unsigned char}. + +Each kind of machine has a default for what @code{char} should +be. It is either like @code{unsigned char} by default or like +@code{signed char} by default. (Actually, at present, the +default is always signed.) + +The type @code{char} is always a distinct type from either +@code{signed char} or @code{unsigned char}, even though its +behavior is always just like one of those two. + +Note that this is equivalent to @samp{-fno-signed-char}, which is the +negative form of @samp{-fsigned-char}. + +@item -fsigned-char +Let the type @code{char} be signed, like @code{signed char}. + +Note that this is equivalent to @samp{-fno-unsigned-char}, which is +the negative form of @samp{-funsigned-char}. + +@item -fdelayed-branch +If supported for the target machine, attempt to reorder instructions +to exploit instruction slots available after delayed branch +instructions. + +@item -ffixed-@var{reg} +Treat the register named @var{reg} as a fixed register; generated +code should never refer to it (except perhaps as a stack pointer, +frame pointer or in some other fixed role). + +@var{reg} must be the name of a register. The register names +accepted are machine-specific and are defined in the +@code{REGISTER_NAMES} macro in the machine description macro +file. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item -fcall-used-@var{reg} +Treat the register named @var{reg} as an allocatable register +that is clobbered by function calls. It may be allocated for +temporaries or variables that do not live across a call. +Functions compiled this way will not save and restore the +register @var{reg}. + +Use of this flag for a register that has a fixed pervasive role +in the machine's execution model, such as the stack pointer or +frame pointer, will produce disastrous results. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item -fcall-saved-@var{reg} +Treat the register named @var{reg} as an allocatable register +saved by functions. It may be allocated even for temporaries or +variables that live across a call. Functions compiled this way +will save and restore the register @var{reg} if they use it. + +Use of this flag for a register that has a fixed pervasive role +in the machine's execution model, such as the stack pointer or +frame pointer, will produce disastrous results. + +A different sort of disaster will result from the use of this +flag for a register in which function values may be returned. + +This flag does not have a negative form, because it specifies a +three-way choice. +@end table + +@item -d@var{letters} +Says to make debugging dumps at times specified by @var{letters}. +Here are the possible letters: + +@table @samp +@item r +Dump after RTL generation. +@item j +Dump after first jump optimization. +@item s +Dump after CSE (including the jump optimization that sometimes +follows CSE). +@item L +Dump after loop optimization. +@item f +Dump after flow analysis. +@item c +Dump after instruction combination. +@item l +Dump after local register allocation. +@item g +Dump after global register allocation. +@item d +Dump after delayed branch scheduling. +@item J +Dump after last jump optimization. +@item m +Print statistics on memory usage, at the end of the run. +@end table + +@item -pedantic +Issue all the warnings demanded by strict ANSI standard C; reject +all programs that use forbidden extensions. + +Valid ANSI standard C programs should compile properly with or without +this option (though a rare few will require @samp{-ansi}). However, +without this option, certain GNU extensions and traditional C features +are supported as well. With this option, they are rejected. There is +no reason to @i{use} this option; it exists only to satisfy pedants. + +@samp{-pedantic} does not cause warning messages for use of the +alternate keywords whose names begin and end with @samp{__}. +@xref{Alternate Keywords}. + +@item -static +On Suns running version 4, this prevents linking with the shared +libraries. (@samp{-g} has the same effect.) +@end table + +These options control the C preprocessor, which is run on each C source +file before actual compilation. If you use the @samp{-E} option, nothing +is done except C preprocessing. Some of these options make sense only +together with @samp{-E} because they request preprocessor output that is +not suitable for actual compilation. + +@table @samp +@item -C +Tell the preprocessor not to discard comments. Used with the +@samp{-E} option. + +@item -I@var{dir} +Search directory @var{dir} for include files. + +@item -I- +Any directories specified with @samp{-I} options before the @samp{-I-} +option are searched only for the case of @samp{#include "@var{file}"}; +they are not searched for @samp{#include <@var{file}>}. + +If additional directories are specified with @samp{-I} options after +the @samp{-I-}, these directories are searched for all @samp{#include} +directives. (Ordinarily @emph{all} @samp{-I} directories are used +this way.) + +In addition, the @samp{-I-} option inhibits the use of the current +directory (where the current input file came from) as the first search +directory for @samp{#include "@var{file}"}. There is no way to override +this effect of @samp{-I-}. With @samp{-I.} you can specify searching +the directory which was current when the compiler was invoked. That is +not exactly the same as what the preprocessor does by default, but it is +often satisfactory. + +@samp{-I-} does not inhibit the use of the standard system directories +for header files. Thus, @samp{-I-} and @samp{-nostdinc} are +independent. + +@item -i @var{file} +Process @var{file} as input, discarding the resulting output, before +processing the regular input file. Because the output generated from +@var{file} is discarded, the only effect of @samp{-i @var{file}} is to +make the macros defined in @var{file} available for use in the main +input. + +@item -nostdinc +Do not search the standard system directories for header files. Only +the directories you have specified with @samp{-I} options (and the +current directory, if appropriate) are searched. + +Between @samp{-nostdinc} and @samp{-I-}, you can eliminate all +directories from the search path except those you specify. + +@item -M +Tell the preprocessor to output a rule suitable for @code{make} +describing the dependencies of each object file. For each source +file, the preprocessor outputs one @code{make}-rule whose target is +the object file name for that source file and whose dependencies are +all the files @samp{#include}d in it. This rule may be a single line +or may be continued with @samp{\}-newline if it is long. + +@samp{-M} implies @samp{-E}. + +@item -MM +Like @samp{-M} but the output mentions only the user-header files +included with @samp{#include "@var{file}"}. System header files +included with @samp{#include <@var{file}>} are omitted. + +@samp{-MM} implies @samp{-E}. + +@item -D@var{macro} +Define macro @var{macro} with the string @samp{1} as its definition. + +@item -D@var{macro}=@var{defn} +Define macro @var{macro} as @var{defn}. + +@item -U@var{macro} +Undefine macro @var{macro}. + +@item -trigraphs +Support ANSI C trigraphs. You don't want to know about this +brain-damage. The @samp{-ansi} option also has this effect. +@end table + +@node Installation, Trouble, Options, Top +@chapter Installing GNU CC + +Here is the procedure for installing GNU CC on a Unix system. + +@menu +* Other Dir:: Compiling in a separate directory (not where the source is). +* Sun Install:: See below for installation on the Sun. +* 3B1 Install:: See below for installation on the 3B1. +* SCO Install:: See below for installation on SCO System V 3.2. (Or ESIX.) +* VMS Install:: See below for installation on VMS. +* HPUX Install:: See below for installation on HPUX. +* Tower Install:: See below for installation on an NCR Tower. +@end menu +@iftex +See below for VMS systems, and modified procedures needed on Sun +systems, 3b1 machines and HPUX. The following section says how to +compile in a separate directory on Unix; here we assume you compile in +the same directory that contains the source files. +@end iftex + +@enumerate +@item +Edit @file{Makefile}. If you are using HPUX, or any form of system V, +you must make a few changes described in comments at the beginning of +the file. Genix requires changes also, and so does the Pyramid. + +@item +On a Sequent system, go to the Berkeley universe. + +@item +Choose configuration files. The easy way to do this is to run the +command file @file{config.gcc} with a single argument, which specifies +the type of machine (and in some cases which operating system). + +Here is a list of the possible arguments: + +@table @samp +@item vax +Vaxes running BSD. +@item vms +Vaxes running VMS. +@item vax-sysv +Vaxes running system V. +@item i386-sysv +Intel 386 PCs running system V. +@item i386-sysv-gas +Intel 386 PCs running system V, using the GNU assembler and GNU +linker. +@item sequent-i386 +Sequent with Intel 386 processors. +@item i386-aix +Intel 386 PCs or PS/2s running AIX. +@item sun2 +Sun 2 running system version 2 or 3. +@item sun3 +Sun 3 running system version 4, with 68881. +Note there we do not provide a configuration file to use an FPA +by default, because programs that establish signal handlers for +floating point traps inherently cannot work with the FPA. +@item sun3-nfp +Sun 3 running system version 4, without 68881. +@item sun4 +Sun 4 running system version 4. @xref{Incompatibilities}, +for calling convention incompatibilities on the Sun 4 (sparc). +@item sun2-os4 +Sun 2 running system version 4. +@item sun3-os3 +Sun 3 running system version 2 or 3, with 68881. +@item sun3-nfp-os3 +Sun 3 running system version 2 or 3, without 68881. +@item sun4-os3 +Sun 4 running system version 2 or 3. @xref{Incompatibilities}, +for calling convention incompatibilities on the Sun 4 (sparc). +@item sun386 +Sun 386 (``roadrunner''). +@item alliant +Alliant FX/8 computer. Note that the standard installed C compiler in +Concentrix 5.0 has a bug which prevent it from compiling GNU CC +correctly. You can patch the compiler bug as follows: + +@example +cp /bin/pcc ./pcc +adb -w ./pcc - << EOF +15f6?w 6610 +EOF +@end example + +Then you must use the @samp{-ip12} option when compiling GNU CC +with the patched compiler, as shown here: + +@example +make CC="./pcc -ip12" CFLAGS=-w +@end example + +Note also that Alliant's version of DBX does not manage to work with the +output from GNU CC. +@item tahoe +The tahoe computer (running BSD, and using DBX). +@item decstation +The DEC 3100 Mips machine (``pmax''). Note that GNU CC cannot generate +debugging information in the unusual format used on the Mips. +@item mips-sysv +The Mips computer, RS series, with the System V environment as default. +Note that GNU CC cannot generate debugging information in the unusual +format used on the Mips. +@item mips-bsd43 +The Mips computer, RS series, with the BSD 4.3 environment as default. +Note that GNU CC cannot generate debugging information in the unusual +format used on the Mips. +@item mips +The Mips computer, M series. Note that GNU CC cannot generate debugging +information in the unusual format used on the Mips. +@item iris +Another variant of the Mips computer, the Silicon Graphics Iris 4D. +Note that GNU CC cannot generate debugging information in the unusual +format used on the Mips. +@item convex-c1 +Convex C1 computer. With operating system version 9, use @samp{cc -pcc} +as the compilation command when building stage 1 of GNU CC. +@item convex-c2 +Convex C2 computer. With operating system version 9, use @samp{cc -pcc} +as the compilation command when building stage 1 of GNU CC. +@item pyramid +Pyramid computer. +@item hp9k320 +HP 9000 series 300 using HPUX assembler. Note there is no +support in GNU CC for HP's debugger; thus, @samp{-g} is not +available in this configuration. +@item hp9k320-gas +HP 9000 series 300 using GNU assembler, linker and debugger. +This requires the HP-adapt package, which is available along with +the GNU linker as part of the ``binutils'' distribution. +This is on the GNU CC distribution tape. +@item hp9k320-old +HP 9000 series 300 using HPUX assembler, in operating system versions +older than 6.5. Note there is no support in GNU CC for HP's debugger; +thus, @samp{-g} is not available in this configuration. +@item hp9k320-bsd +HP 9000 series 300 running BSD. +@item hp9k200-bsd +HP 9000 series 200 running BSD. Note that the C compiler that comes +with this system cannot compile GNU CC; contact @code{law@@super.org} to +get binaries of GNU CC for bootstrapping. Additionally, a minor patch +is necessary if you wish to build kernels with GNU CC; contact +@code{law@@super.org} to get a copy of the patch. +@item isi68 +ISI 68000 or 68020 system with a 68881. +@item isi68-nfp +ISI 68000 or 68020 system without a 68881. +@item news800 +Sony NEWS 68020 system. +@item next +NeXT system. +@item tower +NCR Tower 32 system. +@item altos +Altos 3068. Note that you must use the GNU assembler, linker and +debugger, with COFF-encapsulation. Also, you must fix a kernel +bug. Details in the file @file{ALTOS-README}. +@item 3b1 +AT&T 3b1, a.k.a. 7300 PC. Note that special procedures are needed +to compile GNU CC with this machine's standard C compiler, due to +bugs in that compiler. @xref{3b1 Install}. You can bootstrap it +more easily with previous versions of GNU CC if you have them. +@item 3b1-gas +AT&T 3b1 using the GNU assembler. +@item sequent-ns32k +Sequent containing ns32000 processors. +@item encore +Encore ns32000 system. +@item genix +National Semiconductor ns32000 system. +@item 88000 +Motorola 88000 processor. This port is not finished. +@end table + +Here we spell out what files need to be set up: + +@itemize @bullet +@item +Make a symbolic link named @file{config.h} to the top-level +config file for the machine you are using (@pxref{Config}). This +file is responsible for defining information about the host +machine. It includes @file{tm.h}. + +The file is located in the subdirectory @file{config}. Its name +should be @file{xm-@var{machine}.h}, with these exceptions: + +@table @file +@item xm-vms.h +for vaxen running VMS. +@item xm-vaxv.h +for vaxen running system V. +@item xm-i386v.h +for Intel 80386's running system V. +@item xm-sun386i.h +for Sun roadrunner running any version of the operating system. +@item xm-hp9k320.h +for the HP 9000 series 300. +@item xm-genix.h +for the ns32000 running Genix +@end table + +If your system does not support symbolic links, you might want to +set up @file{config.h} to contain a @samp{#include} command which +refers to the appropriate file. + +@item +Make a symbolic link named @file{tm.h} to the machine-description +macro file for your machine. It should be in the subdirectory +@file{config} and its name should be @file{tm-@var{machine}.h}. + +If your system is a 68000, don't use the file @file{tm-m68k.h} +directly. Instead, use one of these files: + +@table @file +@item tm-sun3.h +for Sun 3 machines with 68881. +@item tm-sun3-nfp.h +for Sun 3 machines with no hardware floating point. +@item tm-sun3os3.h +for Sun 3 machines with 68881, running Sunos version 3. +@item tm-sun3os3nf.h +for Sun 3 machines with no hardware floating point, running Sunos +version 3. +@item tm-sun2.h +for Sun 2 machines. +@item tm-3b1.h +for AT&T 3b1 (aka 7300 Unix PC). +@item tm-isi68.h +for Integrated Solutions systems. This file assumes you +use the GNU assembler. +@item tm-isi68-nfp.h +for Integrated Solutions systems without a 68881. This file assumes you +use the GNU assembler. +@item tm-news800.h +for Sony NEWS systems. +@item tm-hp9k320.h +for HPUX systems, if you are using GNU CC with the system's +assembler and linker. +@item tm-hp9k320g.h +for HPUX systems, if you are using the GNU assembler, linker and +other utilities. Not all of the pieces of GNU software needed +for this mode of operation are as yet in distribution; full +instructions will appear here in the future.@refill +@item tm-tower-as.h +for NCR Tower 32 systems, using the standard system assembler. +@end table + +For the vax, use @file{tm-vax.h} on BSD Unix, @file{tm-vaxv.h} on +system V, or @file{tm-vms.h} on VMS.@refill + +For the Motorola 88000, use @file{tm-m88k.h}. The support for the +88000 does not currently work; it requires extensive changes which +we hope to reconcile in version 2. + +For the 80386, don't use @file{tm-i386.h} directly. Use +@file{tm-i386v.h} if the target machine is running system V, +@file{tm-i386gas.h} if it is running system V but you are using the +GNU assembler and linker, @file{tm-seq386.h} for a Sequent 386 system, +or @file{tm-compaq.h} for a Compaq, or @file{tm-sun386i.h} for a Sun +386 system. + +For the Mips computer, there are five choices: @file{tm-mips.h} for the +M series, @file{tm-mips-bsd.h} for the RS series with BSD, +@file{tm-mips-sysv.h} for the RS series with System V, @file{tm-iris.h} +for the Iris version of the machine, and @file{tm-decstatn.h} for the +Decstation. + +For the 32000, use @file{tm-sequent.h} if you are using a Sequent +machine, or @file{tm-encore.h} for an Encore machine, or +@file{tm-genix.h} if you are using Genix version 3; otherwise, perhaps +@file{tm-ns32k.h} will work for you. + +Note that Genix has bugs in @code{alloca} and @code{malloc}; you must +get the compiled versions of these from GNU Emacs and edit GNU CC's +@file{Makefile} to use them. + +Note that Encore systems are supported only under BSD. + +For Sparc (Sun 4) machines, use @file{tm-sparc.h} with operating system +version 4, and @file{tm-sun4os3.h} with system version 3. + +For Convex systems before version 8.1, use @file{tm-conv1os7.h} or +@file{tm-conv2os7.h}. For versions 8.1 and greater, use @file{tm-convex1.h} +or @file{tm-convex2.h}. You should also bootstrap GCC with @code{pcc} +rather than @code{cc}; one way to do this is with the following commands. + +@example +ln -s /bin/pcc ./cc +set path = (. $path) +@end example + +@item +Make a symbolic link named @file{md} to the machine description +pattern file. It should be in the @file{config} subdirectory and its +name should be @file{@var{machine}.md}; but @var{machine} is often not +the same as the name used in the @file{tm.h} file because the +@file{md} files are more general. + +@item +Make a symbolic link named @file{aux-output.c} to the output +subroutine file for your machine. It should be in the @file{config} +subdirectory and its name should be @file{out-@var{machine}.c}. +@end itemize + +@item +Make sure the Bison parser generator is installed. (This is +unnecessary if the Bison output files @file{c-parse.tab.c} and +@file{cexp.c} are more recent than @file{c-parse.y} and @file{cexp.y} +and you do not plan to change the @samp{.y} files.) + +Bison versions older than Sept 8, 1988 will produce incorrect output +for @file{c-parse.tab.c}. + +@item +If you have a previous version of GCC installed, then chances are +you can compile the new version with that. Do the following: + +@example +make CC="gcc -O" +@end example + +@noindent +Since this produces an optimized executable right away, there is no need +to bootstrap the result with itself except to test it. Therefore, you can +skip directly to the @samp{make install} step below. + +@item +Build the compiler. Just type @samp{make} in the compiler directory. + +Ignore any warnings you may see about ``statement not reached'' in the +@file{insn-emit.c}; they are normal. Any other compilation errors may +represent bugs in the port to your machine or operating system, and +should be investigated and reported (@pxref{Bugs}). + +Some commercial compilers fail to compile GNU CC because they have bugs +or limitations. For example, the Microsoft compiler is said to run out +of macro space. Some Ultrix compilers run out of expression space; then +you need to break up the statement where the problem happens. + +@item +If you are using COFF-encapsulation, you must convert @file{gnulib} to +a GNU-format library at this point. See the file @file{README-ENCAP} +in the directory containing the GNU binary file utilities, for +directions. + +@item +Move the first-stage object files and executables into a subdirectory +with this command: + +@example +make stage1 +@end example + +The files are moved into a subdirectory named @file{stage1}. +Once installation is complete, you may wish to delete these files +with @code{rm -r stage1}. + +@item +Recompile the compiler with itself, with this command: + +@example +make CC=stage1/gcc CFLAGS="-g -O -Bstage1/" +@end example + +This is called making the stage 2 compiler. + +On a 68000 or 68020 system lacking floating point hardware, +unless you have selected a @file{tm.h} file that expects by default +that there is no such hardware, do this instead: + +@example +make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -msoft-float" +@end example + +@item +If you wish to test the compiler by compiling it with itself one more +time, do this (in C shell): + +@example +make stage2 +make CC=stage2/gcc CFLAGS="-g -O -Bstage2/" +foreach file (*.o) +cmp $file stage2/$file +end +@end example + +@noindent +This is called making the stage 3 compiler. Aside from the @samp{-B} +option, the options should be the same as when you made the stage 2 +compiler. + +The @code{foreach} command (written in C shell) will notify you if any of +these stage 3 object files differs from those of stage 2. On BSD systems, +any difference, no matter how innocuous, indicates that the stage 2 +compiler has compiled GNU CC incorrectly, and is therefore a potentially +serious bug which you should investigate and report (@pxref{Bugs}). + +On systems that use COFF object files, bytes 5 to 8 will always be +different, since it is a timestamp. On these systems, you can do the +comparison as follows (in Bourne shell): + +@example +for file in *.o; do +echo $file +tail +10c $file > foo1 +tail +10c stage2/$file > foo2 +cmp foo1 foo2 +done +@end example + +On MIPS machines, you should use the shell script @file{ecoff-cmp} +to compare two object files. + +@item +Install the compiler driver, the compiler's passes and run-time support. +You can use the following command: + +@example +make install +@end example + +@noindent +This copies the files @file{cc1}, @file{cpp} and @file{gnulib} to +files @file{gcc-cc1}, @file{gcc-cpp} and @file{gcc-gnulib} in +directory @file{/usr/local/lib}, which is where the compiler driver +program looks for them. It also copies the driver program @file{gcc} +into the directory @file{/usr/local/bin}, so that it appears in typical +execution search paths.@refill + +@strong{Warning: there is a bug in @code{alloca} in the Sun library. +To avoid this bug, install the binaries of GNU CC that were compiled +by GNU CC. They use @code{alloca} as a built-in function and never +the one in the library.} + +@strong{Warning: the GNU CPP may not work for @file{ioctl.h}, +@file{ttychars.h} and other system header files unless the +@samp{-traditional} option is used.} The bug is in the header files: +at least on some machines, they rely on behavior that is incompatible +with ANSI C. This behavior consists of substituting for macro +argument names when they appear inside of character constants. The +@samp{-traditional} option tells GNU CC to behave the way these +headers expect. + +Because of this problem, you might prefer to configure GNU CC to use +the system's own C preprocessor. To do so, make the file +@file{/usr/local/lib/gcc-cpp} a link to @file{/lib/cpp}. + +Alternatively, on Sun systems and 4.3BSD at least, you can correct the +include files by running the shell script @file{fixincludes}. This +installs modified, corrected copies of the files @file{ioctl.h}, +@file{ttychars.h} and many others, in a special directory where only +GNU CC will normally look for them. This script will work on various +systems because it chooses the files by searching all the system +headers for the problem cases that we know about. + +Use the following command to do this: + +@example +make includes +@end example + +@noindent +If you selected a different directory for GNU CC installation when you +installed it, by specifying the Make variable @code{prefix} or +@code{libdir}, specify it the same way in this command. + +Note that some systems are starting to come with ANSI C system header +files. On these systems, don't run @file{fixincludes}; it may not work, +and is certainly not necessary. + +@strong{Warning:} @file{fixincludes} does not work on many MIPS systems, +because those systems come with circular symbolic links which cause +@samp{ls -lR} to go into an infinite loop. +@end enumerate + +If you cannot install the compiler's passes and run-time support in +@file{/usr/local/lib}, you can alternatively use the @samp{-B} option to +specify a prefix by which they may be found. The compiler concatenates +the prefix with the names @file{cpp}, @file{cc1} and @file{gnulib}. +Thus, you can put the files in a directory @file{/usr/foo/gcc} and +specify @samp{-B/usr/foo/gcc/} when you run GNU CC. + +Also, you can specify an alternative default directory for these files +by setting the Make variable @code{libdir} when you make GNU CC. + +@node Other Dir, Sun Install, Installation, Installation +@section Compilation in a Separate Directory + +If you wish to build the object files and executables in a directory +other than the one containing the source files, here is what you must +do differently: + +@enumerate +@item +Go to that directory before running @file{config.gcc}: + +@example +mkdir gcc-sun3 +cd gcc-sun3 +@end example + +On systems that do not support symbolic links, this directory must be +on the same file system as the source code directory. + +@item +Specify where to find @file{config.gcc} when you run it: + +@example +../gcc-1.36/config.gcc @dots{} +@end example + +@item +Specify where to find the sources, as an argument to @file{config.gcc}: + +@example +../gcc-1.36/config.gcc -srcdir=../gcc-1.36 sun3 +@end example + +The @samp{-srcdir=@var{dir}} option is not needed when the source +directory is the parent of the current directory, because +@file{config.gcc} detects that case automatically. +@end enumerate + +Now, you can run @code{make} in that directory. You need not repeat the +configuration steps shown above, when ordinary source files change. You +must, however, run @code{config.gcc} again when the configuration files +change, if your system does not support symbolic links. + +@node Sun Install, 3b1 Install, Other Dir, Installation +@section Installing GNU CC on the Sun + +Make sure the environment variable @code{FLOAT_OPTION} is not set when +you compile @file{gnulib}. If this option were set to @code{f68881} +when @file{gnulib} is compiled, the resulting code would demand to be +linked with a special startup file and would not link properly without +special pains. + +There is a bug in @code{alloca} in certain versions of the Sun library. +To avoid this bug, install the binaries of GNU CC that were compiled by +GNU CC. They use @code{alloca} as a built-in function and never the one +in the library. + +Some versions of the Sun compiler crash when compiling GNU CC, with a +segmentation fault in cpp. This can sometimes be due to the bulk of +data in the environment variables. You may be able to avoid it by using +the following command to compile GNU CC with Sun CC: + +@example +make CC="TERMCAP=x OBJS=x LIBFUNCS=x STAGESTUFF=x cc" +@end example + +Another problem that often happens on Suns is that you get a crash when +building stage 2, when @code{genflags} is run. + +One reason for such as crash is if you configured GNU CC for the wrong +version of SunOS. Starting with version 1.38, configurations @code{sun3} +and @code{sun4} are for SunOS 4, so this problem should no longer happen. + +Another cause of the same symptom is having installed the GNU linker +with an earlier version of SunOS. The version that worked before +stopped working due to a change in the format of executables in SunOS +4.1. Many sites have installed the GNU linker as +@file{/usr/local/lib/gcc-ld}, often as part of installing GNU C++. So +if you get such crashes and you have used the proper configuration, try +deleting @file{/usr/local/lib/gcc-ld}. + +The current version of the GNU linker, found in the current binutils +release, does work with SunOS 4.1. + +@node 3b1 Install, SCO Install, Sun Install, Installation +@section Installing GNU CC on the 3b1 + +Installing GNU CC on the 3b1 is difficult if you do not already have +GNU CC running, due to bugs in the installed C compiler. However, +the following procedure might work. We are unable to test it. + +@enumerate +@item +Comment out the @samp{#include "config.h"} line on line 37 of +@file{cccp.c} and do @samp{make cpp}. This makes a preliminary version +of GNU cpp. + +@item +Save the old @file{/lib/cpp} and copy the preliminary GNU cpp to that +file name. + +@item +Undo your change in @file{cccp.c}, or reinstall the original version, +and do @samp{make cpp} again. + +@item +Copy this final version of GNU cpp into @file{/lib/cpp}. + +@item +Replace every occurrence of @code{obstack_free} in @file{tree.c} +with @code{_obstack_free}. + +@item +Run @code{make} to get the first-stage GNU CC. + +@item +Reinstall the original version of @file{/lib/cpp}. + +@item +Now you can compile GNU CC with itself and install it in the normal +fashion. +@end enumerate + +If you have installed an earlier version of GCC, you can compile the +newer version with that. However, you will run into trouble compiling +@file{gnulib}, since that is normally compiled with CC. To solve the +problem, uncomment this line in @file{Makefile}: + +@example +CCLIBFLAGS = -B/usr/local/lib/gcc- -tp -Wp,-traditional +@end example + +@node SCO Install, VMS Install, 3B1 Install, Installation +@section Installing GNU CC on SCO System V 3.2 +@cindex Installation on SCO systems + +The compiler that comes with this system does not work properly with +@samp{-O}. Therefore, you should redefine the Make variable +@code{CCLIBFLAGS} not to use @samp{-O}. + +You should also edit @file{Makefile} to enable the lines that set +@code{CLIB} to @code{-lPW}, and the ones specifically labeled as being +for SCO, that set @code{RANLIB}, and that set @code{CC} and @code{OLDCC} +to @code{rcc}. + +Also, edit the definition of @code{USER_H} to remove the file @file{limits.h}. + +Then you can run @samp{config.gcc i386-sco} and finish building GNU CC +normally. + +The same recipe should work on ESIX, but use @samp{config.gcc i386-esix} +instead. + +@node VMS Install, HPUX Install, SCO Install, Installation +@section Installing GNU CC on VMS + +The VMS version of GNU CC is distributed in a backup saveset containing +both source code and precompiled binaries. + +To install the @file{gcc} command so you can use the compiler easily, in +the same manner as you use the VMS C compiler, you must install the VMS CLD +file for GNU CC as follows: + +@enumerate +@item +Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE} +to point to the directories where the GNU CC executables +(@file{gcc-cpp}, @file{gcc-cc1}, etc.) and the C include files are +kept. This should be done with the commands:@refill + +@example +$ assign /super /system disk:[gcc.] gnu_cc +$ assign /super /system disk:[gcc.include.] gnu_cc_include +@end example + +@noindent +with the appropriate disk and directory names. These commands can be +placed in your system startup file so they will be executed whenever +the machine is rebooted. You may, if you choose, do this via the +@file{GCC_INSTALL.COM} script in the @file{[GCC]} directory. + +@item +Install the @file{GCC} command with the command line: + +@example +$ set command /table=sys$library:dcltables gnu_cc:[000000]gcc +@end example + +@item +To install the help file, do the following: + +@example +$ lib/help sys$library:helplib.hlb gcc.hlp +@end example + +@noindent +Now you can invoke the compiler with a command like @samp{gcc /verbose +file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in +Unix. +@end enumerate + +We try to put corresponding binaries and sources on the VMS distribution +tape. But sometimes the binaries will be from an older version that the +sources, because we don't always have time to update them. (Use the +@samp{/verbose} option to determine the version number of the binaries and +compare it with the source file @file{version.c} to tell whether this is +so.) In this case, you should use the binaries you get to recompile the +sources. If you must recompile, here is how: + +@enumerate +@item +Copy the file @file{tm-vms.h} to @file{tm.h}, @file{xm-vms.h} to +@file{config.h}, @file{vax.md} to @file{md.} and @file{out-vax.c} +to @file{aux-output.c}. The files to be copied are found in the +subdirectory named @file{config}; they should be copied to the +main directory of GNU CC.@refill + +@item +Setup the logical names and command tables as defined above. In +addition, define the vms logical name @samp{GNU_BISON} to point at the +to the directories where the Bison executable is kept. This should be +done with the command:@refill + +@example +$ assign /super /system disk:[bison.] gnu_bison +@end example + +You may, if you choose, use the @file{INSTALL_BISON.COM} script in the +@file{[BISON]} directory. + +@item +Install the @samp{BISON} command with the command line:@refill + +@example +$ set command /table=sys$library:dcltables gnu_bison:[000000]bison +@end example + +@item +Type @samp{@@make} to do recompile everything. + +If you are compiling with a version of GNU CC older than 1.33, specify +@samp{/DEFINE=("inline=")} as an option in all the compilations. This +requires editing all the @code{gcc} commands in @file{make-cc1.com}. +(The older versions had problems supporting @code{inline}.) Once you +have a working 1.33 or newer GNU CC, you can change this file back. +@end enumerate + +Due to the differences between the filesystems of Unix and VMS, the +preprocessor attempts to translate the names of include files into +something that VMS will understand. The basic strategy is to prepend a +prefix to the specification of the include file, convert the whole +filename to a VMS filename, and then try to open the file. The +preprocessor tries various prefixes until one of them succeeds. + +The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is +where GNU_C header files are traditionally stored. If a header file is +not found there, @samp{SYS$SYSROOT:[SYSLIB.]} is tried next. If the +preprocessor is still unable to locate the file, it then assumes that +the include file specification is a valid VMS filename all by itself, +and it uses this filename to attempt to open the include file. If none +of these strategies succeeds, the preprocessor reports an error. + +If you wish to store header files in non-standard locations, then you +can assign the logical @samp{GNU_CC_INCLUDE} to be a search list, where +each element of the list is suitable for use with a rooted logical. + +With this version of GNU CC, @code{const} global variables now work +properly. Unless, however, the @code{const} modifier is also specified +in every external declaration of the variable in all of the source files +that use that variable, the linker will issue warnings about conflicting +attributes for the variable, since the linker does not know if the +variable should be read-only. The program will still work, but the +variable will be placed in writable storage. + +Due to an assembler bug, offsets to static constants are sometimes +incorrectly evaluated. This bug is present in GAS 1.38.1, and should be +fixed in the next version. + +Under previous versions of GNU CC, the generated code would occasionally +give strange results when linked to the sharable @file{VAXCRTL} library. +Now this should work. + +Even with this version, however, GNU CC itself should not be linked to the +sharable @file{VAXCRTL}. The @file{qsort} routine supplied with @file{VAXCRTL} +has a bug which can cause a compiler crash. + +Similarly, the preprocessor should not be linked to the sharable +@file{VAXCRTL}. The @code{strncat} routine supplied with @file{VAXCRTL} has a +bug which can cause the preprocessor to go into an infinite loop. + +It should be pointed out that if you attempt to link to the sharable +@file{VAXCRTL}, the VMS linker will strongly resist any effort to force +it to use the @code{qsort} and @code{strncat} routines from +@file{gcclib}. Until the bugs in @file{VAXCRTL} have been fixed, +linking any of the compiler components to the sharable VAXCRTL is not +recommended. (These routines can be bypassed by placing duplicate copies +of @code{qsort} and @code{strncat} in @file{gcclib} under different +names, and patching the compiler sources to use these routines). Both +of the bugs in @file{VAXCRTL} are still present in VMS version 5.4-1, +which is the most recent version as of this writing. + +The executables that are generated by @file{make-cc1.com} and +@file{make-cccp.com} use the non-shared version of @file{VAXCRTL} (and +thus use the @code{qsort} and @code{strncat} routines from +@file{gcclib.olb}). + +Note that GNU CC on VMS now generates debugging information to describe +the programs symbols to the VMS debugger. However, you need version 1.37 +or later of GAS in order to output them properly in the object file. + +The VMS linker does not distinguish between upper and lower case letters +in function and variable names. However, usual practice in C is to +distinguish case. Normally GNU C (by means of the assembler GAS) +implements usual C behavior by augmenting each name that is not all +lower-case. A name is augmented by truncating it to at most 23 +characters and then adding more characters at the end which encode the +case pattern the rest. + +Name augmentation yields bad results for programs that use precompiled +libraries (such as Xlib) which were generated by another compiler. Use +the compiler option @samp{/NOCASE_HACK} to inhibits augmentation; it +makes external C functions and variables case-independent as is usual on +VMS. Alternatively, you could write all references to the functions and +variables in such libraries using lower case; this will work on VMS, but +is not portable to other systems. In cases where you need to +selectively inhibit augmentation, you can define a macro for each mixed +case symbol for which you wish to inhibit augmentation, where the macro +expands into the lower case equivalent of the name. + +@node HPUX Install, Tower Install, VMS Install, Installation +@section Installing GNU CC on HPUX + +To install GNU CC on HPUX, you must start by editing the file +@file{Makefile}. Search for the string @samp{HPUX} to find comments +saying what to change. You need to change some variable definitions and +(if you are using GAS) some lines in the rule for the target +@samp{gnulib}. + +To avoid errors when linking programs with @samp{-g}, create an empty +library named @file{libg.a}. An easy way to do this is: + +@example +ar rc /usr/local/lib/libg.a +@end example + +To compile with the HPUX C compiler, you must specify get the file +@file{alloca.c} from GNU Emacs. Then, when you run @code{make}, use +this argument: + +@example +make ALLOCA=alloca.o +@end example + +When recompiling GNU CC with itself, do not define @code{ALLOCA}. +Instead, an @samp{-I} option needs to be added to @code{CFLAGS} as +follows: + +@example +make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -I../binutils/hp-include" +@end example + +@node Tower Install,, HPUX Install, Installation +@section Installing GNU CC on an NCR Tower + +On an NCR Tower model 4x0 or 6x0, you may have trouble because the +default maximum virtual address size of a process is just 1 Mb. Most +often you will find this problem while compiling GNU CC with itself. + +The only way to solve the problem is to reconfigure the kernel. +Add a line such as this to the configuration file: + +@example +MAXUMEM = 4096 +@end example + +@noindent +and then relink the kernel and reboot the machine. + + +@node Trouble, Service, Installation, Top +@chapter Known Causes of Trouble with GNU CC + +Here are some of the things that have caused trouble for people installing +or using GNU CC. + +@itemize @bullet +@item +On certain systems, defining certain environment variables such as +@code{CC} can interfere with the functioning of @code{make}. + +@item +Cross compilation can run into trouble for certain machines because +some target machines' assemblers require floating point numbers to be +written as @emph{integer} constants in certain contexts. + +The compiler writes these integer constants by examining the floating +point value as an integer and printing that integer, because this is +simple to write and independent of the details of the floating point +representation. But this does not work if the compiler is running on +a different machine with an incompatible floating point format, or +even a different byte-ordering. + +In addition, correct constant folding of floating point values +requires representing them in the target machine's format. +(The C standard does not quite require this, but in practice +it is the only way to win.) + +It is now possible to overcome these problems by defining macros such +as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of +work for each target machine. @xref{Cross-compilation}. + +@item +Users often think it is a bug when GNU CC reports an error for code +like this: + +@example +int foo (short); + +int foo (x) + short x; +@{@dots{}@} +@end example + +The error message is correct: this code really is erroneous, because the +old-style non-prototype definition passes subword integers in their +promoted types. In other words, the argument is really an @code{int}, +not a @code{short}. The correct prototype is this: + +@example +int foo (int); +@end example + +@item +Users often think it is a bug when GNU CC reports an error for code +like this: + +@example +int foo (struct mumble *); + +struct mumble @{ @dots{} @}; + +int foo (struct mumble *x) +@{ @dots{} @} +@end example + +This code really is erroneous, because the scope of @code{struct +mumble} the prototype is limited to the argument list containing it. +It does not refer to the @code{struct mumble} defined with file scope +immediately below---they are two unrelated types with similar names in +different scopes. + +But in the definition of @code{foo}, the file-scope type is used +because that is available to be inherited. Thus, the definition and +the prototype do not match, and you get an error. + +This behavior may seem silly, but it's what the ANSI standard +specifies. It is easy enough for you to make your code work by moving +the definition of @code{struct mumble} above the prototype. I don't +think it's worth being incompatible for. +@end itemize + +Additional problems are described in @ref{Incompatibilities}. + +@node Service, Incompatibilities, Trouble, Top +@chapter How To Get Help with GNU CC + +If you need help installing, using or changing GNU CC, there are two +ways to find it: + +@itemize @bullet +@item +Send a message to a suitable network mailing list. First try +@code{bug-gcc@@prep.ai.mit.edu}, and if that brings no response, try +@code{help-gcc@@prep.ai.mit.edu}. + +@item +Look in the service directory for someone who might help you for a fee. +The service directory is found in the file named @file{SERVICE} in the +GNU CC distribution. +@end itemize + +@node Incompatibilities, Extensions, Service, Top +@chapter Incompatibilities of GNU CC + +There are several noteworthy incompatibilities between GNU C and most +existing (non-ANSI) versions of C. The @samp{-traditional} option +eliminates most of these incompatibilities, @emph{but not all}, by +telling GNU C to behave like older C compilers. + +@itemize @bullet +@item +GNU CC normally makes string constants read-only. If several +identical-looking string constants are used, GNU CC stores only one +copy of the string. + +One consequence is that you cannot call @code{mktemp} with a string +constant argument. The function @code{mktemp} always alters the +string its argument points to. + +Another consequence is that @code{sscanf} does not work on some +systems when passed a string constant as its format control string. +This is because @code{sscanf} incorrectly tries to write into the +string constant. Likewise @code{fscanf} and @code{scanf}. + +The best solution to these problems is to change the program to use +@code{char}-array variables with initialization strings for these +purposes instead of string constants. But if this is not possible, +you can use the @samp{-fwritable-strings} flag, which directs GNU CC +to handle string constants the same way most C compilers do. +@samp{-traditional} also has this effect, among others. + +@item +GNU CC does not substitute macro arguments when they appear inside of +string constants. For example, the following macro in GNU CC + +@example +#define foo(a) "a" +@end example + +@noindent +will produce output @code{"a"} regardless of what the argument @var{a} is. + +The @samp{-traditional} option directs GNU CC to handle such cases +(among others) in the old-fashioned (non-ANSI) fashion. + +@item +When you use @code{setjmp} and @code{longjmp}, the only automatic +variables guaranteed to remain valid are those declared +@code{volatile}. This is a consequence of automatic register +allocation. Consider this function: + +@example +jmp_buf j; + +foo () +@{ + int a, b; + + a = fun1 (); + if (setjmp (j)) + return a; + + a = fun2 (); + /* @r{@code{longjmp (j)} may be occur in @code{fun3}.} */ + return a + fun3 (); +@} +@end example + +Here @code{a} may or may not be restored to its first value when the +@code{longjmp} occurs. If @code{a} is allocated in a register, then +its first value is restored; otherwise, it keeps the last value stored +in it. + +If you use the @samp{-W} option with the @samp{-O} option, you will +get a warning when GNU CC thinks such a problem might be possible. + +The @samp{-traditional} option directs GNU C to put variables in +the stack by default, rather than in registers, in functions that +call @code{setjmp}. This results in the behavior found in +traditional C compilers. + +@item +Declarations of external variables and functions within a block apply +only to the block containing the declaration. In other words, they +have the same scope as any other declaration in the same place. + +In some other C compilers, a @code{extern} declaration affects all the +rest of the file even if it happens within a block. + +The @samp{-traditional} option directs GNU C to treat all @code{extern} +declarations as global, like traditional compilers. + +@item +In traditional C, you can combine @code{long}, etc., with a typedef name, +as shown here: + +@example +typedef int foo; +typedef long foo bar; +@end example + +In ANSI C, this is not allowed: @code{long} and other type modifiers +require an explicit @code{int}. Because this criterion is expressed +by Bison grammar rules rather than C code, the @samp{-traditional} +flag cannot alter it. + +@item +PCC allows typedef names to be used as function parameters. The +difficulty described immediately above applies here too. + +@item +PCC allows whitespace in the middle of compound assignment operators +such as @samp{+=}. GNU CC, following the ANSI standard, does not +allow this. The difficulty described immediately above applies here +too. + +@item +GNU CC will flag unterminated character constants inside of preprocessor +conditionals that fail. Some programs have English comments enclosed in +conditionals that are guaranteed to fail; if these comments contain +apostrophes, GNU CC will probably report an error. For example, +this code would produce an error: + +@example +#if 0 +You can't expect this to work. +#endif +@end example + +The best solution to such a problem is to put the text into an actual +C comment delimited by @samp{/*@dots{}*/}. However, +@samp{-traditional} suppresses these error messages. + +@item +When compiling functions that return @code{float}, PCC converts it to +a double. GNU CC actually returns a @code{float}. If you are concerned +with PCC compatibility, you should declare your functions to return +@code{double}; you might as well say what you mean. + +@item +When compiling functions that return structures or unions, GNU CC +output code normally uses a method different from that used on most +versions of Unix. As a result, code compiled with GNU CC cannot call +a structure-returning function compiled with PCC, and vice versa. + +The method used by GNU CC is as follows: a structure or union which is 1, +2, 4 or 8 bytes long is returned like a scalar. A structure or union +with any other size is stored into an address supplied by the caller +in a special, fixed register. + +PCC usually handles all sizes of structures and unions by returning +the address of a block of static storage containing the value. This +method is not used in GNU CC because it is slower and nonreentrant. + +You can tell GNU CC to use the PCC convention with the option +@samp{-fpcc-struct-return}. +@end itemize + +There are also system-specific incompatibilities. + +@itemize @bullet +@item +On the Sparc, GNU CC uses an incompatible calling convention for +structures. It passes them by including their contents in the argument +list, whereas the standard compiler passes them effectively by +reference. + +This really ought to be fixed, but such calling conventions are not +yet supported in GNU CC, so it isn't straightforward to fix it. +GNU CC version 2 will use a compatible calling convention. + +The convention for structure returning is also incompatible, and +@samp{-fpcc-struct-return} does not help. + +@item +The Sparc version of @code{setjmp} interacts badly with unexpected stack +adjustments. With rare exceptions, you cannot use @code{setjmp} in a +function which moves the stack pointer. + +In the current version of GNU CC, there are three ways that the stack +pointer can change value: (1) calls to @code{alloca}, (2) use of +variable-sized objects, and (3) calls to functions with parameters that +do not all fit in the argument-passing registers (e.g., more than 6 +parameters). You should avoid all three in functions that call +@code{setjmp}. + +The cause of the problem is the way that Sun implemented register +windows. The 64 bytes at addresses @code{%sp} through @code{%sp+63} +correspond to the register window save area. When a register window +must be spilled, its stack pointer is located, and the registers are +dumped starting at that address. Similarly, when a register window must +be restored, its stack pointer is located, and the registers are +restored from that address. + +When @code{setjmp} is called, the current register window's registers +are saved into the register save area, and when @code{longjmp} is +called, they are restored (actually, @emph{all} register windows are +restored from all valid register windows at the time @code{longjmp} is +called). If there is a change in the value of the stack pointer bewteen +the @code{setjmp} and @code{longjmp} calls, when the registers are +restored, they are restored with random values. + +@item +On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved +by function calls. We have not been able to tell whether the C compiler +agrees with the Fortran compiler. Currently, GNU CC treats these registers +as temporaries on the Vax, which is compatible with BSD Unix. + +If we learn for certain that Ultrix has departed from the traditional +BSD calling convention, we will change GNU CC for Ultrix to fit. In the +mean time, you can use these options to produce code compatible with the +Fortran compiler: + +@example +-fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5 +@end example + +@item +DBX rejects some files produced by GNU CC, though it accepts similar +constructs in output from PCC. Until someone can supply a coherent +description of what is valid DBX input and what is not, there is +nothing I can do about these problems. You are on your own. +@end itemize + +@node Extensions, Bugs, Incompatibilities, Top +@chapter GNU Extensions to the C Language + +GNU C provides several language features not found in ANSI standard C. +(The @samp{-pedantic} option directs GNU CC to print a warning message if +any of these features is used.) To test for the availability of these +features in conditional compilation, check for a predefined macro +@code{__GNUC__}, which is always defined under GNU CC. + +@menu +* Statement Exprs:: Putting statements and declarations inside expressions. +* Naming Types:: Giving a name to the type of some expression. +* Typeof:: @code{typeof}: referring to the type of an expression. +* Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues. +* Conditionals:: Omitting the middle operand of a @samp{?:} expression. +* Zero-Length:: Zero-length arrays. +* Variable-Length:: Arrays whose length is computed at run time. +* Subscripting:: Any array can be subscripted, even if not an lvalue. +* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. +* Initializers:: Non-constant initializers. +* Constructors:: Constructor expressions give structures, unions + or arrays as values. +* Function Attributes:: Declaring that functions have no side effects, + or that they can never return. +* Dollar Signs:: Dollar sign is allowed in identifiers. +* Alignment:: Inquiring about the alignment of a type or variable. +* Inline:: Defining inline functions (as fast as macros). +* Extended Asm:: Assembler instructions with C expressions as operands. + (With them you can define ``built-in'' functions.) +* Asm Labels:: Specifying the assembler name to use for a C symbol. +* Explicit Reg Vars:: Defining variables residing in specified registers. +* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. +@end menu + +@node Statement Exprs, Naming Types, Extensions, Extensions +@section Statements and Declarations inside of Expressions + +A compound statement in parentheses may appear inside an expression in GNU +C. This allows you to declare variables within an expression. For +example: + +@example +(@{ int y = foo (); int z; + if (y > 0) z = y; + else z = - y; + z; @}) +@end example + +@noindent +is a valid (though slightly more complex than necessary) expression +for the absolute value of @code{foo ()}. + +This feature is especially useful in making macro definitions ``safe'' (so +that they evaluate each operand exactly once). For example, the +``maximum'' function is commonly defined as a macro in standard C as +follows: + +@example +#define max(a,b) ((a) > (b) ? (a) : (b)) +@end example + +@noindent +But this definition computes either @var{a} or @var{b} twice, with bad +results if the operand has side effects. In GNU C, if you know the +type of the operands (here let's assume @code{int}), you can define +the macro safely as follows: + +@example +#define maxint(a,b) \ + (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) +@end example + +Embedded statements are not allowed in constant expressions, such as +the value of an enumeration constant, the width of a bit field, or +the initial value of a static variable. + +If you don't know the type of the operand, you can still do this, but you +must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming +Types}). + +@node Naming Types, Typeof, Statement Exprs, Extensions +@section Naming an Expression's Type + +You can give a name to the type of an expression using a @code{typedef} +declaration with an initializer. Here is how to define @var{name} as a +type name for the type of @var{exp}: + +@example +typedef @var{name} = @var{exp}; +@end example + +This is useful in conjunction with the statements-within-expressions +feature. Here is how the two together can be used to define a safe +``maximum'' macro that operates on any arithmetic type: + +@example +#define max(a,b) \ + (@{typedef _ta = (a), _tb = (b); \ + _ta _a = (a); _tb _b = (b); \ + _a > _b ? _a : _b; @}) +@end example + +The reason for using names that start with underscores for the local +variables is to avoid conflicts with variable names that occur within the +expressions that are substituted for @code{a} and @code{b}. Eventually we +hope to design a new form of declaration syntax that allows you to declare +variables whose scopes start only after their initializers; this will be a +more reliable way to prevent such conflicts. + +@node Typeof, Lvalues, Naming Types, Extensions +@section Referring to a Type with @code{typeof} + +Another way to refer to the type of an expression is with @code{typeof}. +The syntax of using of this keyword looks like @code{sizeof}, but the +construct acts semantically like a type name defined with @code{typedef}. + +There are two ways of writing the argument to @code{typeof}: with an +expression or with a type. Here is an example with an expression: + +@example +typeof (x[0](1)) +@end example + +@noindent +This assumes that @code{x} is an array of functions; the type described +is that of the values of the functions. + +Here is an example with a typename as the argument: + +@example +typeof (int *) +@end example + +@noindent +Here the type described is that of pointers to @code{int}. + +If you are writing a header file that must work when included in ANSI C +programs, write @code{__typeof__} instead of @code{typeof}. +@xref{Alternate Keywords}. + +A @code{typeof}-construct can be used anywhere a typedef name could be +used. For example, you can use it in a declaration, in a cast, or inside +of @code{sizeof} or @code{typeof}. + +@itemize @bullet +@item +This declares @code{y} with the type of what @code{x} points to. + +@example +typeof (*x) y; +@end example + +@item +This declares @code{y} as an array of such values. + +@example +typeof (*x) y[4]; +@end example + +@item +This declares @code{y} as an array of pointers to characters: + +@example +typeof (typeof (char *)[4]) y; +@end example + +@noindent +It is equivalent to the following traditional C declaration: + +@example +char *y[4]; +@end example + +To see the meaning of the declaration using @code{typeof}, and why it +might be a useful way to write, let's rewrite it with these macros: + +@example +#define pointer(T) typeof(T *) +#define array(T, N) typeof(T [N]) +@end example + +@noindent +Now the declaration can be rewritten this way: + +@example +array (pointer (char), 4) y; +@end example + +@noindent +Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 +pointers to @code{char}. +@end itemize + +@node Lvalues, Conditionals, Typeof, Extensions +@section Generalized Lvalues + +Compound expressions, conditional expressions and casts are allowed as +lvalues provided their operands are lvalues. This means that you can take +their addresses or store values into them. + +For example, a compound expression can be assigned, provided the last +expression in the sequence is an lvalue. These two expressions are +equivalent: + +@example +(a, b) += 5 +a, (b += 5) +@end example + +Similarly, the address of the compound expression can be taken. These two +expressions are equivalent: + +@example +&(a, b) +a, &b +@end example + +A conditional expression is a valid lvalue if its type is not void and the +true and false branches are both valid lvalues. For example, these two +expressions are equivalent: + +@example +(a ? b : c) = 5 +(a ? b = 5 : (c = 5)) +@end example + +A cast is a valid lvalue if its operand is valid. Taking the address of +the cast is the same as taking the address without a cast, except for the +type of the result. For example, these two expressions are equivalent (but +the second may be valid when the type of @code{a} does not permit a cast to +@code{int *}). + +@example +&(int *)a +(int **)&a +@end example + +A simple assignment whose left-hand side is a cast works by converting the +right-hand side first to the specified type, then to the type of the inner +left-hand side expression. After this is stored, the value is converter +back to the specified type to become the value of the assignment. Thus, if +@code{a} has type @code{char *}, the following two expressions are +equivalent: + +@example +(int)a = 5 +(int)(a = (char *)5) +@end example + +An assignment-with-arithmetic operation such as @samp{+=} applied to a cast +performs the arithmetic using the type resulting from the cast, and then +continues as in the previous case. Therefore, these two expressions are +equivalent: + +@example +(int)a += 5 +(int)(a = (char *) ((int)a + 5)) +@end example + +@node Conditionals, Zero-Length, Lvalues, Extensions +@section Conditional Expressions with Omitted Middle-Operands + +The middle operand in a conditional expression may be omitted. Then +if the first operand is nonzero, its value is the value of the conditional +expression. + +Therefore, the expression + +@example +x ? : y +@end example + +@noindent +has the value of @code{x} if that is nonzero; otherwise, the value of +@code{y}. + +This example is perfectly equivalent to + +@example +x ? x : y +@end example + +@noindent +In this simple case, the ability to omit the middle operand is not +especially useful. When it becomes useful is when the first operand does, +or may (if it is a macro argument), contain a side effect. Then repeating +the operand in the middle would perform the side effect twice. Omitting +the middle operand uses the value already computed without the undesirable +effects of recomputing it. + +@node Zero-Length, Variable-Length, Conditionals, Extensions +@section Arrays of Length Zero + +Zero-length arrays are allowed in GNU C. They are very useful as the last +element of a structure which is really a header for a variable-length +object: + +@example +struct line @{ + int length; + char contents[0]; +@}; + +@{ + struct line *thisline + = (struct line *) malloc (sizeof (struct line) + this_length); + thisline->length = this_length; +@} +@end example + +In standard C, you would have to give @code{contents} a length of 1, which +means either you waste space or complicate the argument to @code{malloc}. + +@node Variable-Length, Subscripting, Zero-Length, Extensions +@section Arrays of Variable Length + +Variable-length automatic arrays are allowed in GNU C. These arrays are +declared like any other automatic arrays, but with a length that is not a +constant expression. The storage is allocated at that time and +deallocated when the brace-level is exited. For example: + +@example +FILE *concat_fopen (char *s1, char *s2, char *mode) +@{ + char str[strlen (s1) + strlen (s2) + 1]; + strcpy (str, s1); + strcat (str, s2); + return fopen (str, mode); +@} +@end example + +You can also use variable-length arrays as arguments to functions: + +@example +struct entry +tester (int len, char data[len]) +@{ + @dots{} +@} +@end example + +The length of an array is computed on entry to the brace-level where the +array is declared and is remembered for the scope of the array in case you +access it with @code{sizeof}. + +Jumping or breaking out of the scope of the array name will also deallocate +the storage. Jumping into the scope is not allowed; you will get an error +message for it. + +You can use the function @code{alloca} to get an effect much like +variable-length arrays. The function @code{alloca} is available in +many other C implementations (but not in all). On the other hand, +variable-length arrays are more elegant. + +There are other differences between these two methods. Space allocated +with @code{alloca} exists until the containing @emph{function} returns. +The space for a variable-length array is deallocated as soon as the array +name's scope ends. (If you use both variable-length arrays and +@code{alloca} in the same function, deallocation of a variable-length array +will also deallocate anything more recently allocated with @code{alloca}.) + +@node Subscripting, Pointer Arith, Variable-Length, Extensions +@section Non-Lvalue Arrays May Have Subscripts + +Subscripting is allowed on arrays that are not lvalues, even though the +unary @samp{&} operator is not. For example, this is valid in GNU C though +not valid in other C dialects: + +@example +struct foo @{int a[4];@}; + +struct foo f(); + +bar (int index) +@{ + return f().a[index]; +@} +@end example + +@node Pointer Arith, Initializers, Subscripting, Extensions +@section Arithmetic on @code{void}-Pointers and Function Pointers + +In GNU C, addition and subtraction operations are supported on pointers to +@code{void} and on pointers to functions. This is done by treating the +size of a @code{void} or of a function as 1. + +A consequence of this is that @code{sizeof} is also allowed on @code{void} +and on function types, and returns 1. + +The option @samp{-Wpointer-arith} requests a warning if these extensions +are used. + +@node Initializers, Constructors, Pointer Arith, Extensions +@section Non-Constant Initializers + +The elements of an aggregate initializer for an automatic variable are +not required to be constant expressions in GNU C. Here is an example of +an initializer with run-time varying elements: + +@example +foo (float f, float g) +@{ + float beat_freqs[2] = @{ f-g, f+g @}; + @dots{} +@} +@end example + +@node Constructors, Function Attributes, Initializers, Extensions +@section Constructor Expressions + +GNU C supports constructor expressions. A constructor looks like a cast +containing an initializer. Its value is an object of the type specified in +the cast, containing the elements specified in the initializer. The type +must be a structure, union or array type. + +Assume that @code{struct foo} and @code{structure} are declared as shown: + +@example +struct foo @{int a; char b[2];@} structure; +@end example + +@noindent +Here is an example of constructing a @code{struct foo} with a constructor: + +@example +structure = ((struct foo) @{x + y, 'a', 0@}); +@end example + +@noindent +This is equivalent to writing the following: + +@example +@{ + struct foo temp = @{x + y, 'a', 0@}; + structure = temp; +@} +@end example + +You can also construct an array. If all the elements of the constructor +are (made up of) simple constant expressions, suitable for use in +initializers, then the constructor is an lvalue and can be coerced to a +pointer to its first element, as shown here: + +@example +char **foo = (char *[]) @{ "x", "y", "z" @}; +@end example + +Array constructors whose elements are not simple constants are not very +useful, because the constructor is not an lvalue. There are only two valid +ways to use it: to subscript it, or initialize an array variable with it. +The former is probably slower than a @code{switch} statement, while the +latter does the same thing an ordinary C initializer would do. + +@example +output = ((int[]) @{ 2, x, 28 @}) [input]; +@end example + +@node Function Attributes, Dollar Signs, Constructors, Extensions +@section Declaring Attributes of Functions + +In GNU C, you declare certain things about functions called in your program +which help the compiler optimize function calls. + +A few functions, such as @code{abort} and @code{exit}, cannot return. +These functions should be declared @code{volatile}. For example, + +@example +extern volatile void abort (); +@end example + +@noindent +tells the compiler that it can assume that @code{abort} will not return. +This makes slightly better code, but more importantly it helps avoid +spurious warnings of uninitialized variables. + +Many functions do not examine any values except their arguments, and +have no effects except the return value. Such a function can be subject +to common subexpression elimination and loop optimization just as an +arithmetic operator would be. These functions should be declared +@code{const}. For example, + +@example +extern const void square (); +@end example + +@noindent +says that the hypothetical function @code{square} is safe to call +fewer times than the program says. + +Note that a function that has pointer arguments and examines the data +pointed to must @emph{not} be declared @code{const}. Likewise, a +function that calls a non-@code{const} function usually must not be +@code{const}. + +Some people object to this feature, claiming that ANSI C's @code{#pragma} +should be used instead. There are two reasons I did not do this. + +@enumerate +@item +It is impossible to generate @code{#pragma} commands from a macro. + +@item +The @code{#pragma} command is just as likely as these keywords to mean +something else in another compiler. +@end enumerate + +These two reasons apply to @emph{any} application whatever: as far as +I can see, @code{#pragma} is never useful. + +@node Dollar Signs, Alignment, Function Attributes, Extensions +@section Dollar Signs in Identifier Names + +In GNU C, you may use dollar signs in identifier names. This is because +many traditional C implementations allow such identifiers. + +Dollar signs are allowed if you specify @samp{-traditional}; they are +not allowed if you specify @samp{-ansi}. Whether they are allowed by +default depends on the target machine; usually, they are not. + +@node Alignment, Inline, Dollar Signs, Extensions +@section Inquiring about the Alignment of a Type or Variable + +The keyword @code{__alignof__} allows you to inquire about how an object +is aligned, or the minimum alignment usually required by a type. Its +syntax is just like @code{sizeof}. + +For example, if the target machine requires a @code{double} value to be +aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. +This is true on many RISC machines. On more traditional machine +designs, @code{__alignof__ (double)} is 4 or even 2. + +Some machines never actually require alignment; they allow reference to any +data type even at an odd addresses. For these machines, @code{__alignof__} +reports the @emph{recommended} alignment of a type. + +When the operand of @code{__alignof__} is an lvalue rather than a type, the +value is the largest alignment that the lvalue is known to have. It may +have this alignment as a result of its data type, or because it is part of +a structure and inherits alignment from that structure. For example, after +this declaration: + +@example +struct foo @{ int x; char y; @} foo1; +@end example + +@noindent +the value of @code{__alignof__ (foo1.y)} is probably 2 or 4, the same as +@code{__alignof__ (int)}, even though the data type of @code{foo1.y} +does not itself demand any alignment.@refill + +@node Inline, Extended Asm, Alignment, Extensions +@section An Inline Function is As Fast As a Macro + +By declaring a function @code{inline}, you can direct GNU CC to integrate +that function's code into the code for its callers. This makes execution +faster by eliminating the function-call overhead; in addition, if any of +the actual argument values are constant, their known values may permit +simplifications at compile time so that not all of the inline function's +code needs to be included. + +To declare a function inline, use the @code{inline} keyword in its +declaration, like this: + +@example +inline int +inc (int *a) +@{ + (*a)++; +@} +@end example + +(If you are writing a header file to be included in ANSI C programs, write +@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.) + +You can also make all ``simple enough'' functions inline with the option +@samp{-finline-functions}. Note that certain usages in a function +definition can make it unsuitable for inline substitution. + +When a function is both inline and @code{static}, if all calls to the +function are integrated into the caller, and the function's address is +never used, then the function's own assembler code is never referenced. +In this case, GNU CC does not actually output assembler code for the +function, unless you specify the option @samp{-fkeep-inline-functions}. +Some calls cannot be integrated for various reasons (in particular, +calls that precede the function's definition cannot be integrated, and +neither can recursive calls within the definition). If there is a +nonintegrated call, then the function is compiled to assembler code as +usual. The function must also be compiled as usual if the program +refers to its address, because that can't be inlined. + +When an inline function is not @code{static}, then the compiler must assume +that there may be calls from other source files; since a global symbol can +be defined only once in any program, the function must not be defined in +the other source files, so the calls therein cannot be integrated. +Therefore, a non-@code{static} inline function is always compiled on its +own in the usual fashion. + +If you specify both @code{inline} and @code{extern} in the function +definition, then the definition is used only for inlining. In no case +is the function compiled on its own, not even if you refer to its +address explicitly. Such an address becomes an external reference, as +if you had only declared the function, and had not defined it. + +This combination of @code{inline} and @code{extern} has almost the +effect of a macro. The way to use it is to put a function definition in +a header file with these keywords, and put another copy of the +definition (lacking @code{inline} and @code{extern}) in a library file. +The definition in the header file will cause most calls to the function +to be inlined. If any uses of the function remain, they will refer to +the single copy in the library. + +@node Extended Asm, Asm Labels, Inline, Extensions +@section Assembler Instructions with C Expression Operands + +In an assembler instruction using @code{asm}, you can now specify the +operands of the instruction using C expressions. This means no more +guessing which registers or memory locations will contain the data you want +to use. + +You must specify an assembler instruction template much like what appears +in a machine description, plus an operand constraint string for each +operand. + +For example, here is how to use the 68881's @code{fsinx} instruction: + +@example +asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); +@end example + +@noindent +Here @code{angle} is the C expression for the input operand while +@code{result} is that of the output operand. Each has @samp{"f"} as its +operand constraint, saying that a floating-point register is required. The +@samp{=} in @samp{=f} indicates that the operand is an output; all output +operands' constraints must use @samp{=}. The constraints use the same +language used in the machine description (@pxref{Constraints}). + +Each operand is described by an operand-constraint string followed by the C +expression in parentheses. A colon separates the assembler template from +the first output operand, and another separates the last output operand +from the first input, if any. Commas separate output operands and separate +inputs. The total number of operands is limited to the maximum number of +operands in any instruction pattern in the machine description. + +If there are no output operands, and there are input operands, then there +must be two consecutive colons surrounding the place where the output +operands would go. + +Output operand expressions must be lvalues; the compiler can check this. +The input operands need not be lvalues. The compiler cannot check whether +the operands have data types that are reasonable for the instruction being +executed. It does not parse the assembler instruction template and does +not know what it means, or whether it is valid assembler input. The +extended @code{asm} feature is most often used for machine instructions +that the compiler itself does not know exist. + +The output operands must be write-only; GNU CC will assume that the values +in these operands before the instruction are dead and need not be +generated. Extended asm does not support input-output or read-write +operands. For this reason, the constraint character @samp{+}, which +indicates such an operand, may not be used. + +When the assembler instruction has a read-write operand, or an operand +in which only some of the bits are to be changed, you must logically +split its function into two separate operands, one input operand and one +write-only output operand. The connection between them is expressed by +constraints which say they need to be in the same location when the +instruction executes. You can use the same C expression for both +operands, or different expressions. For example, here we write the +(fictitious) @samp{combine} instruction with @code{bar} as its read-only +source operand and @code{foo} as its read-write destination: + +@example +asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); +@end example + +@noindent +The constraint @samp{"0"} for operand 1 says that it must occupy the same +location as operand 0. A digit in constraint is allowed only in an input +operand, and it must refer to an output operand. + +Only a digit in the constraint can guarantee that one operand will be in +the same place as another. The mere fact that @code{foo} is the value of +both operands is not enough to guarantee that they will be in the same +place in the generated assembler code. The following would not work: + +@example +asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); +@end example + +Various optimizations or reloading could cause operands 0 and 1 to be in +different registers; GNU CC knows no reason not to do so. For example, the +compiler might find a copy of the value of @code{foo} in one register and +use it for operand 1, but generate the output operand 0 in a different +register (copying it afterward to @code{foo}'s own address). Of course, +since the register for operand 1 is not even mentioned in the assembler +code, the result will not work, but GNU CC can't tell that. + +Unless an output operand has the @samp{&} constraint modifier, GNU CC may +allocate it in the same register as an unrelated input operand, on the +assumption that the inputs are consumed before the outputs are produced. +This assumption may be false if the assembler code actually consists of +more than one instruction. In such a case, use @samp{&} for each output +operand that may not overlap an input. @xref{Modifiers}. + +Some instructions clobber specific hard registers. To describe this, write +a third colon after the input operands, followed by the names of the +clobbered hard registers (given as strings). Here is a realistic example +for the vax: + +@example +asm volatile ("movc3 %0,%1,%2" + : /* no outputs */ + : "g" (from), "g" (to), "g" (count) + : "r0", "r1", "r2", "r3", "r4", "r5"); +@end example + +You can put multiple assembler instructions together in a single @code{asm} +template, separated either with newlines (written as @samp{\n}) or with +semicolons if the assembler allows such semicolons. The GNU assembler +allows semicolons and all Unix assemblers seem to do so. The input +operands are guaranteed not to use any of the clobbered registers, and +neither will the output operands' addresses, so you can read and write the +clobbered registers as many times as you like. Here is an example of +multiple instructions in a template; it assumes that the subroutine +@code{_foo} accepts arguments in registers 9 and 10: + +@example +asm ("movl %0,r9;movl %1,r10;call _foo" + : /* no outputs */ + : "g" (from), "g" (to) + : "r9", "r10"); +@end example + +If you want to test the condition code produced by an assembler instruction, +you must include a branch and a label in the @code{asm} construct, as follows: + +@example +asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:" + : "g" (result) + : "g" (input)); +@end example + +@noindent +This assumes your assembler supports local labels, as the GNU assembler +and most Unix assemblers do. + +Usually the most convenient way to use these @code{asm} instructions is to +encapsulate them in macros that look like functions. For example, + +@example +#define sin(x) \ +(@{ double __value, __arg = (x); \ + asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ + __value; @}) +@end example + +@noindent +Here the variable @code{__arg} is used to make sure that the instruction +operates on a proper @code{double} value, and to accept only those +arguments @code{x} which can convert automatically to a @code{double}. + +Another way to make sure the instruction operates on the correct data type +is to use a cast in the @code{asm}. This is different from using a +variable @code{__arg} in that it converts more different types. For +example, if the desired type were @code{int}, casting the argument to +@code{int} would accept a pointer with no complaint, while assigning the +argument to an @code{int} variable named @code{__arg} would warn about +using a pointer unless the caller explicitly casts it. + +If an @code{asm} has output operands, GNU CC assumes for optimization +purposes that the instruction has no side effects except to change the +output operands. This does not mean that instructions with a side effect +cannot be used, but you must be careful, because the compiler may eliminate +them if the output operands aren't used, or move them out of loops, or +replace two with one if they constitute a common subexpression. Also, if +your instruction does have a side effect on a variable that otherwise +appears not to change, the old value of the variable may be reused later if +it happens to be found in a register. + +You can prevent an @code{asm} instruction from being deleted, moved or +combined by writing the keyword @code{volatile} after the @code{asm}. For +example: + +@example +#define set_priority(x) \ +asm volatile ("set_priority %0": /* no outputs */ : "g" (x)) +@end example + +@noindent +(However, an instruction without output operands will not be deleted +or moved, regardless, unless it is unreachable.) + +It is a natural idea to look for a way to give access to the condition +code left by the assembler instruction. However, when we attempted to +implement this, we found no way to make it work reliably. The problem +is that output operands might need reloading, which would result in +additional following ``store'' instructions. On most machines, these +instructions would alter the condition code before there was time to +test it. This problem doesn't arise for ordinary ``test'' and +``compare'' instructions because they don't have any output operands. + +If you are writing a header file that should be includable in ANSI C +programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate +Keywords}. + +@node Asm Labels, Explicit Reg Vars, Extended Asm, Extensions +@section Controlling Names Used in Assembler Code + +You can specify the name to be used in the assembler code for a C +function or variable by writing the @code{asm} (or @code{__asm__}) +keyword after the declarator as follows: + +@example +int foo asm ("myfoo") = 2; +@end example + +@noindent +This specifies that the name to be used for the variable @code{foo} in +the assembler code should be @samp{myfoo} rather than the usual +@samp{_foo}. + +On systems where an underscore is normally prepended to the name of a C +function or variable, this feature allows you to define names for the +linker that do not start with an underscore. + +You cannot use @code{asm} in this way in a function @emph{definition}; but +you can get the same effect by writing a declaration for the function +before its definition and putting @code{asm} there, like this: + +@example +extern func () asm ("FUNC"); + +func (x, y) + int x, y; +@dots{} +@end example + +It is up to you to make sure that the assembler names you choose do not +conflict with any other assembler symbols. Also, you must not use a +register name; that would produce completely invalid assembler code. GNU +CC does not as yet have the ability to store static variables in registers. +Perhaps that will be added. + +@node Explicit Reg Vars, Alternate Keywords, Asm Labels, Extensions +@section Variables in Specified Registers + +GNU C allows you to put a few global variables into specified hardware +registers. You can also specify the register in which an ordinary +register variable should be allocated. + +@itemize @bullet +@item +Global register variables reserve registers throughout the program. +This may be useful in programs such as programming language +interpreters which have a couple of global variables that are accessed +very often. + +@item +Local register variables in specific registers do not reserve the +registers. The compiler's data flow analysis is capable of +determining where the specified registers contain live values, and +where they are available for other uses. These local variables are +sometimes convenient for use with the extended @code{asm} feature +(@pxref{Extended Asm}). +@end itemize + +@menu +* Global Reg Vars:: +* Local Reg Vars:: +@end menu + +@node Global Reg Vars, Local Reg Vars, Explicit Reg Vars, Explicit Reg Vars +@subsection Defining Global Register Variables + +You can define a global register variable in GNU C like this: + +@example +register int *foo asm ("a5"); +@end example + +@noindent +Here @code{a5} is the name of the register which should be used. Choose a +register which is normally saved and restored by function calls on your +machine, so that library routines will not clobber it. + +Naturally the register name is cpu-dependent, so you would need to +conditionalize your program according to cpu type. The register +@code{a5} would be a good choice on a 68000 for a variable of pointer +type. On machines with register windows, be sure to choose a ``global'' +register that is not affected magically by the function call mechanism. + +In addition, operating systems on one type of cpu may differ in how they +name the registers; then you would need additional conditionals. For +example, some 68000 operating systems call this register @code{%a5}. + +Eventually there may be a way of asking the compiler to choose a register +automatically, but first we need to figure out how it should choose and +how to enable you to guide the choice. No solution is evident. + +Defining a global register variable in a certain register reserves that +register entirely for this use, at least within the current compilation. +The register will not be allocated for any other purpose in the functions +in the current compilation. The register will not be saved and restored by +these functions. Stores into this register are never deleted even if they +would appear to be dead, but references may be deleted or moved or +simplified. + +It is not safe to access the global register variables from signal +handlers, or from more than one thread of control, because the system +library routines may temporarily use the register for other things (unless +you recompile them specially for the task at hand). + +It is not safe for one function that uses a global register variable to +call another such function @code{foo} by way of a third function +@code{lose} that was compiled without knowledge of this variable (i.e. in a +different source file in which the variable wasn't declared). This is +because @code{lose} might save the register and put some other value there. +For example, you can't expect a global register variable to be available in +the comparison-function that you pass to @code{qsort}, since @code{qsort} +might have put something else in that register. (If you are prepared to +recompile @code{qsort} with the same global register variable, you can +solve this problem.) + +If you want to recompile @code{qsort} or other source files which do not +actually use your global register variable, so that they will not use that +register for any other purpose, then it suffices to specify the compiler +option @samp{-ffixed-@var{reg}}. You need not actually add a global +register declaration to their source code. + +A function which can alter the value of a global register variable cannot +safely be called from a function compiled without this variable, because it +could clobber the value the caller expects to find there on return. +Therefore, the function which is the entry point into the part of the +program that uses the global register variable must explicitly save and +restore the value which belongs to its caller. + +On most machines, @code{longjmp} will restore to each global register +variable the value it had at the time of the @code{setjmp}. On some +machines, however, @code{longjmp} will not change the value of global +register variables. To be portable, the function that called @code{setjmp} +should make other arrangements to save the values of the global register +variables, and to restore them in a @code{longjmp}. This way, the same +thing will happen regardless of what @code{longjmp} does. + +All global register variable declarations must precede all function +definitions. If such a declaration could appear after function +definitions, the declaration would be too late to prevent the register from +being used for other purposes in the preceding functions. + +Global register variables may not have initial values, because an +executable file has no means to supply initial contents for a register. + +@node Local Reg Vars,, Global Reg Vars, Explicit Reg Vars +@subsection Specifying Registers for Local Variables + +You can define a local register variable with a specified register +like this: + +@example +register int *foo asm ("a5"); +@end example + +@noindent +Here @code{a5} is the name of the register which should be used. Note +that this is the same syntax used for defining global register +variables, but for a local variable it would appear within a function. + +Naturally the register name is cpu-dependent, but this is not a +problem, since specific registers are most often useful with explicit +assembler instructions (@pxref{Extended Asm}). Both of these things +generally require that you conditionalize your program according to +cpu type. + +In addition, operating systems on one type of cpu may differ in how they +name the registers; then you would need additional conditionals. For +example, some 68000 operating systems call this register @code{%a5}. + +Eventually there may be a way of asking the compiler to choose a register +automatically, but first we need to figure out how it should choose and +how to enable you to guide the choice. No solution is evident. + +Defining such a register variable does not reserve the register; it +remains available for other uses in places where flow control determines +the variable's value is not live. However, these registers are made +unavailable for use in the reload pass. I would not be surprised if +excessive use of this feature leaves the compiler too few available +registers to compile certain functions. + +@node Alternate Keywords,, Explicit Reg Vars, Extensions +@section Alternate Keywords + +The option @samp{-traditional} disables certain keywords; @samp{-ansi} +disables certain others. This causes trouble when you want to use GNU C +extensions, or ANSI C features, in a general-purpose header file that +should be usable by all programs, including ANSI C programs and traditional +ones. The keywords @code{asm}, @code{typeof} and @code{inline} cannot be +used since they won't work in a program compiled with @samp{-ansi}, while +the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof} +and @code{inline} won't work in a program compiled with +@samp{-traditional}.@refill + +The way to solve these problems is to put @samp{__} at the beginning and +end of each problematical keyword. For example, use @code{__asm__} +instead of @code{asm}, @code{__const__} instead of @code{const}, and +@code{__inline__} instead of @code{inline}. + +Other C compilers won't accept these alternative keywords; if you want to +compile with another compiler, you can define the alternate keywords as +macros to replace them with the customary keywords. It looks like this: + +@example +#ifndef __GNUC__ +#define __asm__ asm +#endif +@end example + +@node Bugs, Portability, Extensions, Top +@chapter Reporting Bugs + +Your bug reports play an essential role in making GNU CC reliable. + +When you encounter a problem, the first thing to do is to see if it is +already known. @xref{Trouble}. Also look in @ref{Incompatibilities}. +If it isn't known, then you should report the problem. + +Reporting a bug may help you by bringing a solution to your problem, or +it may not. (If it does not, look in the service directory; see +@ref{Service}.) In any case, the principal function of a bug report +is to help the entire community by making the next version of GNU CC +work better. Bug reports are your contribution to the maintenance of +GNU CC. + +In order for a bug report to serve its purpose, you must include the +information that makes for fixing the bug. + +@menu +* Criteria: Bug Criteria. Have you really found a bug? +* Reporting: Bug Reporting. How to report a bug effectively. +@end menu + +@node Bug Criteria, Bug Reporting, Bugs, Bugs +@section Have You Found a Bug? + +If you are not sure whether you have found a bug, here are some guidelines: + +@itemize @bullet +@item +If the compiler gets a fatal signal, for any input whatever, that is a +compiler bug. Reliable compilers never crash. + +@item +If the compiler produces invalid assembly code, for any input whatever +(except an @code{asm} statement), that is a compiler bug, unless the +compiler reports errors (not just warnings) which would ordinarily +prevent the assembler from being run. + +@item +If the compiler produces valid assembly code that does not correctly +execute the input source code, that is a compiler bug. + +However, you must double-check to make sure, because you may have run +into an incompatibility between GNU C and traditional C +(@pxref{Incompatibilities}). These incompatibilities might be considered +bugs, but they are inescapable consequences of valuable features. + +Or you may have a program whose behavior is undefined, which happened +by chance to give the desired results with another C compiler. + +For example, in many nonoptimizing compilers, you can write @samp{x;} +at the end of a function instead of @samp{return x;}, with the same +results. But the value of the function is undefined if @code{return} +is omitted; it is not a bug when GNU CC produces different results. + +Problems often result from expressions with two increment operators, +as in @code{f (*p++, *p++)}. Your previous compiler might have +interpreted that expression the way you intended; GNU CC might +interpret it another way. Neither compiler is wrong. The bug is +in your code. + +After you have localized the error to a single source line, it should +be easy to check for these things. If your program is correct and +well defined, you have found a compiler bug. + +@item +If the compiler produces an error message for valid input, that is a +compiler bug. + +Note that the following is not valid input, and the error message for +it is not a bug: + +@example +int foo (char); + +int +foo (x) + char x; +@{ @dots{} @} +@end example + +@noindent +The prototype says to pass a @code{char}, while the definition says to +pass an @code{int} and treat the value as a @code{char}. This is what +the ANSI standard says, and it makes sense. + +@item +If the compiler does not produce an error message for invalid input, +that is a compiler bug. However, you should note that your idea of +``invalid input'' might be my idea of ``an extension'' or ``support +for traditional practice''. + +@item +If you are an experienced user of C compilers, your suggestions +for improvement of GNU CC are welcome in any case. +@end itemize + +@node Bug Reporting,, Bug Criteria, Bugs +@section How to Report Bugs + +Send bug reports for GNU C to one of these addresses: + +@example +bug-gcc@@prep.ai.mit.edu +@{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gcc +@end example + +@strong{Do not send bug reports to @samp{help-gcc}, or to the newsgroup +@samp{gnu.gcc.help}.} Most users of GNU CC do not want to receive bug +reports. Those that do, have asked to be on @samp{bug-gcc}. + +The mailing list @samp{bug-gcc} has a newsgroup which serves as a +repeater. The mailing list and the newsgroup carry exactly the same +messages. Often people think of posting bug reports to the newsgroup +instead of mailing them. This appears to work, but it has one problem +which can be crucial: a newsgroup posting does not contain a mail path +back to the sender. Thus, if I need to ask for more information, I +may be unable to reach you. For this reason, it is better to send bug +reports to the mailing list. + +As a last resort, send bug reports on paper to: + +@example +GNU Compiler Bugs +Free Software Foundation +675 Mass Ave +Cambridge, MA 02139 +@end example + +The fundamental principle of reporting bugs usefully is this: +@strong{report all the facts}. If you are not sure whether to state a +fact or leave it out, state it! + +Often people omit facts because they think they know what causes the +problem and they conclude that some details don't matter. Thus, you might +assume that the name of the variable you use in an example does not matter. +Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a +stray memory reference which happens to fetch from the location where that +name is stored in memory; perhaps, if the name were different, the contents +of that location would fool the compiler into doing the right thing despite +the bug. Play it safe and give a specific, complete example. That is the +easiest thing for you to do, and the most helpful. + +Keep in mind that the purpose of a bug report is to enable me to fix +the bug if it is not known. It isn't very important what happens if +the bug is already known. Therefore, always write your bug reports on +the assumption that the bug is not known. + +Sometimes people give a few sketchy facts and ask, ``Does this ring a +bell?'' Those bug reports are useless, and I urge everyone to +@emph{refuse to respond to them} except to chide the sender to report +bugs properly. + +To enable me to fix the bug, you should include all these things: + +@itemize @bullet +@item +The version of GNU CC. You can get this by running it with the +@samp{-v} option. + +Without this, I won't know whether there is any point in looking for +the bug in the current version of GNU CC. + +@item +A complete input file that will reproduce the bug. If the bug is in +the C preprocessor, send me a source file and any header files that it +requires. If the bug is in the compiler proper (@file{cc1}), run your +source file through the C preprocessor by doing @samp{gcc -E +@var{sourcefile} > @var{outfile}}, then include the contents of +@var{outfile} in the bug report. (Any @samp{-I}, @samp{-D} or +@samp{-U} options that you used in actual compilation should also be +used when doing this.) + +A single statement is not enough of an example. In order to compile +it, it must be embedded in a function definition; and the bug might +depend on the details of how this is done. + +Without a real example I can compile, all I can do about your bug +report is wish you luck. It would be futile to try to guess how to +provoke the bug. For example, bugs in register allocation and +reloading frequently depend on every little detail of the function +they happen in. + +@item +The command arguments you gave GNU CC to compile that example and +observe the bug. For example, did you use @samp{-O}? To guarantee +you won't omit something important, list them all. + +If I were to try to guess the arguments, I would probably guess wrong +and then I would not encounter the bug. + +@item +The names of the files that you used for @file{tm.h} and @file{md} +when you installed the compiler. + +@item +The type of machine you are using, and the operating system name and +version number. + +@item +A description of what behavior you observe that you believe is +incorrect. For example, ``It gets a fatal signal,'' or, ``There is an +incorrect assembler instruction in the output.'' + +Of course, if the bug is that the compiler gets a fatal signal, then I +will certainly notice it. But if the bug is incorrect output, I might +not notice unless it is glaringly wrong. I won't study all the +assembler code from a 50-line C program just on the off chance that it +might be wrong. + +Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, +your copy of the compiler is out of synch, or you have encountered a +bug in the C library on your system. (This has happened!) Your copy +might crash and mine would not. If you @i{told} me to expect a crash, +then when mine fails to crash, I would know that the bug was not +happening for me. If you had not told me to expect a crash, then I +would not be able to draw any conclusion from my observations. + +Often the observed symptom is incorrect output when your program is run. +Sad to say, this is not enough information for me unless the program is +short and simple. If you send me a large program, I don't have time to +figure out how it would work if compiled correctly, much less which line +of it was compiled wrong. So you will have to do that. Tell me which +source line it is, and what incorrect result happens when that line is +executed. A person who understands the test program can find this as +easily as a bug in the program itself. + +@item +If you send me examples of output from GNU CC, please use @samp{-g} +when you make them. The debugging information includes source line +numbers which are essential for correlating the output with the input. + +@item +If you wish to suggest changes to the GNU CC source, send me context +diffs. If you even discuss something in the GNU CC source, refer to +it by context, not by line number. + +The line numbers in my development sources don't match those in your +sources. Your line numbers would convey no useful information to me. + +@item +Additional information from a debugger might enable me to find +a problem on a machine which I do not have available myself. +However, you need to think when you collect this information if +you want it to have any chance of being useful. + +For example, many people send just a backtrace, but that is never +useful by itself. A simple backtrace with arguments conveys little +about GNU CC because the compiler is largely data-driven; the same +functions are called over and over for different RTL insns, doing +different things depending on the details of the insn. + +Most of the arguments listed in the backtrace are useless because they +are pointers to RTL list structure. The numeric values of the +pointers, which the debugger prints in the backtrace, have no +significance whatever; all that matters is the contents of the objects +they point to (and most of the contents are other such pointers). + +In addition, most compiler passes consist of one or more loops that +scan the RTL insn sequence. The most vital piece of information about +such a loop---which insn it has reached---is usually in a local variable, +not in an argument. + +What you need to provide in addition to a backtrace are the values of +the local variables for several stack frames up. When a local +variable or an argument is an RTX, first print its value and then use +the GDB command @code{pr} to print the RTL expression that it points +to. (If GDB doesn't run on your machine, use your debugger to call +the function @code{debug_rtx} with the RTX as an argument.) In +general, whenever a variable is a pointer, its value is no use +without the data it points to. + +In addition, include a debugging dump from just before the pass +in which the crash happens. Most bugs involve a series of insns, +not just one. +@end itemize + +Here are some things that are not necessary: + +@itemize @bullet +@item +A description of the envelope of the bug. + +Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. + +This is often time consuming and not very useful, because the way I +will find the bug is by running a single example under the debugger +with breakpoints, not by pure deduction from a series of examples. +I recommend that you save your time for something else. + +Of course, if you can find a simpler example to report @emph{instead} +of the original one, that is a convenience for me. Errors in the +output will be easier to spot, running under the debugger will take +less time, etc. Most GNU CC bugs involve just one function, so the +most straightforward way to simplify an example is to delete all the +function definitions except the one where the bug occurs. Those +earlier in the file may be replaced by external declarations if the +crucial function depends on them. (Exception: inline functions may +affect compilation of functions defined later in the file.) + +However, simplification is not vital; if you don't want to do this, +report the bug anyway and send me the entire test case you used. + +@item +A patch for the bug. + +A patch for the bug does help me if it is a good one. But don't omit +the necessary information, such as the test case, on the assumption that +a patch is all I need. I might see problems with your patch and decide +to fix the problem another way, or I might not understand it at all. + +Sometimes with a program as complicated as GNU CC it is very hard to +construct an example that will make the program follow a certain path +through the code. If you don't send me the example, I won't be able +to construct one, so I won't be able to verify that the bug is fixed. + +And if I can't understand what bug you are trying to fix, or why your +patch should be an improvement, I won't install it. A test case will +help me to understand. + +@item +A guess about what the bug is or what it depends on. + +Such guesses are usually wrong. Even I can't guess right about such +things without first using the debugger to find the facts. +@end itemize + +@node Portability, Interface, Bugs, Top +@chapter GNU CC and Portability + +The main goal of GNU CC was to make a good, fast compiler for machines in +the class that the GNU system aims to run on: 32-bit machines that address +8-bit bytes and have several general registers. Elegance, theoretical +power and simplicity are only secondary. + +GNU CC gets most of the information about the target machine from a machine +description which gives an algebraic formula for each of the machine's +instructions. This is a very clean way to describe the target. But when +the compiler needs information that is difficult to express in this +fashion, I have not hesitated to define an ad-hoc parameter to the machine +description. The purpose of portability is to reduce the total work needed +on the compiler; it was not of interest for its own sake. + +GNU CC does not contain machine dependent code, but it does contain code +that depends on machine parameters such as endianness (whether the most +significant byte has the highest or lowest address of the bytes in a word) +and the availability of autoincrement addressing. In the RTL-generation +pass, it is often necessary to have multiple strategies for generating code +for a particular kind of syntax tree, strategies that are usable for different +combinations of parameters. Often I have not tried to address all possible +cases, but only the common ones or only the ones that I have encountered. +As a result, a new target may require additional strategies. You will know +if this happens because the compiler will call @code{abort}. Fortunately, +the new strategies can be added in a machine-independent fashion, and will +affect only the target machines that need them. + +@node Interface, Passes, Portability, Top +@chapter Interfacing to GNU CC Output + +GNU CC is normally configured to use the same function calling convention +normally in use on the target system. This is done with the +machine-description macros described (@pxref{Machine Macros}). + +However, returning of structure and union values is done differently on +some target machines. As a result, functions compiled with PCC +returning such types cannot be called from code compiled with GNU CC, +and vice versa. This does not cause trouble often because few Unix +library routines return structures or unions. + +GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes +long in the same registers used for @code{int} or @code{double} return +values. (GNU CC typically allocates variables of such types in +registers also.) Structures and unions of other sizes are returned by +storing them into an address passed by the caller (usually in a +register). The machine-description macros @code{STRUCT_VALUE} and +@code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address. + +By contrast, PCC on most target machines returns structures and unions +of any size by copying the data into an area of static storage, and then +returning the address of that storage as if it were a pointer value. +The caller must copy the data from that memory area to the place where +the value is wanted. This is slower than the method used by GNU CC, and +fails to be reentrant. + +On some target machines, such as RISC machines and the 80386, the +standard system convention is to pass to the subroutine the address of +where to return the value. On these machines, GNU CC has been +configured to be compatible with the standard compiler, when this method +is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes. + +GNU CC uses the system's standard convention for passing arguments. On +some machines, the first few arguments are passed in registers; in +others, all are passed on the stack. It would be possible to use +registers for argument passing on any machine, and this would probably +result in a significant speedup. But the result would be complete +incompatibility with code that follows the standard convention. So this +change is practical only if you are switching to GNU CC as the sole C +compiler for the system. We may implement register argument passing on +certain machines once we have a complete GNU system so that we can +compile the libraries with GNU CC. + +If you use @code{longjmp}, beware of automatic variables. ANSI C says that +automatic variables that are not declared @code{volatile} have undefined +values after a @code{longjmp}. And this is all GNU CC promises to do, +because it is very difficult to restore register variables correctly, and +one of GNU CC's features is that it can put variables in registers without +your asking it to. + +If you want a variable to be unaltered by @code{longjmp}, and you don't +want to write @code{volatile} because old C compilers don't accept it, +just take the address of the variable. If a variable's address is ever +taken, even if just to compute it and ignore it, then the variable cannot +go in a register: + +@example +@{ + int careful; + &careful; + @dots{} +@} +@end example + +Code compiled with GNU CC may call certain library routines. Most of +them handle arithmetic for which there are no instructions. This +includes multiply and divide on some machines, and floating point +operations on any machine for which floating point support is disabled +with @samp{-msoft-float}. Some standard parts of the C library, such as +@code{bcopy} or @code{memcpy}, are also called automatically. The usual +function call interface is used for calling the library routines. + +These library routines should be defined in the library @file{gnulib}, +which GNU CC automatically searches whenever it links a program. On +machines that have multiply and divide instructions, if hardware +floating point is in use, normally @file{gnulib} is not needed, but it +is searched just in case. + +Each arithmetic function is defined in @file{gnulib.c} to use the +corresponding C arithmetic operator. As long as the file is compiled +with another C compiler, which supports all the C arithmetic operators, +this file will work portably. However, @file{gnulib.c} does not work if +compiled with GNU CC, because each arithmetic function would compile +into a call to itself! + +@node Passes, RTL, Interface, Top +@chapter Passes and Files of the Compiler + +The overall control structure of the compiler is in @file{toplev.c}. This +file is responsible for initialization, decoding arguments, opening and +closing files, and sequencing the passes. + +The parsing pass is invoked only once, to parse the entire input. The RTL +intermediate code for a function is generated as the function is parsed, a +statement at a time. Each statement is read in as a syntax tree and then +converted to RTL; then the storage for the tree for the statement is +reclaimed. Storage for types (and the expressions for their sizes), +declarations, and a representation of the binding contours and how they nest, +remains until the function is finished being compiled; these are all needed +to output the debugging information. + +Each time the parsing pass reads a complete function definition or +top-level declaration, it calls the function +@code{rest_of_compilation} or @code{rest_of_decl_compilation} in +@file{toplev.c}, which are responsible for all further processing +necessary, ending with output of the assembler language. All other +compiler passes run, in sequence, within @code{rest_of_compilation}. +When that function returns from compiling a function definition, the +storage used for that function definition's compilation is entirely +freed, unless it is an inline function (@pxref{Inline}). + +Here is a list of all the passes of the compiler and their source files. +Also included is a description of where debugging dumps can be requested +with @samp{-d} options. + +@itemize @bullet +@item +Parsing. This pass reads the entire text of a function definition, +constructing partial syntax trees. This and RTL generation are no longer +truly separate passes (formerly they were), but it is easier to think +of them as separate. + +The tree representation does not entirely follow C syntax, because it is +intended to support other languages as well. + +C data type analysis is also done in this pass, and every tree node +that represents an expression has a data type attached. Variables are +represented as declaration nodes. + +Constant folding and associative-law simplifications are also done +during this pass. + +The source files for parsing are @file{c-parse.y}, @file{c-decl.c}, +@file{c-typeck.c}, @file{c-convert.c}, @file{stor-layout.c}, +@file{fold-const.c}, and @file{tree.c}. The last three files are +intended to be language-independent. There are also header files +@file{c-parse.h}, @file{c-tree.h}, @file{tree.h} and @file{tree.def}. +The last two define the format of the tree representation.@refill + +@item +RTL generation. This is the conversion of syntax tree into RTL code. +It is actually done statement-by-statement during parsing, but for +most purposes it can be thought of as a separate pass. + +This is where the bulk of target-parameter-dependent code is found, +since often it is necessary for strategies to apply only when certain +standard kinds of instructions are available. The purpose of named +instruction patterns is to provide this information to the RTL +generation pass. + +Optimization is done in this pass for @code{if}-conditions that are +comparisons, boolean operations or conditional expressions. Tail +recursion is detected at this time also. Decisions are made about how +best to arrange loops and how to output @code{switch} statements. + +The source files for RTL generation are @file{stmt.c}, @file{expr.c}, +@file{explow.c}, @file{expmed.c}, @file{optabs.c} and @file{emit-rtl.c}. +Also, the file @file{insn-emit.c}, generated from the machine description +by the program @code{genemit}, is used in this pass. The header files +@file{expr.h} is used for communication within this pass.@refill + +The header files @file{insn-flags.h} and @file{insn-codes.h}, +generated from the machine description by the programs @code{genflags} +and @code{gencodes}, tell this pass which standard names are available +for use and which patterns correspond to them.@refill + +Aside from debugging information output, none of the following passes +refers to the tree structure representation of the function (only +part of which is saved). + +The decision of whether the function can and should be expanded inline +in its subsequent callers is made at the end of rtl generation. The +function must meet certain criteria, currently related to the size of +the function and the types and number of parameters it has. Note that +this function may contain loops, recursive calls to itself +(tail-recursive functions can be inlined!), gotos, in short, all +constructs supported by GNU CC. + +The option @samp{-dr} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.rtl} to +the input file name. + +@item +Jump optimization. This pass simplifies jumps to the following +instruction, jumps across jumps, and jumps to jumps. It deletes +unreferenced labels and unreachable code, except that unreachable code +that contains a loop is not recognized as unreachable in this pass. +(Such loops are deleted later in the basic block analysis.) + +Jump optimization is performed two or three times. The first time is +immediately following RTL generation. The second time is after CSE, +but only if CSE says repeated jump optimization is needed. The +last time is right before the final pass. That time, cross-jumping +and deletion of no-op move instructions are done together with the +optimizations described above. + +The source file of this pass is @file{jump.c}. + +The option @samp{-dj} causes a debugging dump of the RTL code after +this pass is run for the first time. This dump file's name is made by +appending @samp{.jump} to the input file name. + +@item +Register scan. This pass finds the first and last use of each +register, as a guide for common subexpression elimination. Its source +is in @file{regclass.c}. + +@item +Common subexpression elimination. This pass also does constant +propagation. Its source file is @file{cse.c}. If constant +propagation causes conditional jumps to become unconditional or to +become no-ops, jump optimization is run again when CSE is finished. + +The option @samp{-ds} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.cse} to +the input file name. + +@item +Loop optimization. This pass moves constant expressions out of loops, +and optionally does strength-reduction as well. Its source file is +@file{loop.c}. + +The option @samp{-dL} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.loop} to +the input file name. + +@item +Stupid register allocation is performed at this point in a +nonoptimizing compilation. It does a little data flow analysis as +well. When stupid register allocation is in use, the next pass +executed is the reloading pass; the others in between are skipped. +The source file is @file{stupid.c}. + +@item +Data flow analysis (@file{flow.c}). This pass divides the program +into basic blocks (and in the process deletes unreachable loops); then +it computes which pseudo-registers are live at each point in the +program, and makes the first instruction that uses a value point at +the instruction that computed the value. + +This pass also deletes computations whose results are never used, and +combines memory references with add or subtract instructions to make +autoincrement or autodecrement addressing. + +The option @samp{-df} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.flow} to +the input file name. If stupid register allocation is in use, this +dump file reflects the full results of such allocation. + +@item +Instruction combination (@file{combine.c}). This pass attempts to +combine groups of two or three instructions that are related by data +flow into single instructions. It combines the RTL expressions for +the instructions by substitution, simplifies the result using algebra, +and then attempts to match the result against the machine description. + +The option @samp{-dc} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.combine} +to the input file name. + +@item +Register class preferencing. The RTL code is scanned to find out +which register class is best for each pseudo register. The source +file is @file{regclass.c}. + +@item +Local register allocation (@file{local-alloc.c}). This pass allocates +hard registers to pseudo registers that are used only within one basic +block. Because the basic block is linear, it can use fast and +powerful techniques to do a very good job. + +The option @samp{-dl} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.lreg} to +the input file name. + +@item +Global register allocation (@file{global-alloc.c}). This pass +allocates hard registers for the remaining pseudo registers (those +whose life spans are not contained in one basic block). + +@item +Reloading. This pass renumbers pseudo registers with the hardware +registers numbers they were allocated. Pseudo registers that did not +get hard registers are replaced with stack slots. Then it finds +instructions that are invalid because a value has failed to end up in +a register, or has ended up in a register of the wrong kind. It fixes +up these instructions by reloading the problematical values +temporarily into registers. Additional instructions are generated to +do the copying. + +Source files are @file{reload.c} and @file{reload1.c}, plus the header +@file{reload.h} used for communication between them. + +The option @samp{-dg} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.greg} to +the input file name. + +@item +Jump optimization is repeated, this time including cross-jumping +and deletion of no-op move instructions. + +The option @samp{-dJ} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.jump2} +to the input file name. + +@item +Delayed branch scheduling may be done at this point. The source file +name is @file{dbranch.c}. + +The option @samp{-dd} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.dbr} +to the input file name. + +@item +Final. This pass outputs the assembler code for the function. It is +also responsible for identifying spurious test and compare +instructions. Machine-specific peephole optimizations are performed +at the same time. The function entry and exit sequences are generated +directly as assembler code in this pass; they never exist as RTL. + +The source files are @file{final.c} plus @file{insn-output.c}; the +latter is generated automatically from the machine description by the +tool @file{genoutput}. The header file @file{conditions.h} is used +for communication between these files. + +@item +Debugging information output. This is run after final because it must +output the stack slot offsets for pseudo registers that did not get +hard registers. Source files are @file{dbxout.c} for DBX symbol table +format and @file{symout.c} for GDB's own symbol table format. +@end itemize + +Some additional files are used by all or many passes: + +@itemize @bullet +@item +Every pass uses @file{machmode.def}, which defines the machine modes. + +@item +All the passes that work with RTL use the header files @file{rtl.h} +and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools +@code{gen*} also use these files to read and work with the machine +description RTL. + +@item +Several passes refer to the header file @file{insn-config.h} which +contains a few parameters (C macro definitions) generated +automatically from the machine description RTL by the tool +@code{genconfig}. + +@item +Several passes use the instruction recognizer, which consists of +@file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c} +and @file{insn-extract.c} that are generated automatically from the +machine description by the tools @file{genrecog} and +@file{genextract}.@refill + +@item +Several passes use the header files @file{regs.h} which defines the +information recorded about pseudo register usage, and @file{basic-block.h} +which defines the information recorded about basic blocks. + +@item +@file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector +with a bit for each hard register, and some macros to manipulate it. +This type is just @code{int} if the machine has few enough hard registers; +otherwise it is an array of @code{int} and some of the macros expand +into loops. +@end itemize + +@node RTL, Machine Desc, Passes, Top +@chapter RTL Representation + +Most of the work of the compiler is done on an intermediate representation +called register transfer language. In this language, the instructions to be +output are described, pretty much one by one, in an algebraic form that +describes what the instruction does. + +RTL is inspired by Lisp lists. It has both an internal form, made up of +structures that point at other structures, and a textual form that is used +in the machine description and in printed debugging dumps. The textual +form uses nested parentheses to indicate the pointers in the internal form. + +@menu +* RTL Objects:: Expressions vs vectors vs strings vs integers. +* Accessors:: Macros to access expression operands or vector elts. +* Flags:: Other flags in an RTL expression. +* Machine Modes:: Describing the size and format of a datum. +* Constants:: Expressions with constant values. +* Regs and Memory:: Expressions representing register contents or memory. +* Arithmetic:: Expressions representing arithmetic on other expressions. +* Comparisons:: Expressions representing comparison of expressions. +* Bit Fields:: Expressions representing bit-fields in memory or reg. +* Conversions:: Extending, truncating, floating or fixing. +* RTL Declarations:: Declaring volatility, constancy, etc. +* Side Effects:: Expressions for storing in registers, etc. +* Incdec:: Embedded side-effects for autoincrement addressing. +* Assembler:: Representing @code{asm} with operands. +* Insns:: Expression types for entire insns. +* Calls:: RTL representation of function call insns. +* Sharing:: Some expressions are unique; others *must* be copied. +@end menu + +@node RTL Objects, Accessors, RTL, RTL +@section RTL Object Types + +RTL uses four kinds of objects: expressions, integers, strings and vectors. +Expressions are the most important ones. An RTL expression (``RTX'', for +short) is a C structure, but it is usually referred to with a pointer; a +type that is given the typedef name @code{rtx}. + +An integer is simply an @code{int}, and a string is a @code{char *}. +Within RTL code, strings appear only inside @code{symbol_ref} expressions, +but they appear in other contexts in the RTL expressions that make up +machine descriptions. Their written form uses decimal digits. + +A string is a sequence of characters. In core it is represented as a +@code{char *} in usual C fashion, and it is written in C syntax as well. +However, strings in RTL may never be null. If you write an empty string in +a machine description, it is represented in core as a null pointer rather +than as a pointer to a null character. In certain contexts, these null +pointers instead of strings are valid. + +A vector contains an arbitrary, specified number of pointers to +expressions. The number of elements in the vector is explicitly present in +the vector. The written form of a vector consists of square brackets +(@samp{[@dots{}]}) surrounding the elements, in sequence and with +whitespace separating them. Vectors of length zero are not created; null +pointers are used instead. + +Expressions are classified by @dfn{expression codes} (also called RTX +codes). The expression code is a name defined in @file{rtl.def}, which is +also (in upper case) a C enumeration constant. The possible expression +codes and their meanings are machine-independent. The code of an RTX can +be extracted with the macro @code{GET_CODE (@var{x})} and altered with +@code{PUT_CODE (@var{x}, @var{newcode})}. + +The expression code determines how many operands the expression contains, +and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell +by looking at an operand what kind of object it is. Instead, you must know +from its context---from the expression code of the containing expression. +For example, in an expression of code @code{subreg}, the first operand is +to be regarded as an expression and the second operand as an integer. In +an expression of code @code{plus}, there are two operands, both of which +are to be regarded as expressions. In a @code{symbol_ref} expression, +there is one operand, which is to be regarded as a string. + +Expressions are written as parentheses containing the name of the +expression type, its flags and machine mode if any, and then the operands +of the expression (separated by spaces). + +Expression code names in the @samp{md} file are written in lower case, +but when they appear in C code they are written in upper case. In this +manual, they are shown as follows: @code{const_int}. + +In a few contexts a null pointer is valid where an expression is normally +wanted. The written form of this is @code{(nil)}. + +@node Accessors, Flags, RTL Objects, RTL +@section Access to Operands + +For each expression type @file{rtl.def} specifies the number of contained +objects and their kinds, with four possibilities: @samp{e} for expression +(actually a pointer to an expression), @samp{i} for integer, @samp{s} for +string, and @samp{E} for vector of expressions. The sequence of letters +for an expression code is called its @dfn{format}. Thus, the format of +@code{subreg} is @samp{ei}.@refill + +Two other format characters are used occasionally: @samp{u} and @samp{0}. +@samp{u} is equivalent to @samp{e} except that it is printed differently in +debugging dumps, and @samp{0} means a slot whose contents do not fit any +normal category. @samp{0} slots are not printed at all in dumps, and are +often used in special ways by small parts of the compiler.@refill + +There are macros to get the number of operands and the format of an +expression code: + +@table @code +@item GET_RTX_LENGTH (@var{code}) +Number of operands of an RTX of code @var{code}. + +@item GET_RTX_FORMAT (@var{code}) +The format of an RTX of code @var{code}, as a C string. +@end table + +Operands of expressions are accessed using the macros @code{XEXP}, +@code{XINT} and @code{XSTR}. Each of these macros takes two arguments: an +expression-pointer (RTX) and an operand number (counting from zero). +Thus,@refill + +@example +XEXP (@var{x}, 2) +@end example + +@noindent +accesses operand 2 of expression @var{x}, as an expression. + +@example +XINT (@var{x}, 2) +@end example + +@noindent +accesses the same operand as an integer. @code{XSTR}, used in the same +fashion, would access it as a string. + +Any operand can be accessed as an integer, as an expression or as a string. +You must choose the correct method of access for the kind of value actually +stored in the operand. You would do this based on the expression code of +the containing expression. That is also how you would know how many +operands there are. + +For example, if @var{x} is a @code{subreg} expression, you know that it has +two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)} +and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you +would get the address of the expression operand but cast as an integer; +that might occasionally be useful, but it would be cleaner to write +@code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also +compile without error, and would return the second, integer operand cast as +an expression pointer, which would probably result in a crash when +accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either, +but this will access memory past the end of the expression with +unpredictable results.@refill + +Access to operands which are vectors is more complicated. You can use the +macro @code{XVEC} to get the vector-pointer itself, or the macros +@code{XVECEXP} and @code{XVECLEN} to access the elements and length of a +vector. + +@table @code +@item XVEC (@var{exp}, @var{idx}) +Access the vector-pointer which is operand number @var{idx} in @var{exp}. + +@item XVECLEN (@var{exp}, @var{idx}) +Access the length (number of elements) in the vector which is +in operand number @var{idx} in @var{exp}. This value is an @code{int}. + +@item XVECEXP (@var{exp}, @var{idx}, @var{eltnum}) +Access element number @var{eltnum} in the vector which is +in operand number @var{idx} in @var{exp}. This value is an RTX. + +It is up to you to make sure that @var{eltnum} is not negative +and is less than @code{XVECLEN (@var{exp}, @var{idx})}. +@end table + +All the macros defined in this section expand into lvalues and therefore +can be used to assign the operands, lengths and vector elements as well as +to access them. + +@node Flags, Machine Modes, Accessors, RTL +@section Flags in an RTL Expression + +RTL expressions contain several flags (one-bit bit-fields) that are used +in certain types of expression. Most often they are accessed with the +following macros: + +@table @code +@item EXTERNAL_SYMBOL_P (@var{x}) +In a @code{symbol_ref} expression, nonzero if it corresponds to a variable +declared extern in the users code. Zero for all other variables. Stored in +the @code{volatil} field and printed as @samp{/v}. + +@item MEM_VOLATILE_P (@var{x}) +In @code{mem} expressions, nonzero for volatile memory references. +Stored in the @code{volatil} field and printed as @samp{/v}. + +@item MEM_IN_STRUCT_P (@var{x}) +In @code{mem} expressions, nonzero for reference to an entire +structure, union or array, or to a component of one. Zero for +references to a scalar variable or through a pointer to a scalar. +Stored in the @code{in_struct} field and printed as @samp{/s}. + +@item REG_USER_VAR_P (@var{x}) +In a @code{reg}, nonzero if it corresponds to a variable present in +the user's source code. Zero for temporaries generated internally by +the compiler. Stored in the @code{volatil} field and printed as +@samp{/v}. + +@item REG_FUNCTION_VALUE_P (@var{x}) +Nonzero in a @code{reg} if it is the place in which this function's +value is going to be returned. (This happens only in a hard +register.) Stored in the @code{integrated} field and printed as +@samp{/i}. + +The same hard register may be used also for collecting the values of +functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero +in this kind of use. + +@item RTX_UNCHANGING_P (@var{x}) +Nonzero in a @code{reg} or @code{mem} if the value is not changed +explicitly by the current function. (If it is a memory reference then +it may be changed by other functions or by aliasing.) Stored in the +@code{unchanging} field and printed as @samp{/u}. + +@item RTX_INTEGRATED_P (@var{insn}) +Nonzero in an insn if it resulted from an in-line function call. +Stored in the @code{integrated} field and printed as @samp{/i}. This +may be deleted; nothing currently depends on it. + +@item INSN_DELETED_P (@var{insn}) +In an insn, nonzero if the insn has been deleted. Stored in the +@code{volatil} field and printed as @samp{/v}. + +@item CONSTANT_POOL_ADDRESS_P (@var{x}) +Nonzero in a @code{symbol_ref} if it refers to part of the current +function's ``constants pool''. These are addresses close to the +beginning of the function, and GNU CC assumes they can be addressed +directly (perhaps with the help of base registers). Stored in the +@code{unchanging} field and printed as @samp{/u}. +@end table + +These are the fields which the above macros refer to: + +@table @code +@item used +This flag is used only momentarily, at the end of RTL generation for a +function, to count the number of times an expression appears in insns. +Expressions that appear more than once are copied, according to the +rules for shared structure (@pxref{Sharing}). + +@item volatil +This flag is used in @code{mem},@code{symbol_ref} and @code{reg} expressions +and in insns. In RTL dump files, it is printed as @samp{/v}. + +In a @code{mem} expression, it is 1 if the memory reference is volatile. +Volatile memory references may not be deleted, reordered or combined. + +In a @code{reg} expression, it is 1 if the value is a user-level variable. +0 indicates an internal compiler temporary. + +In a @code{symbol_ref} expression, it is 1 if the symbol is declared +@code{extern}. + +In an insn, 1 means the insn has been deleted. + +@item in_struct +This flag is used in @code{mem} expressions. It is 1 if the memory +datum referred to is all or part of a structure or array; 0 if it is (or +might be) a scalar variable. A reference through a C pointer has 0 +because the pointer might point to a scalar variable. + +This information allows the compiler to determine something about possible +cases of aliasing. + +In an RTL dump, this flag is represented as @samp{/s}. + +@item unchanging +This flag is used in @code{reg} and @code{mem} expressions. 1 means +that the value of the expression never changes (at least within the +current function). + +In an RTL dump, this flag is represented as @samp{/u}. + +@item integrated +In some kinds of expressions, including insns, this flag means the +rtl was produced by procedure integration. + +In a @code{reg} expression, this flag indicates the register +containing the value to be returned by the current function. On +machines that pass parameters in registers, the same register number +may be used for parameters as well, but this flag is not set on such +uses. +@end table + +@node Machine Modes, Constants, Flags, RTL +@section Machine Modes + +A machine mode describes a size of data object and the representation used +for it. In the C code, machine modes are represented by an enumeration +type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL +expression has room for a machine mode and so do certain kinds of tree +expressions (declarations and types, to be precise). + +In debugging dumps and machine descriptions, the machine mode of an RTL +expression is written after the expression code with a colon to separate +them. The letters @samp{mode} which appear at the end of each machine mode +name are omitted. For example, @code{(reg:SI 38)} is a @code{reg} +expression with machine mode @code{SImode}. If the mode is +@code{VOIDmode}, it is not written at all. + +Here is a table of machine modes. + +@table @code +@item QImode +``Quarter-Integer'' mode represents a single byte treated as an integer. + +@item HImode +``Half-Integer'' mode represents a two-byte integer. + +@item PSImode +``Partial Single Integer'' mode represents an integer which occupies +four bytes but which doesn't really use all four. On some machines, +this is the right mode to use for pointers. + +@item SImode +``Single Integer'' mode represents a four-byte integer. + +@item PDImode +``Partial Double Integer'' mode represents an integer which occupies +eight bytes but which doesn't really use all eight. On some machines, +this is the right mode to use for certain pointers. + +@item DImode +``Double Integer'' mode represents an eight-byte integer. + +@item TImode +``Tetra Integer'' (?) mode represents a sixteen-byte integer. + +@item SFmode +``Single Floating'' mode represents a single-precision (four byte) floating +point number. + +@item DFmode +``Double Floating'' mode represents a double-precision (eight byte) floating +point number. + +@item XFmode +``Extended Floating'' mode represents a triple-precision (twelve byte) +floating point number. This mode is used for IEEE extended floating +point. + +@item TFmode +``Tetra Floating'' mode represents a quadruple-precision (sixteen byte) +floating point number. + +@item BLKmode +``Block'' mode represents values that are aggregates to which none of +the other modes apply. In RTL, only memory references can have this mode, +and only if they appear in string-move or vector instructions. On machines +which have no such instructions, @code{BLKmode} will not appear in RTL. + +@item VOIDmode +Void mode means the absence of a mode or an unspecified mode. +For example, RTL expressions of code @code{const_int} have mode +@code{VOIDmode} because they can be taken to have whatever mode the context +requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by +the absence of any mode. + +@item EPmode +``Entry Pointer'' mode is intended to be used for function variables in +Pascal and other block structured languages. Such values contain +both a function address and a static chain pointer for access to +automatic variables of outer levels. This mode is only partially +implemented since C does not use it. + +@item CSImode@r{, @dots{}} +``Complex Single Integer'' mode stands for a complex number represented +as a pair of @code{SImode} integers. Any of the integer and floating modes +may have @samp{C} prefixed to its name to obtain a complex number mode. +For example, there are @code{CQImode}, @code{CSFmode}, and @code{CDFmode}. +Since C does not support complex numbers, these machine modes are only +partially implemented. + +@item BImode +This is the machine mode of a bit-field in a structure. It is used +only in the syntax tree, never in RTL, and in the syntax tree it appears +only in declaration nodes. In C, it appears only in @code{FIELD_DECL} +nodes for structure fields defined with a bit size. +@end table + +The machine description defines @code{Pmode} as a C macro which expands +into the machine mode used for addresses. Normally this is @code{SImode}. + +The only modes which a machine description @i{must} support are +@code{QImode}, @code{SImode}, @code{SFmode} and @code{DFmode}. The +compiler will attempt to use @code{DImode} for two-word structures and +unions, but this can be prevented by overriding the definition of +@code{MAX_FIXED_MODE_SIZE}. Likewise, you can arrange for the C type +@code{short int} to avoid using @code{HImode}. In the long term it +might be desirable to make the set of available machine modes +machine-dependent and eliminate all assumptions about specific machine +modes or their uses from the machine-independent code of the compiler. + +To help begin this process, the machine modes are divided into mode +classes. These are represented by the enumeration type @code{enum +mode_class} defined in @file{rtl.h}. The possible mode classes are: + +@table @code +@item MODE_INT +Integer modes. By default these are @code{QImode}, @code{HImode}, +@code{SImode}, @code{DImode}, @code{TImode}, and also @code{BImode}. + +@item MODE_FLOAT +Floating-point modes. By default these are @code{QFmode}, +@code{HFmode}, @code{SFmode}, @code{DFmode} and @code{TFmode}, but the +MC68881 also defines @code{XFmode} to be an 80-bit extended-precision +floating-point mode. + +@item MODE_COMPLEX_INT +Complex integer modes. By default these are @code{CQImode}, +@code{CHImode}, @code{CSImode}, @code{CDImode} and @code{CTImode}. + +@item MODE_COMPLEX_FLOAT +Complex floating-point modes. By default these are @code{CQFmode}, +@code{CHFmode}, @code{CSFmode}, @code{CDFmode} and @code{CTFmode}, + +@item MODE_FUNCTION +Algol or Pascal function variables including a static chain. +(These are not currently implemented). + +@item MODE_RANDOM +This is a catchall mode class for modes which don't fit into the above +classes. Currently @code{VOIDmode}, @code{BLKmode} and @code{EPmode} +are in @code{MODE_RANDOM}. +@end table + +Here are some C macros that relate to machine modes: + +@table @code +@item GET_MODE (@var{x}) +Returns the machine mode of the RTX @var{x}. + +@item PUT_MODE (@var{x}, @var{newmode}) +Alters the machine mode of the RTX @var{x} to be @var{newmode}. + +@item NUM_MACHINE_MODES +Stands for the number of machine modes available on the target +machine. This is one greater than the largest numeric value of any +machine mode. + +@item GET_MODE_NAME (@var{m}) +Returns the name of mode @var{m} as a string. + +@item GET_MODE_CLASS (@var{m}) +Returns the mode class of mode @var{m}. + +@item GET_MODE_SIZE (@var{m}) +Returns the size in bytes of a datum of mode @var{m}. + +@item GET_MODE_BITSIZE (@var{m}) +Returns the size in bits of a datum of mode @var{m}. + +@item GET_MODE_UNIT_SIZE (@var{m}) +Returns the size in bits of the subunits of a datum of mode @var{m}. +This is the same as @code{GET_MODE_SIZE} except in the case of +complex modes and @code{EPmode}. For them, the unit size is the +size of the real or imaginary part, or the size of the function +pointer or the context pointer. +@end table + +@node Constants, Regs and Memory, Machine Modes, RTL +@section Constant Expression Types + +The simplest RTL expressions are those that represent constant values. + +@table @code +@item (const_int @var{i}) +This type of expression represents the integer value @var{i}. @var{i} +is customarily accessed with the macro @code{INTVAL} as in +@code{INTVAL (@var{exp})}, which is equivalent to @code{XINT (@var{exp}, 0)}. + +There is only one expression object for the integer value zero; +it is the value of the variable @code{const0_rtx}. Likewise, the +only expression for integer value one is found in @code{const1_rtx}. +Any attempt to create an expression of code @code{const_int} and +value zero or one will return @code{const0_rtx} or @code{const1_rtx} +as appropriate. + +@item (const_double:@var{m} @var{i0} @var{i1}) +Represents a 64-bit constant of mode @var{m}. All floating point +constants are represented in this way, and so are 64-bit @code{DImode} +integer constants. + +The two integers @var{i0} and @var{i1} together contain the bits of +the value. If the constant is floating point (either single or double +precision), then they represent a @code{double}. To convert them to a +@code{double}, do + +@example +union @{ double d; int i[2];@} u; +u.i[0] = CONST_DOUBLE_LOW(x); +u.i[1] = CONST_DOUBLE_HIGH(x); +@end example + +@noindent +and then refer to @code{u.d}. + +The global variables @code{dconst0_rtx} and @code{fconst0_rtx} hold +@code{const_double} expressions with value 0, in modes @code{DFmode} +and @code{SFmode}, respectively. The macro @code{CONST0_RTX +(@var{mode})} refers to a @code{const_double} expression with value 0 +in mode @var{mode}. The mode @var{mode} must be of mode class +@code{MODE_FLOAT}. + +@item (symbol_ref @var{symbol}) +Represents the value of an assembler label for data. @var{symbol} is +a string that describes the name of the assembler label. If it starts +with a @samp{*}, the label is the rest of @var{symbol} not including +the @samp{*}. Otherwise, the label is @var{symbol}, prefixed with +@samp{_}. + +@item (label_ref @var{label}) +Represents the value of an assembler label for code. It contains one +operand, an expression, which must be a @code{code_label} that appears +in the instruction sequence to identify the place where the label +should go. + +The reason for using a distinct expression type for code label +references is so that jump optimization can distinguish them. + +@item (const @var{exp}) +Represents a constant that is the result of an assembly-time +arithmetic computation. The operand, @var{exp}, is an expression that +contains only constants (@code{const_int}, @code{symbol_ref} and +@code{label_ref} expressions) combined with @code{plus} and +@code{minus}. However, not all combinations are valid, since the +assembler cannot do arbitrary arithmetic on relocatable symbols. +@end table + +@node Regs and Memory, Arithmetic, Constants, RTL +@section Registers and Memory + +Here are the RTL expression types for describing access to machine +registers and to main memory. + +@table @code +@item (reg:@var{m} @var{n}) +For small values of the integer @var{n} (less than +@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine +register number @var{n}: a @dfn{hard register}. For larger values of +@var{n}, it stands for a temporary value or @dfn{pseudo register}. +The compiler's strategy is to generate code assuming an unlimited +number of such pseudo registers, and later convert them into hard +registers or into memory references. + +The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine +description, since the number of hard registers on the machine is an +invariant characteristic of the machine. Note, however, that not +all of the machine registers must be general registers. All the +machine registers that can be used for storage of data are given +hard register numbers, even those that can be used only in certain +instructions or can hold only certain types of data. + +Each pseudo register number used in a function's RTL code is +represented by a unique @code{reg} expression. + +@var{m} is the machine mode of the reference. It is necessary because +machines can generally refer to each register in more than one mode. +For example, a register may contain a full word but there may be +instructions to refer to it as a half word or as a single byte, as +well as instructions to refer to it as a floating point number of +various precisions. + +Even for a register that the machine can access in only one mode, +the mode must always be specified. + +A hard register may be accessed in various modes throughout one +function, but each pseudo register is given a natural mode +and is accessed only in that mode. When it is necessary to describe +an access to a pseudo register using a nonnatural mode, a @code{subreg} +expression is used. + +A @code{reg} expression with a machine mode that specifies more than +one word of data may actually stand for several consecutive registers. +If in addition the register number specifies a hardware register, then +it actually represents several consecutive hardware registers starting +with the specified one. + +Such multi-word hardware register @code{reg} expressions must not be live +across the boundary of a basic block. The lifetime analysis pass does not +know how to record properly that several consecutive registers are +actually live there, and therefore register allocation would be confused. +The CSE pass must go out of its way to make sure the situation does +not arise. + +@item (subreg:@var{m} @var{reg} @var{wordnum}) +@code{subreg} expressions are used to refer to a register in a machine +mode other than its natural one, or to refer to one register of +a multi-word @code{reg} that actually refers to several registers. + +Each pseudo-register has a natural mode. If it is necessary to +operate on it in a different mode---for example, to perform a fullword +move instruction on a pseudo-register that contains a single +byte---the pseudo-register must be enclosed in a @code{subreg}. In +such a case, @var{wordnum} is zero. + +The other use of @code{subreg} is to extract the individual registers +of a multi-register value. Machine modes such as @code{DImode} and +@code{EPmode} indicate values longer than a word, values which usually +require two consecutive registers. To access one of the registers, +use a @code{subreg} with mode @code{SImode} and a @var{wordnum} that +says which register. + +The compilation parameter @code{WORDS_BIG_ENDIAN}, if defined, says +that word number zero is the most significant part; otherwise, it is +the least significant part. + +Between the combiner pass and the reload pass, it is possible to have +a @code{subreg} which contains a @code{mem} instead of a @code{reg} as +its first operand. The reload pass eliminates these cases by +reloading the @code{mem} into a suitable register. + +Note that it is not valid to access a @code{DFmode} value in @code{SFmode} +using a @code{subreg}. On some machines the most significant part of a +@code{DFmode} value does not have the same format as a single-precision +floating value. + +@item (cc0) +This refers to the machine's condition code register. It has no +operands and may not have a machine mode. There are two ways to use it: + +@itemize @bullet +@item +To stand for a complete set of condition code flags. This is best on +most machines, where each comparison sets the entire series of flags. + +With this technique, @code{(cc0)} may be validly used in only two +contexts: as the destination of an assignment (in test and compare +instructions) and in comparison operators comparing against zero +(@code{const_int} with value zero; that is to say, @code{const0_rtx}). + +@item +To stand for a single flag that is the result of a single condition. +This is useful on machines that have only a single flag bit, and in +which comparison instructions must specify the condition to test. + +With this technique, @code{(cc0)} may be validly used in only two +contexts: as the destination of an assignment (in test and compare +instructions) where the source is a comparison operator, and as the +first operand of @code{if_then_else} (in a conditional branch). +@end itemize + +There is only one expression object of code @code{cc0}; it is the +value of the variable @code{cc0_rtx}. Any attempt to create an +expression of code @code{cc0} will return @code{cc0_rtx}. + +One special thing about the condition code register is that +instructions can set it implicitly. On many machines, nearly all +instructions set the condition code based on the value that they +compute or store. It is not necessary to record these actions +explicitly in the RTL because the machine description includes a +prescription for recognizing the instructions that do so (by means of +the macro @code{NOTICE_UPDATE_CC}). Only instructions whose sole +purpose is to set the condition code, and instructions that use the +condition code, need mention @code{(cc0)}. + +In some cases, better code may result from recognizing combinations or +peepholes that include instructions that set the condition codes, even +in cases where some reloading is inevitable. For examples, search for +@samp{addcc} and @samp{andcc} in @file{sparc.md}. + +@item (pc) +This represents the machine's program counter. It has no operands and +may not have a machine mode. @code{(pc)} may be validly used only in +certain specific contexts in jump instructions. + +There is only one expression object of code @code{pc}; it is the value +of the variable @code{pc_rtx}. Any attempt to create an expression of +code @code{pc} will return @code{pc_rtx}. + +All instructions that do not jump alter the program counter implicitly +by incrementing it, but there is no need to mention this in the RTL. + +@item (mem:@var{m} @var{addr}) +This RTX represents a reference to main memory at an address +represented by the expression @var{addr}. @var{m} specifies how large +a unit of memory is accessed. +@end table + +@node Arithmetic, Comparisons, Regs and Memory, RTL +@section RTL Expressions for Arithmetic + +@table @code +@item (plus:@var{m} @var{x} @var{y}) +Represents the sum of the values represented by @var{x} and @var{y} +carried out in machine mode @var{m}. This is valid only if +@var{x} and @var{y} both are valid for mode @var{m}. + +@item (minus:@var{m} @var{x} @var{y}) +Like @code{plus} but represents subtraction. + +@item (compare @var{x} @var{y}) +Represents the result of subtracting @var{y} from @var{x} +for purposes of comparison. The absence of a machine mode +in the @code{compare} expression indicates that the result is +computed without overflow, as if with infinite precision. + +Of course, machines can't really subtract with infinite precision. +However, they can pretend to do so when only the sign of the +result will be used, which is the case when the result is stored +in @code{(cc0)}. And that is the only way this kind of expression +may validly be used: as a value to be stored in the condition codes. + +@item (neg:@var{m} @var{x}) +Represents the negation (subtraction from zero) of the value +represented by @var{x}, carried out in mode @var{m}. @var{x} must be +valid for mode @var{m}. + +@item (mult:@var{m} @var{x} @var{y}) +Represents the signed product of the values represented by @var{x} and +@var{y} carried out in machine mode @var{m}. If +@var{x} and @var{y} are both valid for mode @var{m}, this is ordinary +size-preserving multiplication. Alternatively, both @var{x} and @var{y} +may be valid for a different, narrower mode. This represents the +kind of multiplication that generates a product wider than the operands. +Widening multiplication and same-size multiplication are completely +distinct and supported by different machine instructions; machines may +support one but not the other.@refill + +@code{mult} may be used for floating point multiplication as well. +Then @var{m} is a floating point machine mode. + +@item (umult:@var{m} @var{x} @var{y}) +Like @code{mult} but represents unsigned multiplication. It may be +used in both same-size and widening forms, like @code{mult}. +@code{umult} is used only for fixed-point multiplication. + +@item (div:@var{m} @var{x} @var{y}) +Represents the quotient in signed division of @var{x} by @var{y}, +carried out in machine mode @var{m}. If @var{m} is a floating-point +mode, it represents the exact quotient; otherwise, the integerized +quotient. If @var{x} and @var{y} are both valid for mode @var{m}, +this is ordinary size-preserving division. Some machines have +division instructions in which the operands and quotient widths are +not all the same; such instructions are represented by @code{div} +expressions in which the machine modes are not all the same. + +@item (udiv:@var{m} @var{x} @var{y}) +Like @code{div} but represents unsigned division. + +@item (mod:@var{m} @var{x} @var{y}) +@itemx (umod:@var{m} @var{x} @var{y}) +Like @code{div} and @code{udiv} but represent the remainder instead of +the quotient. + +@item (not:@var{m} @var{x}) +Represents the bitwise complement of the value represented by @var{x}, +carried out in mode @var{m}, which must be a fixed-point machine mode. +@var{x} must be valid for mode @var{m}, which must be a fixed-point mode. + +@item (and:@var{m} @var{x} @var{y}) +Represents the bitwise logical-and of the values represented by +@var{x} and @var{y}, carried out in machine mode @var{m}. This is +valid only if @var{x} and @var{y} both are valid for mode @var{m}, +which must be a fixed-point mode. + +@item (ior:@var{m} @var{x} @var{y}) +Represents the bitwise inclusive-or of the values represented by +@var{x} and @var{y}, carried out in machine mode @var{m}. This is +valid only if @var{x} and @var{y} both are valid for mode @var{m}, +which must be a fixed-point mode. + +@item (xor:@var{m} @var{x} @var{y}) +Represents the bitwise exclusive-or of the values represented by +@var{x} and @var{y}, carried out in machine mode @var{m}. This is +valid only if @var{x} and @var{y} both are valid for mode @var{m}, +which must be a fixed-point mode. + +@item (lshift:@var{m} @var{x} @var{c}) +Represents the result of logically shifting @var{x} left by @var{c} +places. @var{x} must be valid for the mode @var{m}, a fixed-point +machine mode. @var{c} must be valid for a fixed-point mode; +which mode is determined by the mode called for in the machine +description entry for the left-shift instruction. For example, +on the Vax, the mode of @var{c} is @code{QImode} regardless of @var{m}. + +On some machines, negative values of @var{c} may be meaningful; this +is why logical left shift and arithmetic left shift are distinguished. +For example, Vaxes have no right-shift instructions, and right shifts +are represented as left-shift instructions whose counts happen +to be negative constants or else computed (in a previous instruction) +by negation. + +@item (ashift:@var{m} @var{x} @var{c}) +Like @code{lshift} but for arithmetic left shift. + +@item (lshiftrt:@var{m} @var{x} @var{c}) +@itemx (ashiftrt:@var{m} @var{x} @var{c}) +Like @code{lshift} and @code{ashift} but for right shift. + +@item (rotate:@var{m} @var{x} @var{c}) +@itemx (rotatert:@var{m} @var{x} @var{c}) +Similar but represent left and right rotate. + +@item (abs:@var{m} @var{x}) +Represents the absolute value of @var{x}, computed in mode @var{m}. +@var{x} must be valid for @var{m}. + +@item (sqrt:@var{m} @var{x}) +Represents the square root of @var{x}, computed in mode @var{m}. +@var{x} must be valid for @var{m}. Most often @var{m} will be +a floating point mode. + +@item (ffs:@var{m} @var{x}) +Represents one plus the index of the least significant 1-bit in +@var{x}, represented as an integer of mode @var{m}. (The value is +zero if @var{x} is zero.) The mode of @var{x} need not be @var{m}; +depending on the target machine, various mode combinations may be +valid. +@end table + +@node Comparisons, Bit Fields, Arithmetic, RTL +@section Comparison Operations + +Comparison operators test a relation on two operands and are considered +to represent a machine-dependent nonzero value (@code{STORE_FLAG_VALUE}) +if the relation holds, or zero if it does not. The mode of the +comparison is determined by the operands; they must both be valid for a +common machine mode. A comparison with both operands constant would be +invalid as the machine mode could not be deduced from it, but such a +comparison should never exist in RTL due to constant folding. + +Inequality comparisons come in two flavors, signed and unsigned. Thus, +there are distinct expression codes @code{gt} and @code{gtu} for signed and +unsigned greater-than. These can produce different results for the same +pair of integer values: for example, 1 is signed greater-than -1 but not +unsigned greater-than, because -1 when regarded as unsigned is actually +@code{0xffffffff} which is greater than 1. + +The signed comparisons are also used for floating point values. Floating +point comparisons are distinguished by the machine modes of the operands. + +The comparison operators may be used to compare the condition codes +@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such a +construct actually refers to the result of the preceding instruction in +which the condition codes were set. The above example stands for 1 if the +condition codes were set to say ``zero'' or ``equal'', 0 otherwise. +Although the same comparison operators are used for this as may be used in +other contexts on actual data, no confusion can result since the machine +description would never allow both kinds of uses in the same context. + +@table @code +@item (eq @var{x} @var{y}) +1 if the values represented by @var{x} and @var{y} are equal, +otherwise 0. + +@item (ne @var{x} @var{y}) +1 if the values represented by @var{x} and @var{y} are not equal, +otherwise 0. + +@item (gt @var{x} @var{y}) +1 if the @var{x} is greater than @var{y}. If they are fixed-point, +the comparison is done in a signed sense. + +@item (gtu @var{x} @var{y}) +Like @code{gt} but does unsigned comparison, on fixed-point numbers only. + +@item (lt @var{x} @var{y}) +@item (ltu @var{x} @var{y}) +Like @code{gt} and @code{gtu} but test for ``less than''. + +@item (ge @var{x} @var{y}) +@item (geu @var{x} @var{y}) +Like @code{gt} and @code{gtu} but test for ``greater than or equal''. + +@item (le @var{x} @var{y}) +@item (leu @var{x} @var{y}) +Like @code{gt} and @code{gtu} but test for ``less than or equal''. + +@item (if_then_else @var{cond} @var{then} @var{else}) +This is not a comparison operation but is listed here because it is +always used in conjunction with a comparison operation. To be +precise, @var{cond} is a comparison expression. This expression +represents a choice, according to @var{cond}, between the value +represented by @var{then} and the one represented by @var{else}. + +On most machines, @code{if_then_else} expressions are valid only +to express conditional jumps. +@end table + +@node Bit Fields, Conversions, Comparisons, RTL +@section Bit-fields + +Special expression codes exist to represent bit-field instructions. +These types of expressions are lvalues in RTL; they may appear +on the left side of an assignment, indicating insertion of a value +into the specified bit field. + +@table @code +@item (sign_extract:SI @var{loc} @var{size} @var{pos}) +This represents a reference to a sign-extended bit-field contained or +starting in @var{loc} (a memory or register reference). The bit field +is @var{size} bits wide and starts at bit @var{pos}. The compilation +option @code{BITS_BIG_ENDIAN} says which end of the memory unit +@var{pos} counts from. + +Which machine modes are valid for @var{loc} depends on the machine, +but typically @var{loc} should be a single byte when in memory +or a full word in a register. + +@item (zero_extract:SI @var{loc} @var{size} @var{pos}) +Like @code{sign_extract} but refers to an unsigned or zero-extended +bit field. The same sequence of bits are extracted, but they +are filled to an entire word with zeros instead of by sign-extension. +@end table + +@node Conversions, RTL Declarations, Bit Fields, RTL +@section Conversions + +All conversions between machine modes must be represented by +explicit conversion operations. For example, an expression +which is the sum of a byte and a full word cannot be written as +@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus} +operation requires two operands of the same machine mode. +Therefore, the byte-sized operand is enclosed in a conversion +operation, as in + +@example +(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80)) +@end example + +The conversion operation is not a mere placeholder, because there +may be more than one way of converting from a given starting mode +to the desired final mode. The conversion operation code says how +to do it. + +@table @code +@item (sign_extend:@var{m} @var{x}) +Represents the result of sign-extending the value @var{x} +to machine mode @var{m}. @var{m} must be a fixed-point mode +and @var{x} a fixed-point value of a mode narrower than @var{m}. + +@item (zero_extend:@var{m} @var{x}) +Represents the result of zero-extending the value @var{x} +to machine mode @var{m}. @var{m} must be a fixed-point mode +and @var{x} a fixed-point value of a mode narrower than @var{m}. + +@item (float_extend:@var{m} @var{x}) +Represents the result of extending the value @var{x} +to machine mode @var{m}. @var{m} must be a floating point mode +and @var{x} a floating point value of a mode narrower than @var{m}. + +@item (truncate:@var{m} @var{x}) +Represents the result of truncating the value @var{x} +to machine mode @var{m}. @var{m} must be a fixed-point mode +and @var{x} a fixed-point value of a mode wider than @var{m}. + +@item (float_truncate:@var{m} @var{x}) +Represents the result of truncating the value @var{x} +to machine mode @var{m}. @var{m} must be a floating point mode +and @var{x} a floating point value of a mode wider than @var{m}. + +@item (float:@var{m} @var{x}) +Represents the result of converting fixed point value @var{x}, +regarded as signed, to floating point mode @var{m}. + +@item (unsigned_float:@var{m} @var{x}) +Represents the result of converting fixed point value @var{x}, +regarded as unsigned, to floating point mode @var{m}. + +@item (fix:@var{m} @var{x}) +When @var{m} is a fixed point mode, represents the result of +converting floating point value @var{x} to mode @var{m}, regarded as +signed. How rounding is done is not specified, so this operation may +be used validly in compiling C code only for integer-valued operands. + +@item (unsigned_fix:@var{m} @var{x}) +Represents the result of converting floating point value @var{x} to +fixed point mode @var{m}, regarded as unsigned. How rounding is done +is not specified. + +@item (fix:@var{m} @var{x}) +When @var{m} is a floating point mode, represents the result of +converting floating point value @var{x} (valid for mode @var{m}) to an +integer, still represented in floating point mode @var{m}, by rounding +towards zero. +@end table + +@node RTL Declarations, Side Effects, Conversions, RTL +@section Declarations + +Declaration expression codes do not represent arithmetic operations +but rather state assertions about their operands. + +@table @code +@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0)) +This expression code is used in only one context: operand 0 of a +@code{set} expression. In addition, the operand of this expression +must be a @code{subreg} expression. + +The presence of @code{strict_low_part} says that the part of the +register which is meaningful in mode @var{n}, but is not part of +mode @var{m}, is not to be altered. Normally, an assignment to such +a subreg is allowed to have undefined effects on the rest of the +register when @var{m} is less than a word. +@end table + +@node Side Effects, Incdec, RTL Declarations, RTL +@section Side Effect Expressions + +The expression codes described so far represent values, not actions. +But machine instructions never produce values; they are meaningful +only for their side effects on the state of the machine. Special +expression codes are used to represent side effects. + +The body of an instruction is always one of these side effect codes; +the codes described above, which represent values, appear only as +the operands of these. + +@table @code +@item (set @var{lval} @var{x}) +Represents the action of storing the value of @var{x} into the place +represented by @var{lval}. @var{lval} must be an expression +representing a place that can be stored in: @code{reg} (or +@code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or +@code{cc0}.@refill + +If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a +machine mode; then @var{x} must be valid for that mode.@refill + +If @var{lval} is a @code{reg} whose machine mode is less than the full +width of the register, then it means that the part of the register +specified by the machine mode is given the specified value and the +rest of the register receives an undefined value. Likewise, if +@var{lval} is a @code{subreg} whose machine mode is narrower than +@code{SImode}, the rest of the register can be changed in an undefined way. + +If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the +part of the register specified by the machine mode of the +@code{subreg} is given the value @var{x} and the rest of the register +is not changed.@refill + +If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may +have any mode. This represents a ``test'' or ``compare'' instruction.@refill + +If @var{lval} is @code{(pc)}, we have a jump instruction, and the +possibilities for @var{x} are very limited. It may be a +@code{label_ref} expression (unconditional jump). It may be an +@code{if_then_else} (conditional jump), in which case either the +second or the third operand must be @code{(pc)} (for the case which +does not jump) and the other of the two must be a @code{label_ref} +(for the case which does jump). @var{x} may also be a @code{mem} or +@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a +@code{mem}; these unusual patterns are used to represent jumps through +branch tables.@refill + +@item (return) +Represents a return from the current function, on machines where this +can be done with one instruction, such as Vaxes. On machines where a +multi-instruction ``epilogue'' must be executed in order to return +from the function, returning is done by jumping to a label which +precedes the epilogue, and the @code{return} expression code is never +used. + +@item (call @var{function} @var{nargs}) +Represents a function call. @var{function} is a @code{mem} expression +whose address is the address of the function to be called. +@var{nargs} is an expression which can be used for two purposes: on +some machines it represents the number of bytes of stack argument; on +others, it represents the number of argument registers. + +Each machine has a standard machine mode which @var{function} must +have. The machine description defines macro @code{FUNCTION_MODE} to +expand into the requisite mode name. The purpose of this mode is to +specify what kind of addressing is allowed, on machines where the +allowed kinds of addressing depend on the machine mode being +addressed. + +@item (clobber @var{x}) +Represents the storing or possible storing of an unpredictable, +undescribed value into @var{x}, which must be a @code{reg} or +@code{mem} expression. + +One place this is used is in string instructions that store standard +values into particular hard registers. It may not be worth the +trouble to describe the values that are stored, but it is essential to +inform the compiler that the registers will be altered, lest it +attempt to keep data in them across the string instruction. + +@var{x} may also be null---a null C pointer, no expression at all. +Such a @code{(clobber (null))} expression means that all memory +locations must be presumed clobbered. + +Note that the machine description classifies certain hard registers as +``call-clobbered''. All function call instructions are assumed by +default to clobber these registers, so there is no need to use +@code{clobber} expressions to indicate this fact. Also, each function +call is assumed to have the potential to alter any memory location, +unless the function is declared @code{const}. + +When a @code{clobber} expression for a register appears inside a +@code{parallel} with other side effects, GNU CC guarantees that the +register is unoccupied both before and after that insn. Therefore, it +is safe for the assembler code produced by the insn to use the +register as a temporary. You can clobber either a specific hard +register or a pseudo register; in the latter case, GNU CC will +allocate a hard register that is available there for use as a +temporary. + +If you clobber a pseudo register in this way, use a pseudo register +which appears nowhere else---generate a new one each time. Otherwise, +you may confuse CSE. + +There is one other known use for clobbering a pseudo register in a +@code{parallel}: when one of the input operands of the insn is also +clobbered by the insn. In this case, using the same pseudo register in +the clobber and elsewhere in the insn produces the expected results. + +@item (use @var{x}) +Represents the use of the value of @var{x}. It indicates that the +value in @var{x} at this point in the program is needed, even though +it may not be apparent why this is so. Therefore, the compiler will +not attempt to delete previous instructions whose only effect is to +store a value in @var{x}. @var{x} must be a @code{reg} expression. + +@item (parallel [@var{x0} @var{x1} @dots{}]) +Represents several side effects performed in parallel. The square +brackets stand for a vector; the operand of @code{parallel} is a +vector of expressions. @var{x0}, @var{x1} and so on are individual +side effect expressions---expressions of code @code{set}, @code{call}, +@code{return}, @code{clobber} or @code{use}.@refill + +``In parallel'' means that first all the values used in the individual +side-effects are computed, and second all the actual side-effects are +performed. For example, + +@example +(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1))) + (set (mem:SI (reg:SI 1)) (reg:SI 1))]) +@end example + +@noindent +says unambiguously that the values of hard register 1 and the memory +location addressed by it are interchanged. In both places where +@code{(reg:SI 1)} appears as a memory address it refers to the value +in register 1 @emph{before} the execution of the insn. + +It follows that it is @emph{incorrect} to use @code{parallel} and +expect the result of one @code{set} to be available for the next one. +For example, people sometimes attempt to represent a jump-if-zero +instruction this way: + +@example +(parallel [(set (cc0) (reg:SI 34)) + (set (pc) (if_then_else + (eq (cc0) (const_int 0)) + (label_ref @dots{}) + (pc)))]) +@end example + +@noindent +But this is incorrect, because it says that the jump condition depends +on the condition code value @emph{before} this instruction, not on the +new value that is set by this instruction. + +Peephole optimization, which takes place in together with final assembly +code output, can produce insns whose patterns consist of a @code{parallel} +whose elements are the operands needed to output the resulting +assembler code---often @code{reg}, @code{mem} or constant expressions. +This would not be well-formed RTL at any other stage in compilation, +but it is ok then because no further optimization remains to be done. +However, the definition of the macro @code{NOTICE_UPDATE_CC} must +deal with such insns if you define any peephole optimizations. + +@item (sequence [@var{insns} @dots{}]) +Represents a sequence of insns. Each of the @var{insns} that appears +in the vector is suitable for appearing in the chain of insns, so it +must be an @code{insn}, @code{jump_insn}, @code{call_insn}, +@code{code_label}, @code{barrier} or @code{note}. + +A @code{sequence} RTX never appears in an actual insn. It represents +the sequence of insns that result from a @code{define_expand} +@emph{before} those insns are passed to @code{emit_insn} to insert +them in the chain of insns. When actually inserted, the individual +sub-insns are separated out and the @code{sequence} is forgotten. +@end table + +Three expression codes appear in place of a side effect, as the body of an +insn, though strictly speaking they do not describe side effects as such: + +@table @code +@item (asm_input @var{s}) +Represents literal assembler code as described by the string @var{s}. + +@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}]) +Represents a table of jump addresses. The vector elements @var{lr0}, +etc., are @code{label_ref} expressions. The mode @var{m} specifies +how much space is given to each address; normally @var{m} would be +@code{Pmode}. + +@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}]) +Represents a table of jump addresses expressed as offsets from +@var{base}. The vector elements @var{lr0}, etc., are @code{label_ref} +expressions and so is @var{base}. The mode @var{m} specifies how much +space is given to each address-difference.@refill +@end table + +@node Incdec, Assembler, Side Effects, RTL +@section Embedded Side-Effects on Addresses + +Four special side-effect expression codes appear as memory addresses. + +@table @code +@item (pre_dec:@var{m} @var{x}) +Represents the side effect of decrementing @var{x} by a standard +amount and represents also the value that @var{x} has after being +decremented. @var{x} must be a @code{reg} or @code{mem}, but most +machines allow only a @code{reg}. @var{m} must be the machine mode +for pointers on the machine in use. The amount @var{x} is decremented +by is the length in bytes of the machine mode of the containing memory +reference of which this expression serves as the address. Here is an +example of its use:@refill + +@example +(mem:DF (pre_dec:SI (reg:SI 39))) +@end example + +@noindent +This says to decrement pseudo register 39 by the length of a @code{DFmode} +value and use the result to address a @code{DFmode} value. + +@item (pre_inc:@var{m} @var{x}) +Similar, but specifies incrementing @var{x} instead of decrementing it. + +@item (post_dec:@var{m} @var{x}) +Represents the same side effect as @code{pre_dec} but a different +value. The value represented here is the value @var{x} has @i{before} +being decremented. + +@item (post_inc:@var{m} @var{x}) +Similar, but specifies incrementing @var{x} instead of decrementing it. +@end table + +These embedded side effect expressions must be used with care. Instruction +patterns may not use them. Until the @samp{flow} pass of the compiler, +they may occur only to represent pushes onto the stack. The @samp{flow} +pass finds cases where registers are incremented or decremented in one +instruction and used as an address shortly before or after; these cases are +then transformed to use pre- or post-increment or -decrement. + +Explicit popping of the stack could be represented with these embedded +side effect operators, but that would not be safe; the instruction +combination pass could move the popping past pushes, thus changing +the meaning of the code. + +An instruction that can be represented with an embedded side effect +could also be represented using @code{parallel} containing an additional +@code{set} to describe how the address register is altered. This is not +done because machines that allow these operations at all typically +allow them wherever a memory address is called for. Describing them as +additional parallel stores would require doubling the number of entries +in the machine description. + +@node Assembler, Insns, IncDec, RTL +@section Assembler Instructions as Expressions + +The RTX code @code{asm_operands} represents a value produced by a +user-specified assembler instruction. It is used to represent +an @code{asm} statement with arguments. An @code{asm} statement with +a single output operand, like this: + +@example +asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z)); +@end example + +@noindent +is represented using a single @code{asm_operands} RTX which represents +the value that is stored in @code{outputvar}: + +@example +(set @var{rtx-for-outputvar} + (asm_operands "foo %1,%2,%0" "a" 0 + [@var{rtx-for-addition-result} @var{rtx-for-*z}] + [(asm_input:@var{m1} "g") + (asm_input:@var{m2} "di")])) +@end example + +@noindent +Here the operands of the @code{asm_operands} RTX are the assembler +template string, the output-operand's constraint, the index-number of the +output operand among the output operands specified, a vector of input +operand RTX's, and a vector of input-operand modes and constraints. The +mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of +@code{*z}. + +When an @code{asm} statement has multiple output values, its insn has +several such @code{set} RTX's inside of a @code{parallel}. Each @code{set} +contains a @code{asm_operands}; all of these share the same assembler +template and vectors, but each contains the constraint for the respective +output operand. They are also distinguished by the output-operand index +number, which is 0, 1, @dots{} for successive output operands. + +@node Insns, Calls, Assembler, RTL +@section Insns + +The RTL representation of the code for a function is a doubly-linked +chain of objects called @dfn{insns}. Insns are expressions with +special codes that are used for no other purpose. Some insns are +actual instructions; others represent dispatch tables for @code{switch} +statements; others represent labels to jump to or various sorts of +declarative information. + +In addition to its own specific data, each insn must have a unique id-number +that distinguishes it from all other insns in the current function, and +chain pointers to the preceding and following insns. These three fields +occupy the same position in every insn, independent of the expression code +of the insn. They could be accessed with @code{XEXP} and @code{XINT}, +but instead three special macros are always used: + +@table @code +@item INSN_UID (@var{i}) +Accesses the unique id of insn @var{i}. + +@item PREV_INSN (@var{i}) +Accesses the chain pointer to the insn preceding @var{i}. +If @var{i} is the first insn, this is a null pointer. + +@item NEXT_INSN (@var{i}) +Accesses the chain pointer to the insn following @var{i}. +If @var{i} is the last insn, this is a null pointer. +@end table + +The @code{NEXT_INSN} and @code{PREV_INSN} pointers must always +correspond: if @var{insn} is not the first insn, + +@example +NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn} +@end example + +@noindent +is always true. + +Every insn has one of the following six expression codes: + +@table @code +@item insn +The expression code @code{insn} is used for instructions that do not jump +and do not do function calls. Insns with code @code{insn} have four +additional fields beyond the three mandatory ones listed above. +These four are described in a table below. + +@item jump_insn +The expression code @code{jump_insn} is used for instructions that may jump +(or, more generally, may contain @code{label_ref} expressions). +@code{jump_insn} insns have the same extra fields as @code{insn} insns, +accessed in the same way. If there is an instruction to return from the +current function, it is recorded as a @code{jump_insn}. + +@item call_insn +The expression code @code{call_insn} is used for instructions that may do +function calls. It is important to distinguish these instructions because +they imply that certain registers and memory locations may be altered +unpredictably. + +@code{call_insn} insns have the same extra fields as @code{insn} insns, +accessed in the same way. + +@item code_label +A @code{code_label} insn represents a label that a jump insn can jump to. +It contains one special field of data in addition to the three standard ones. +It is used to hold the @dfn{label number}, a number that identifies this +label uniquely among all the labels in the compilation (not just in the +current function). Ultimately, the label is represented in the assembler +output as an assembler label @samp{L@var{n}} where @var{n} is the label number. + +@item barrier +Barriers are placed in the instruction stream after unconditional +jump instructions to indicate that the jumps are unconditional. +They contain no information beyond the three standard fields. + +@item note +@code{note} insns are used to represent additional debugging and +declarative information. They contain two nonstandard fields, an +integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a +string accessed with @code{NOTE_SOURCE_FILE}. + +If @code{NOTE_LINE_NUMBER} is positive, the note represents the +position of a source line and @code{NOTE_SOURCE_FILE} is the source file name +that the line came from. These notes control generation of line +number data in the assembler output. + +Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a +code with one of the following values (and @code{NOTE_SOURCE_FILE} +must contain a null pointer): + +@table @code +@item NOTE_INSN_DELETED +Such a note is completely ignorable. Some passes of the compiler +delete insns by altering them into notes of this kind. + +@item NOTE_INSN_BLOCK_BEG +@itemx NOTE_INSN_BLOCK_END +These types of notes indicate the position of the beginning and end +of a level of scoping of variable names. They control the output +of debugging information. + +@item NOTE_INSN_LOOP_BEG +@itemx NOTE_INSN_LOOP_END +These types of notes indicate the position of the beginning and end +of a @code{while} or @code{for} loop. They enable the loop optimizer +to find loops quickly. +@item NOTE_INSN_FUNCTION_END +Appears near the end of the function body, just before the label that +@code{return} statements jump to (on machine where a single instruction +does not suffice for returning). This note may be deleted by jump +optimization. +@item NOTE_INSN_SETJMP +Appears following each call to @code{setjmp} or a related function. + +@item NOTE_INSN_LOOP_CONT +Appears at the place in a loop that @code{continue} statements jump to. +@end table + +These codes are printed symbolically when they appear in debugging dumps. +@end table + +The machine mode of an insn is normally zero (@code{VOIDmode}), but the +reload pass sets it to @code{QImode} if the insn needs reloading. + +Here is a table of the extra fields of @code{insn}, @code{jump_insn} +and @code{call_insn} insns: + +@table @code +@item PATTERN (@var{i}) +An expression for the side effect performed by this insn. + +@item INSN_CODE (@var{i}) +An integer that says which pattern in the machine description matches +this insn, or -1 if the matching has not yet been attempted. + +Such matching is never attempted and this field is not used on an insn +whose pattern consists of a single @code{use}, @code{clobber}, +@code{asm}, @code{addr_vec} or @code{addr_diff_vec} expression. + +@item LOG_LINKS (@var{i}) +A list (chain of @code{insn_list} expressions) of previous ``related'' +insns: insns which store into registers values that are used for the +first time in this insn. (An additional constraint is that neither a +jump nor a label may come between the related insns). This list is +set up by the flow analysis pass; it is a null pointer until then. + +@item REG_NOTES (@var{i}) +A list (chain of @code{expr_list} expressions) giving information +about the usage of registers in this insn. This list is set up by the +flow analysis pass; it is a null pointer until then. +@end table + +The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list} +expressions. Each of these has two operands: the first is an insn, +and the second is another @code{insn_list} expression (the next one in +the chain). The last @code{insn_list} in the chain has a null pointer +as second operand. The significant thing about the chain is which +insns appear in it (as first operands of @code{insn_list} +expressions). Their order is not significant. + +The @code{REG_NOTES} field of an insn is a similar chain but of +@code{expr_list} expressions instead of @code{insn_list}. There are +several kinds of register notes, which are distinguished by the machine +mode of the @code{expr_list}, which in a register note is really +understood as being an @code{enum reg_note}. The first operand @var{op} +of the @code{expr_list} is data whose meaning depends on the kind of +note. Here are the kinds of register note: + +@table @code +@item REG_DEAD +The register @var{op} dies in this insn; that is to say, altering the +value immediately after this insn would not affect the future behavior +of the program. + +@item REG_INC +The register @var{op} is incremented (or decremented; at this level +there is no distinction) by an embedded side effect inside this insn. +This means it appears in a @code{post_inc}, @code{pre_inc}, +@code{post_dec} or @code{pre_dec} RTX. + +@item REG_EQUIV +The register that is set by this insn will be equal to @var{op} at run +time, and could validly be replaced in all its occurrences by +@var{op}. (``Validly'' here refers to the data flow of the program; +simple replacement may make some insns invalid.) + +The value which the insn explicitly copies into the register may look +different from @var{op}, but they will be equal at run time. + +For example, when a constant is loaded into a register that is never +assigned any other value, this kind of note is used. + +When a parameter is copied into a pseudo-register at entry to a function, +a note of this kind records that the register is equivalent to the stack +slot where the parameter was passed. Although in this case the register +may be set by other insns, it is still valid to replace the register +by the stack slot throughout the function. + +@item REG_EQUAL +The register that is set by this insn will be equal to @var{op} at run +time at the end of this insn (but not necessarily elsewhere in the +function). + +The RTX @var{op} is typically an arithmetic expression. For example, +when a sequence of insns such as a library call is used to perform an +arithmetic operation, this kind of note is attached to the insn that +produces or copies the final value. It tells the CSE pass how to +think of that value. + +@item REG_RETVAL +This insn copies the value of a library call, and @var{op} is the +first insn that was generated to set up the arguments for the library +call. + +Flow analysis uses this note to delete all of a library call whose +result is dead. + +@item REG_WAS_0 +The register @var{op} contained zero before this insn. You can rely +on this note if it is present; its absence implies nothing. + +@item REG_LIBCALL +This is the inverse of @code{REG_RETVAL}: it is placed on the first +insn of a library call, and it points to the last one. + +Loop optimization uses this note to move an entire library call out +of a loop when its value is constant. + +@item REG_NONNEG +The register @var{op} is known to have nonnegative value when this +insn is reached. +@end table + +For convenience, the machine mode in an @code{insn_list} or +@code{expr_list} is printed using these symbolic codes in debugging dumps. + +The only difference between the expression codes @code{insn_list} and +@code{expr_list} is that the first operand of an @code{insn_list} is +assumed to be an insn and is printed in debugging dumps as the insn's +unique id; the first operand of an @code{expr_list} is printed in the +ordinary way as an expression. + +@node Calls, Sharing, Insns, RTL +@section RTL Representation of Function-Call Insns + +Insns that call subroutines have the RTL expression code @code{call_insn}. +These insns must satisfy special rules, and their bodies must use a special +RTL expression code, @code{call}. + +A @code{call} expression has two operands, as follows: + +@example +(call (mem:@var{fm} @var{addr}) @var{nbytes}) +@end example + +@noindent +Here @var{nbytes} is an operand that represents the number of bytes of +argument data being passed to the subroutine, @var{fm} is a machine mode +(which must equal as the definition of the @code{FUNCTION_MODE} macro in +the machine description) and @var{addr} represents the address of the +subroutine. + +For a subroutine that returns no value, the @code{call} RTX as shown above +is the entire body of the insn. + +For a subroutine that returns a value whose mode is not @code{BLKmode}, +the value is returned in a hard register. If this register's number is +@var{r}, then the body of the call insn looks like this: + +@example +(set (reg:@var{m} @var{r}) + (call (mem:@var{fm} @var{addr}) @var{nbytes})) +@end example + +@noindent +This RTL expression makes it clear (to the optimizer passes) that the +appropriate register receives a useful value in this insn. + +Immediately after RTL generation, if the value of the subroutine is +actually used, this call insn is always followed closely by an insn which +refers to the register @var{r}. This remains true through all the +optimizer passes until cross jumping occurs. + +The following insn has one of two forms. Either it copies the value into a +pseudo-register, like this: + +@example +(set (reg:@var{m} @var{p}) (reg:@var{m} @var{r})) +@end example + +@noindent +or (in the case where the calling function will simply return whatever +value the call produced, and no operation is needed to do this): + +@example +(use (reg:@var{m} @var{r})) +@end example + +@noindent +Between the call insn and this following insn there may intervene only a +stack-adjustment insn (and perhaps some @code{note} insns). + +When a subroutine returns a @code{BLKmode} value, it is handled by +passing to the subroutine the address of a place to store the value. +So the call insn itself does not ``return'' any value, and it has the +same RTL form as a call that returns nothing. + +@node Sharing,, Calls, RTL +@section Structure Sharing Assumptions + +The compiler assumes that certain kinds of RTL expressions are unique; +there do not exist two distinct objects representing the same value. +In other cases, it makes an opposite assumption: that no RTL expression +object of a certain kind appears in more than one place in the +containing structure. + +These assumptions refer to a single function; except for the RTL +objects that describe global variables and external functions, +no RTL objects are common to two functions. + +@itemize @bullet +@item +Each pseudo-register has only a single @code{reg} object to represent it, +and therefore only a single machine mode. + +@item +For any symbolic label, there is only one @code{symbol_ref} object +referring to it. + +@item +There is only one @code{const_int} expression with value zero, +and only one with value one. + +@item +There is only one @code{pc} expression. + +@item +There is only one @code{cc0} expression. + +@item +There is only one @code{const_double} expression with mode +@code{SFmode} and value zero, and only one with mode @code{DFmode} and +value zero. + +@item +No @code{label_ref} appears in more than one place in the RTL +structure; in other words, it is safe to do a tree-walk of all the +insns in the function and assume that each time a @code{label_ref} is +seen it is distinct from all others that are seen. + +@item +Only one @code{mem} object is normally created for each static +variable or stack slot, so these objects are frequently shared in all +the places they appear. However, separate but equal objects for these +variables are occasionally made. + +@item +When a single @code{asm} statement has multiple output operands, +a distinct @code{asm_operands} RTX is made for each output operand. +However, these all share the vector which contains the sequence of +input operands. Because this sharing is used later on to test whether +two @code{asm_operands} RTX's come from the same statement, the sharing +must be guaranteed to be preserved. + +@item +No RTL object appears in more than one place in the RTL structure +except as described above. Many passes of the compiler rely on this +by assuming that they can modify RTL objects in place without unwanted +side-effects on other insns. + +@item +During initial RTL generation, shared structure is freely introduced. +After all the RTL for a function has been generated, all shared +structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c}, +after which the above rules are guaranteed to be followed. + +@item +During the combiner pass, shared structure with an insn can exist +temporarily. However, the shared structure is copied before the +combiner is finished with the insn. This is done by +@code{copy_substitutions} in @file{combine.c}. +@end itemize + +@node Machine Desc, Machine Macros, RTL, Top +@chapter Machine Descriptions + +A machine description has two parts: a file of instruction patterns +(@file{.md} file) and a C header file of macro definitions. + +The @file{.md} file for a target machine contains a pattern for each +instruction that the target machine supports (or at least each instruction +that is worth telling the compiler about). It may also contain comments. +A semicolon causes the rest of the line to be a comment, unless the semicolon +is inside a quoted string. + +See the next chapter for information on the C header file. + +@menu +* Patterns:: How to write instruction patterns. +* Example:: An explained example of a @code{define_insn} pattern. +* RTL Template:: The RTL template defines what insns match a pattern. +* Output Template:: The output template says how to make assembler code + from such an insn. +* Output Statement:: For more generality, write C code to output + the assembler code. +* Constraints:: When not all operands are general operands. +* Standard Names:: Names mark patterns to use for code generation. +* Pattern Ordering:: When the order of patterns makes a difference. +* Dependent Patterns:: Having one pattern may make you need another. +* Jump Patterns:: Special considerations for patterns for jump insns. +* Peephole Definitions::Defining machine-specific peephole optimizations. +* Expander Definitions::Generating a sequence of several RTL insns + for a standard operation. +@end menu + +@node Patterns, Example, Machine Desc, Machine Desc +@section Everything about Instruction Patterns + +Each instruction pattern contains an incomplete RTL expression, with pieces +to be filled in later, operand constraints that restrict how the pieces can +be filled in, and an output pattern or C code to generate the assembler +output, all wrapped up in a @code{define_insn} expression. + +A @code{define_insn} is an RTL expression containing four or five operands: + +@enumerate +@item +An optional name. The presence of a name indicate that this instruction +pattern can perform a certain standard job for the RTL-generation +pass of the compiler. This pass knows certain names and will use +the instruction patterns with those names, if the names are defined +in the machine description. + +The absence of a name is indicated by writing an empty string +where the name should go. Nameless instruction patterns are never +used for generating RTL code, but they may permit several simpler insns +to be combined later on. + +Names that are not thus known and used in RTL-generation have no +effect; they are equivalent to no name at all. + +@item +The @dfn{RTL template} (@pxref{RTL Template}) is a vector of +incomplete RTL expressions which show what the instruction should look +like. It is incomplete because it may contain @code{match_operand} +and @code{match_dup} expressions that stand for operands of the +instruction. + +If the vector has only one element, that element is the template for the +instruction pattern. If the vector has multiple elements, then the +instruction pattern is a @code{parallel} expression containing the +elements described. + +@item +A condition. This is a string which contains a C expression that is +the final test to decide whether an insn body matches this pattern. + +For a named pattern, the condition (if present) may not depend on +the data in the insn being matched, but only the target-machine-type +flags. The compiler needs to test these conditions during +initialization in order to learn exactly which named instructions are +available in a particular run. + +For nameless patterns, the condition is applied only when matching an +individual insn, and only after the insn has matched the pattern's +recognition template. The insn's operands may be found in the vector +@code{operands}. + +@item +The @dfn{output template}: a string that says how to output matching +insns as assembler code. @samp{%} in this string specifies where +to substitute the value of an operand. @xref{Output Template}. + +When simple substitution isn't general enough, you can specify a piece +of C code to compute the output. @xref{Output Statement}. + +@item +Optionally, some @dfn{machine-specific information}. The meaning +of this information is defined only by an individual machine description; +typically it might say whether this insn alters the condition codes, +or how many bytes of output it generates. + +This operand is written as a string containing a C initializer +(complete with braces) for the structure type @code{INSN_MACHINE_INFO}, +whose definition is up to you (@pxref{Misc}). +@end enumerate + +@node Example, RTL Template, Patterns, Machine Desc +@section Example of @code{define_insn} + +Here is an actual example of an instruction pattern, for the 68000/68020. + +@example +(define_insn "tstsi" + [(set (cc0) + (match_operand:SI 0 "general_operand" "rm"))] + "" + "* +@{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) + return \"tstl %0\"; + return \"cmpl #0,%0\"; @}") +@end example + +This is an instruction that sets the condition codes based on the value of +a general operand. It has no condition, so any insn whose RTL description +has the form shown may be handled according to this pattern. The name +@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation +pass that, when it is necessary to test such a value, an insn to do so +can be constructed using this pattern. + +The output control string is a piece of C code which chooses which +output template to return based on the kind of operand and the specific +type of CPU for which code is being generated. + +@samp{"rm"} is an operand constraint. Its meaning is explained below. + +@node RTL Template, Output Template, Example, Machine Desc +@section RTL Template for Generating and Recognizing Insns + +The RTL template is used to define which insns match the particular pattern +and how to find their operands. For named patterns, the RTL template also +says how to construct an insn from specified operands. + +Construction involves substituting specified operands into a copy of the +template. Matching involves determining the values that serve as the +operands in the insn being matched. Both of these activities are +controlled by special expression types that direct matching and +substitution of the operands. + +@table @code +@item (match_operand:@var{m} @var{n} @var{pred} @var{constraint}) +This expression is a placeholder for operand number @var{n} of +the insn. When constructing an insn, operand number @var{n} +will be substituted at this point. When matching an insn, whatever +appears at this position in the insn will be taken as operand +number @var{n}; but it must satisfy @var{pred} or this instruction +pattern will not match at all. + +Operand numbers must be chosen consecutively counting from zero in +each instruction pattern. There may be only one @code{match_operand} +expression in the pattern for each operand number. Usually operands +are numbered in the order of appearance in @code{match_operand} +expressions. + +@var{pred} is a string that is the name of a C function that accepts +two arguments, an expression and a machine mode. During matching, the +function will be called with the putative operand as the expression +and @var{m} as the mode argument. If it returns zero, this +instruction pattern fails to match. @var{pred} may be an empty +string; then it means no test is to be done on the operand, +so anything which occurs in this position is valid. + +@var{constraint} controls reloading and the choice of the best register +class to use for a value, as explained later (@pxref{Constraints}). + +People are often unclear on the difference between the constraint and the +predicate. The predicate helps decide whether a given insn matches the +pattern. The constraint plays no role in this decision; instead, it +controls various decisions in the case of an insn which does match. + +Most often, @var{pred} is @code{"general_operand"}. This function checks +that the putative operand is either a constant, a register or a memory +reference, and that it is valid for mode @var{m}. + +For an operand that must be a register, @var{pred} should be +@code{"register_operand"}. It would be valid to use +@code{"general_operand"}, since the reload pass would copy any +non-register operands through registers, but this would make GNU CC do +extra work, and it would prevent the register allocator from doing the +best possible job. + +For an operand that must be a constant, either @var{pred} should be +@code{"immediate_operand"}, or the instruction pattern's extra +condition should check for constants, or both. You cannot expect the +constraints to do this work! If the constraints allow only constants, +but the predicate allows something else, the compiler will crash when +that case arises. + +@item (match_dup @var{n}) +This expression is also a placeholder for operand number @var{n}. +It is used when the operand needs to appear more than once in the +insn. + +In construction, @code{match_dup} behaves exactly like +@code{match_operand}: the operand is substituted into the insn being +constructed. But in matching, @code{match_dup} behaves differently. +It assumes that operand number @var{n} has already been determined by +a @code{match_operand} appearing earlier in the recognition template, +and it matches only an identical-looking expression. + +@item (match_operator:@var{m} @var{n} "@var{predicate}" [@var{operands}@dots{}]) +This pattern is a kind of placeholder for a variable RTL expression +code. + +When constructing an insn, it stands for an RTL expression whose +expression code is taken from that of operand @var{n}, and whose +operands are constructed from the patterns @var{operands}. + +When matching an expression, it matches an expression if the function +@var{predicate} returns nonzero on that expression @emph{and} the +patterns @var{operands} match the operands of the expression. + +Suppose that the function @code{commutative_operator} is defined as +follows, to match any expression whose operator is one of the six +commutative arithmetic operators of RTL and whose mode is @var{mode}: + +@example +int +commutative_operator (x, mode) + rtx x; + enum machine_mode mode; +@{ + enum rtx_code code = GET_CODE (x); + if (GET_MODE (x) != mode) + return 0; + return (code == PLUS || code == MULT || code == UMULT + || code == AND || code == IOR || code == XOR); +@} +@end example + +Then the following pattern will match any RTL expression consisting +of a commutative operator applied to two general operands: + +@example +(match_operator:SI 2 "commutative_operator" + [(match_operand:SI 3 "general_operand" "g") + (match_operand:SI 4 "general_operand" "g")]) +@end example + +Here the vector @code{[@var{operands}@dots{}]} contains two patterns +because the expressions to be matched all contain two operands. + +When this pattern does match, the two operands of the commutative +operator are recorded as operands 3 and 4 of the insn. (This is done +by the two instances of @code{match_operand}.) Operand 2 of the insn +will be the entire commutative expression: use @code{GET_CODE +(operands[2])} to see which commutative operator was used. + +The machine mode @var{m} of @code{match_operator} works like that of +@code{match_operand}: it is passed as the second argument to the +predicate function, and that function is solely responsible for +deciding whether the expression to be matched ``has'' that mode. + +When constructing an insn, argument 2 of the gen-function will specify +the operation (i.e. the expression code) for the expression to be +made. It should be an RTL expression, whose expression code is copied +into a new expression whose operands are arguments 3 and 4 of the +gen-function. The subexpressions of argument 2 are not used; +only its expression code matters. + +There is no way to specify constraints in @code{match_operator}. The +operand of the insn which corresponds to the @code{match_operator} +never has any constraints because it is never reloaded as a whole. +However, if parts of its @var{operands} are matched by +@code{match_operand} patterns, those parts may have constraints of +their own. + +@item (address (match_operand:@var{m} @var{n} "address_operand" "")) +This complex of expressions is a placeholder for an operand number +@var{n} in a ``load address'' instruction: an operand which specifies +a memory location in the usual way, but for which the actual operand +value used is the address of the location, not the contents of the +location. + +@code{address} expressions never appear in RTL code, only in machine +descriptions. And they are used only in machine descriptions that do +not use the operand constraint feature. When operand constraints are +in use, the letter @samp{p} in the constraint serves this purpose. + +@var{m} is the machine mode of the @emph{memory location being +addressed}, not the machine mode of the address itself. That mode is +always the same on a given target machine (it is @code{Pmode}, which +normally is @code{SImode}), so there is no point in mentioning it; +thus, no machine mode is written in the @code{address} expression. If +some day support is added for machines in which addresses of different +kinds of objects appear differently or are used differently (such as +the PDP-10), different formats would perhaps need different machine +modes and these modes might be written in the @code{address} +expression. +@end table + +@node Output Template, Output Statement, RTL Template, Machine Desc +@section Output Templates and Operand Substitution + +The @dfn{output template} is a string which specifies how to output the +assembler code for an instruction pattern. Most of the template is a +fixed string which is output literally. The character @samp{%} is used +to specify where to substitute an operand; it can also be used to +identify places where different variants of the assembler require +different syntax. + +In the simplest case, a @samp{%} followed by a digit @var{n} says to output +operand @var{n} at that point in the string. + +@samp{%} followed by a letter and a digit says to output an operand in an +alternate fashion. Four letters have standard, built-in meanings described +below. The machine description macro @code{PRINT_OPERAND} can define +additional letters with nonstandard meanings. + +@samp{%c@var{digit}} can be used to substitute an operand that is a +constant value without the syntax that normally indicates an immediate +operand. + +@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of +the constant is negated before printing. + +@samp{%a@var{digit}} can be used to substitute an operand as if it were a +memory reference, with the actual operand treated as the address. This may +be useful when outputting a ``load address'' instruction, because often the +assembler syntax for such an instruction requires you to write the operand +as if it were a memory reference. + +@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump +instruction. + +@samp{%} followed by a punctuation character specifies a substitution that +does not use an operand. Only one case is standard: @samp{%%} outputs a +@samp{%} into the assembler code. Other nonstandard cases can be +defined in the @code{PRINT_OPERAND} macro. You must also define +which punctuation characters are valid with the +@code{PRINT_OPERAND_PUNCT_VALID_P} macro. + +The template may generate multiple assembler instructions. Write the text +for the instructions, with @samp{\;} between them. + +When the RTL contains two operands which are required by constraint to match +each other, the output template must refer only to the lower-numbered operand. +Matching operands are not always identical, and the rest of the compiler +arranges to put the proper RTL expression for printing into the lower-numbered +operand. + +One use of nonstandard letters or punctuation following @samp{%} is to +distinguish between different assembler languages for the same machine; for +example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax +requires periods in most opcode names, while MIT syntax does not. For +example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola +syntax. The same file of patterns is used for both kinds of output syntax, +but the character sequence @samp{%.} is used in each place where Motorola +syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax +defines the sequence to output a period; the macro for MIT syntax defines +it to do nothing. + +@node Output Statement, Constraints, Output Template, Machine Desc +@section C Statements for Generating Assembler Output + +Often a single fixed template string cannot produce correct and efficient +assembler code for all the cases that are recognized by a single +instruction pattern. For example, the opcodes may depend on the kinds of +operands; or some unfortunate combinations of operands may require extra +machine instructions. + +If the output control string starts with a @samp{*}, then it is not an +output template but rather a piece of C program that should compute a +template. It should execute a @code{return} statement to return the +template-string you want. Most such templates use C string literals, which +require doublequote characters to delimit them. To include these +doublequote characters in the string, prefix each one with @samp{\}. + +The operands may be found in the array @code{operands}, whose C data type +is @code{rtx []}. + +It is possible to output an assembler instruction and then go on to output +or compute more of them, using the subroutine @code{output_asm_insn}. This +receives two arguments: a template-string and a vector of operands. The +vector may be @code{operands}, or it may be another array of @code{rtx} +that you declare locally and initialize yourself. + +When an insn pattern has multiple alternatives in its constraints, often +the appearance of the assembler code is determined mostly by which alternative +was matched. When this is so, the C code can test the variable +@code{which_alternative}, which is the ordinal number of the alternative +that was actually satisfied (0 for the first, 1 for the second alternative, +etc.). + +For example, suppose there are two opcodes for storing zero, @samp{clrreg} +for registers and @samp{clrmem} for memory locations. Here is how +a pattern could use @code{which_alternative} to choose between them: + +@example +(define_insn "" + [(set (match_operand:SI 0 "general_operand" "r,m") + (const_int 0))] + "" + "* + return (which_alternative == 0 + ? \"clrreg %0\" : \"clrmem %0\"); + ") +@end example + +@node Constraints, Standard Names, Output Statement, Machine Desc +@section Operand Constraints + +Each @code{match_operand} in an instruction pattern can specify a +constraint for the type of operands allowed. Constraints can say whether +an operand may be in a register, and which kinds of register; whether the +operand can be a memory reference, and which kinds of address; whether the +operand may be an immediate constant, and which possible values it may +have. Constraints can also require two operands to match. + +@menu +* Simple Constraints:: Basic use of constraints. +* Multi-Alternative:: When an insn has two alternative constraint-patterns. +* Class Preferences:: Constraints guide which hard register to put things in. +* Modifiers:: More precise control over effects of constraints. +* No Constraints:: Describing a clean machine without constraints. +@end menu + +@node Simple Constraints, Multi-Alternative, Constraints, Constraints +@subsection Simple Constraints + +The simplest kind of constraint is a string full of letters, each of +which describes one kind of operand that is permitted. Here are +the letters that are allowed: + +@table @asis +@item @samp{m} +A memory operand is allowed, with any kind of address that the machine +supports in general. + +@item @samp{o} +A memory operand is allowed, but only if the address is +@dfn{offsettable}. This means that adding a small integer (actually, +the width in bytes of the operand, as determined by its machine mode) +may be added to the address and the result is also a valid memory +address. + +For example, an address which is constant is offsettable; so is an +address that is the sum of a register and a constant (as long as a +slightly larger constant is also within the range of address-offsets +supported by the machine); but an autoincrement or autodecrement +address is not offsettable. More complicated indirect/indexed +addresses may or may not be offsettable depending on the other +addressing modes that the machine supports. + +Note that in an output operand which can be matched by another +operand, the constraint letter @samp{o} is valid only when accompanied +by both @samp{<} (if the target machine has predecrement addressing) +and @samp{>} (if the target machine has preincrement addressing). + +When the constraint letter @samp{o} is used, the reload pass may +generate instructions which copy a nonoffsettable address into an index +register. The idea is that the register can be used as a replacement +offsettable address. But this method requires that there be patterns +to copy any kind of address into a register. Auto-increment +and auto-decrement addresses are an exception; there need not be an +instruction that can copy such an address into a register, because +reload handles these cases specially. + +Most older machine designs have ``load address'' instructions which do +just what is needed here. Some RISC machines do not advertise such +instructions, but the possible addresses on these machines are very +limited, so it is easy to fake them. + +@item @samp{<} +A memory operand with autodecrement addressing (either predecrement or +postdecrement) is allowed. + +@item @samp{>} +A memory operand with autoincrement addressing (either preincrement or +postincrement) is allowed. + +@item @samp{r} +A register operand is allowed provided that it is in a general +register. + +@item @samp{d}, @samp{a}, @samp{f}, @dots{} +Other letters can be defined in machine-dependent fashion to stand for +particular classes of registers. @samp{d}, @samp{a} and @samp{f} are +defined on the 68000/68020 to stand for data, address and floating +point registers. + +@item @samp{i} +An immediate integer operand (one with constant value) is allowed. +This includes symbolic constants whose values will be known only at +assembly time. + +@item @samp{n} +An immediate integer operand with a known numeric value is allowed. +Many systems cannot support assembly-time constants for operands less +than a word wide. Constraints for these operands should use @samp{n} +rather than @samp{i}. + +@item @samp{I}, @samp{J}, @samp{K}, @dots{} +Other letters in the range @samp{I} through @samp{M} may be defined in +a machine-dependent fashion to permit immediate integer operands with +explicit integer values in specified ranges. For example, on the +68000, @samp{I} is defined to stand for the range of values 1 to 8. +This is the range permitted as a shift count in the shift +instructions. + +@item @samp{F} +An immediate floating operand (expression code @code{const_double}) is +allowed. + +@item @samp{G}, @samp{H} +@samp{G} and @samp{H} may be defined in a machine-dependent fashion to +permit immediate floating operands in particular ranges of values. + +@item @samp{s} +An immediate integer operand whose value is not an explicit integer is +allowed. + +This might appear strange; if an insn allows a constant operand with a +value not known at compile time, it certainly must allow any known +value. So why use @samp{s} instead of @samp{i}? Sometimes it allows +better code to be generated. + +For example, on the 68000 in a fullword instruction it is possible to +use an immediate operand; but if the immediate value is between -128 +and 127, better code results from loading the value into a register and +using the register. This is because the load into the register can be +done with a @samp{moveq} instruction. We arrange for this to happen +by defining the letter @samp{K} to mean ``any integer outside the +range -128 to 127'', and then specifying @samp{Ks} in the operand +constraints. + +@item @samp{g} +Any register, memory or immediate integer operand is allowed, except for +registers that are not general registers. + +@item @samp{@var{n}} (a digit) +An operand that matches operand number @var{n} is allowed. +If a digit is used together with letters, the digit should come last. + +This is called a @dfn{matching constraint} and what it really means is +that the assembler has only a single operand that fills two roles +considered separate in the RTL insn. For example, an add insn has two +input operands and one output operand in the RTL, but on most machines +an add instruction really has only two operands, one of them an +input-output operand. + +Matching constraints work only in circumstances like that add insn. +More precisely, the matching constraint must appear in an input-only +operand and the operand that it matches must be an output-only operand +with a lower number. Thus, operand @var{n} must have @samp{=} in its +constraint. + +For operands to match in a particular case usually means that they +are identical-looking RTL expressions. But in a few special cases +specific kinds of dissimilarity are allowed. For example, @code{*x} +as an input operand will match @code{*x++} as an output operand. +For proper results in such cases, the output template should always +use the output-operand's number when printing the operand. + +@item @samp{p} +An operand that is a valid memory address is allowed. This is +for ``load address'' and ``push address'' instructions. + +@samp{p} in the constraint must be accompanies by @code{address_operand} +as the predicate in the @code{match_operand}. +@end table + +In order to have valid assembler code, each operand must satisfy +its constraint. But a failure to do so does not prevent the pattern +from applying to an insn. Instead, it directs the compiler to modify +the code so that the constraint will be satisfied. Usually this is +done by copying an operand into a register. + +Contrast, therefore, the two instruction patterns that follow: + +@example +(define_insn "" + [(set (match_operand:SI 0 "general_operand" "r") + (plus:SI (match_dup 0) + (match_operand:SI 1 "general_operand" "r")))] + "" + "@dots{}") +@end example + +@noindent +which has two operands, one of which must appear in two places, and + +@example +(define_insn "" + [(set (match_operand:SI 0 "general_operand" "r") + (plus:SI (match_operand:SI 1 "general_operand" "0") + (match_operand:SI 2 "general_operand" "r")))] + "" + "@dots{}") +@end example + +@noindent +which has three operands, two of which are required by a constraint to be +identical. If we are considering an insn of the form + +@example +(insn @var{n} @var{prev} @var{next} + (set (reg:SI 3) + (plus:SI (reg:SI 6) (reg:SI 109))) + @dots{}) +@end example + +@noindent +the first pattern would not apply at all, because this insn does not +contain two identical subexpressions in the right place. The pattern would +say, ``That does not look like an add instruction; try other patterns.'' +The second pattern would say, ``Yes, that's an add instruction, but there +is something wrong with it.'' It would direct the reload pass of the +compiler to generate additional insns to make the constraint true. The +results might look like this: + +@example +(insn @var{n2} @var{prev} @var{n} + (set (reg:SI 3) (reg:SI 6)) + @dots{}) + +(insn @var{n} @var{n2} @var{next} + (set (reg:SI 3) + (plus:SI (reg:SI 3) (reg:SI 109))) + @dots{}) +@end example + +It is up to you to make sure that each operand, in each pattern, has +constraints that can handle any RTL expression that could be present for +that operand. (When multiple alternatives are in use, each pattern must, +for each possible combination of operand expressions, have at least one +alternative which can handle that combination of operands.) The +constraints don't need to @emph{allow} any possible operand---when this is +the case, they do not constrain---but they must at least point the way to +reloading any possible operand so that it will fit. + +@itemize @bullet +@item +If the constraint accepts whatever operands the predicate permits, +there is no problem: reloading is never necessary for this operand. + +For example, an operand whose constraints permit everything except +registers is safe provided its predicate rejects registers. + +An operand whose predicate accepts only constant values is safe +provided its constraints include the letter @samp{i}. If any possible +constant value is accepted, then nothing less than @samp{i} will do; +if the predicate is more selective, then the constraints may also be +more selective. + +@item +Any operand expression can be reloaded by copying it into a register. +So if an operand's constraints allow some kind of register, it is +certain to be safe. It need not permit all classes of registers; the +compiler knows how to copy a register into another register of the +proper class in order to make an instruction valid. + +@item +A nonoffsettable memory reference can be reloaded by copying the +address into a register. So if the constraint uses the letter +@samp{o}, all memory references are taken care of. + +@item +A constant operand can be reloaded by allocating space in memory to +hold it as preinitialized data. Then the memory reference can be used +in place of the constant. So if the constraint uses the letters +@samp{o} or @samp{m}, constant operands are not a problem. +@end itemize + +If the operand's predicate can recognize registers, but the constraint does +not permit them, it can make the compiler crash. When this operand happens +to be a register, the reload pass will be stymied, because it does not know +how to copy a register temporarily into memory. + +@node Multi-Alternative, Class Preferences, Simple Constraints, Constraints +@subsection Multiple Alternative Constraints + +Sometimes a single instruction has multiple alternative sets of possible +operands. For example, on the 68000, a logical-or instruction can combine +register or an immediate value into memory, or it can combine any kind of +operand into a register; but it cannot combine one memory location into +another. + +These constraints are represented as multiple alternatives. An alternative +can be described by a series of letters for each operand. The overall +constraint for an operand is made from the letters for this operand +from the first alternative, a comma, the letters for this operand from +the second alternative, a comma, and so on until the last alternative. +Here is how it is done for fullword logical-or on the 68000: + +@example +(define_insn "iorsi3" + [(set (match_operand:SI 0 "general_operand" "=m,d") + (ior:SI (match_operand:SI 1 "general_operand" "%0,0") + (match_operand:SI 2 "general_operand" "dKs,dmKs")))] + @dots{}) +@end example + +The first alternative has @samp{m} (memory) for operand 0, @samp{0} for +operand 1 (meaning it must match operand 0), and @samp{dKs} for operand +2. The second alternative has @samp{d} (data register) for operand 0, +@samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and +@samp{%} in the constraints apply to all the alternatives; their meaning +is explained in the next section. + +If all the operands fit any one alternative, the instruction is valid. +Otherwise, for each alternative, the compiler counts how many instructions +must be added to copy the operands so that that alternative applies. +The alternative requiring the least copying is chosen. If two alternatives +need the same amount of copying, the one that comes first is chosen. +These choices can be altered with the @samp{?} and @samp{!} characters: + +@table @samp +@item ? +Disparage slightly the alternative that the @samp{?} appears in, +as a choice when no alternative applies exactly. The compiler regards +this alternative as one unit more costly for each @samp{?} that appears +in it. + +@item ! +Disparage severely the alternative that the @samp{!} appears in. +When operands must be copied into registers, the compiler will +never choose this alternative as the one to strive for. +@end table + +When an insn pattern has multiple alternatives in its constraints, often +the appearance of the assembler code is determined mostly by which +alternative was matched. When this is so, the C code for writing the +assembler code can use the variable @code{which_alternative}, which is +the ordinal number of the alternative that was actually satisfied (0 for +the first, 1 for the second alternative, etc.). For example: + +@example +(define_insn "" + [(set (match_operand:SI 0 "general_operand" "r,m") + (const_int 0))] + "" + "* + return (which_alternative == 0 + ? \"clrreg %0\" : \"clrmem %0\"); + ") +@end example + +@node Class Preferences, Modifiers, Multi-Alternative, Constraints +@subsection Register Class Preferences + +The operand constraints have another function: they enable the compiler +to decide which kind of hardware register a pseudo register is best +allocated to. The compiler examines the constraints that apply to the +insns that use the pseudo register, looking for the machine-dependent +letters such as @samp{d} and @samp{a} that specify classes of registers. +The pseudo register is put in whichever class gets the most ``votes''. +The constraint letters @samp{g} and @samp{r} also vote: they vote in +favor of a general register. The machine description says which registers +are considered general. + +Of course, on some machines all registers are equivalent, and no register +classes are defined. Then none of this complexity is relevant. + +@node Modifiers, No Constraints, Class Preferences, Constraints +@subsection Constraint Modifier Characters + +@table @samp +@item = +Means that this operand is write-only for this instruction: the previous +value is discarded and replaced by output data. + +@item + +Means that this operand is both read and written by the instruction. + +When the compiler fixes up the operands to satisfy the constraints, +it needs to know which operands are inputs to the instruction and +which are outputs from it. @samp{=} identifies an output; @samp{+} +identifies an operand that is both input and output; all other operands +are assumed to be input only. + +@item & +Means (in a particular alternative) that this operand is written +before the instruction is finished using the input operands. +Therefore, this operand may not lie in a register that is used as an +input operand or as part of any memory address. + +@samp{&} applies only to the alternative in which it is written. In +constraints with multiple alternatives, sometimes one alternative +requires @samp{&} while others do not. See, for example, the +@samp{movdf} insn of the 68000. + +@samp{&} does not obviate the need to write @samp{=}. + +@item % +Declares the instruction to be commutative for this operand and the +following operand. This means that the compiler may interchange the +two operands if that is the cheapest way to make all operands fit the +constraints. This is often used in patterns for addition instructions +that really have only two operands: the result must go in one of the +arguments. Here for example, is how the 68000 halfword-add +instruction is defined: + +@example +(define_insn "addhi3" + [(set (match_operand:HI 0 "general_operand" "=m,r") + (plus:HI (match_operand:HI 1 "general_operand" "%0,0") + (match_operand:HI 2 "general_operand" "di,g")))] + @dots{}) +@end example + +Note that in previous versions of GNU CC the @samp{%} constraint +modifier always applied to operands 1 and 2 regardless of which +operand it was written in. The usual custom was to write it in +operand 0. Now it must be in operand 1 if the operands to be +exchanged are 1 and 2. + +@item # +Says that all following characters, up to the next comma, are to be +ignored as a constraint. They are significant only for choosing +register preferences. + +@item * +Says that the following character should be ignored when choosing +register preferences. @samp{*} has no effect on the meaning of the +constraint as a constraint. + +Here is an example: the 68000 has an instruction to sign-extend a +halfword in a data register, and can also sign-extend a value by +copying it into an address register. While either kind of register is +acceptable, the constraints on an address-register destination are +less strict, so it is best if register allocation makes an address +register its goal. Therefore, @samp{*} is used so that the @samp{d} +constraint letter (for data register) is ignored when computing +register preferences. + +@example +(define_insn "extendhisi2" + [(set (match_operand:SI 0 "general_operand" "=*d,a") + (sign_extend:SI + (match_operand:HI 1 "general_operand" "0,g")))] + @dots{}) +@end example +@end table + +@node No Constraints,, Modifiers, Constraints +@subsection Not Using Constraints + +Some machines are so clean that operand constraints are not required. For +example, on the Vax, an operand valid in one context is valid in any other +context. On such a machine, every operand constraint would be @samp{g}, +excepting only operands of ``load address'' instructions which are +written as if they referred to a memory location's contents but actual +refer to its address. They would have constraint @samp{p}. + +For such machines, instead of writing @samp{g} and @samp{p} for all +the constraints, you can choose to write a description with empty constraints. +Then you write @samp{""} for the constraint in every @code{match_operand}. +Address operands are identified by writing an @code{address} expression +around the @code{match_operand}, not by their constraints. + +When the machine description has just empty constraints, certain parts +of compilation are skipped, making the compiler faster. However, +few machines actually do not need constraints; all machine descriptions +now in existence use constraints. + +@node Standard Names, Pattern Ordering, Constraints, Machine Desc +@section Standard Names for Patterns Used in Generation + +Here is a table of the instruction names that are meaningful in the RTL +generation pass of the compiler. Giving one of these names to an +instruction pattern tells the RTL generation pass that it can use the +pattern in to accomplish a certain task. + +@table @asis +@item @samp{mov@var{m}} +Here @var{m} stands for a two-letter machine mode name, in lower case. +This instruction pattern moves data with that machine mode from operand +1 to operand 0. For example, @samp{movsi} moves full-word data. + +If operand 0 is a @code{subreg} with mode @var{m} of a register whose +own mode is wider than @var{m}, the effect of this instruction is +to store the specified value in the part of the register that corresponds +to mode @var{m}. The effect on the rest of the register is undefined. + +This class of patterns is special in several ways. First of all, each +of these names @emph{must} be defined, because there is no other way +to copy a datum from one place to another. + +Second, these patterns are not used solely in the RTL generation pass. +Even the reload pass can generate move insns to copy values from stack +slots into temporary registers. When it does so, one of the operands is +a hard register and the other is an operand that can need to be reloaded +into a register. + +Therefore, when given such a pair of operands, the pattern must generate +RTL which needs no reloading and needs no temporary registers---no +registers other than the operands. For example, if you support the +pattern with a @code{define_expand}, then in such a case the +@code{define_expand} mustn't call @code{force_reg} or any other such +function which might generate new pseudo registers. + +This requirement exists even for subword modes on a RISC machine where +fetching those modes from memory normally requires several insns and +some temporary registers. Look in @file{spur.md} to see how the +requirement can be satisfied. + +The variety of operands that have reloads depends on the rest of the +machine description, but typically on a RISC machine these can only be +pseudo registers that did not get hard registers, while on other +machines explicit memory references will get optional reloads. + +The constraints on a @samp{move@var{m}} must allow any hard register to +be moved to any other hard register (provided that +@code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers). + +It is obligatory to support floating point @samp{move@var{m}} +instructions into and out of any registers that can hold fixed point +values, because unions and structures (which have modes @code{SImode} or +@code{DImode}) can be in those registers and they may have floating +point members. + +There may also be a need to support fixed point @samp{move@var{m}} +instructions in and out of floating point registers. Unfortunately, I +have forgotten why this was so, and I don't know whether it is still +true. If @code{HARD_REGNO_MODE_OK} rejects fixed point values in +floating point registers, then the constraints of the fixed point +@samp{move@var{m}} instructions must be designed to avoid ever trying to +reload into a floating point register. + +@item @samp{movstrict@var{m}} +Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg} +with mode @var{m} of a register whose natural mode is wider, +the @samp{movstrict@var{m}} instruction is guaranteed not to alter +any of the register except the part which belongs to mode @var{m}. + +@item @samp{add@var{m}3} +Add operand 2 and operand 1, storing the result in operand 0. All operands +must have mode @var{m}. This can be used even on two-address machines, by +means of constraints requiring operands 1 and 0 to be the same location. + +@item @samp{sub@var{m}3}, @samp{mul@var{m}3}, @samp{umul@var{m}3}, @samp{div@var{m}3}, @samp{udiv@var{m}3}, @samp{mod@var{m}3}, @samp{umod@var{m}3}, @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} +Similar, for other arithmetic operations. + +There are special considerations for register classes for logical-and +instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}. +They apply not only to the patterns with these standard names, but to +any patterns that will match such an instruction. @xref{Register +Classes}. + +@item @samp{mulhisi3} +Multiply operands 1 and 2, which have mode @code{HImode}, and store +a @code{SImode} product in operand 0. + +@item @samp{mulqihi3}, @samp{mulsidi3} +Similar widening-multiplication instructions of other widths. + +@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3} +Similar widening-multiplication instructions that do unsigned +multiplication. + +@item @samp{divmod@var{m}4} +Signed division that produces both a quotient and a remainder. +Operand 1 is divided by operand 2 to produce a quotient stored +in operand 0 and a remainder stored in operand 3. + +@item @samp{udivmod@var{m}4} +Similar, but does unsigned division. + +@item @samp{ashl@var{m}3} +Arithmetic-shift operand 1 left by a number of bits specified by +operand 2, and store the result in operand 0. Operand 2 has +mode @code{SImode}, not mode @var{m}. + +@item @samp{ashr@var{m}3}, @samp{lshl@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3} +Other shift and rotate instructions. + +Logical and arithmetic left shift are the same. Machines that do not +allow negative shift counts often have only one instruction for +shifting left. On such machines, you should define a pattern named +@samp{ashl@var{m}3} and leave @samp{lshl@var{m}3} undefined. + +There are special considerations for register classes for shift +instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}. +They apply not only to the patterns with these standard names, but to +any patterns that will match such an instruction. @xref{Register +Classes}. + +@item @samp{neg@var{m}2} +Negate operand 1 and store the result in operand 0. + +@item @samp{abs@var{m}2} +Store the absolute value of operand 1 into operand 0. + +@item @samp{sqrt@var{m}2} +Store the square root of operand 1 into operand 0. + +@item @samp{ffs@var{m}2} +Store into operand 0 one plus the index of the least significant 1-bit +of operand 1. If operand 1 is zero, store zero. @var{m} is the mode +of operand 0; operand 1's mode is specified by the instruction +pattern, and the compiler will convert the operand to that mode before +generating the instruction. + +@item @samp{one_cmpl@var{m}2} +Store the bitwise-complement of operand 1 into operand 0. + +@item @samp{cmp@var{m}} +Compare operand 0 and operand 1, and set the condition codes. +The RTL pattern should look like this: + +@example +(set (cc0) (compare (match_operand:@var{m} 0 @dots{}) + (match_operand:@var{m} 1 @dots{}))) +@end example + +Each such definition in the machine description, for integer mode +@var{m}, must have a corresponding @samp{tst@var{m}} pattern, because +optimization can simplify the compare into a test when operand 1 is +zero. + +@item @samp{tst@var{m}} +Compare operand 0 against zero, and set the condition codes. +The RTL pattern should look like this: + +@example +(set (cc0) (match_operand:@var{m} 0 @dots{})) +@end example + +@item @samp{movstr@var{m}} +Block move instruction. The addresses of the destination and source +strings are the first two operands, and both are in mode @code{Pmode}. +The number of bytes to move is the third operand, in mode @var{m}. +The fourth operand is the known shared alignment of the source and +destination, in the form of a @code{const_int} rtx. + +@item @samp{cmpstr@var{m}} +Block compare instruction, with operands like @samp{movstr@var{m}} +except that the two memory blocks are compared byte by byte +in lexicographic order. The effect of the instruction is to set +the condition codes. + +@item @samp{float@var{m}@var{n}2} +Convert signed integer operand 1 (valid for fixed point mode @var{m}) to +floating point mode @var{n} and store in operand 0 (which has mode +@var{n}). + +@item @samp{floatuns@var{m}@var{n}2} +Convert unsigned integer operand 1 (valid for fixed point mode @var{m}) +to floating point mode @var{n} and store in operand 0 (which has mode +@var{n}). + +@item @samp{fix@var{m}@var{n}2} +Convert operand 1 (valid for floating point mode @var{m}) to fixed +point mode @var{n} as a signed number and store in operand 0 (which +has mode @var{n}). This instruction's result is defined only when +the value of operand 1 is an integer. + +@item @samp{fixuns@var{m}@var{n}2} +Convert operand 1 (valid for floating point mode @var{m}) to fixed +point mode @var{n} as an unsigned number and store in operand 0 (which +has mode @var{n}). This instruction's result is defined only when the +value of operand 1 is an integer. + +@item @samp{ftrunc@var{m}2} +Convert operand 1 (valid for floating point mode @var{m}) to an +integer value, still represented in floating point mode @var{m}, and +store it in operand 0 (valid for floating point mode @var{m}). + +@item @samp{fix_trunc@var{m}@var{n}2} +Like @samp{fix@var{m}@var{n}2} but works for any floating point value +of mode @var{m} by converting the value to an integer. + +@item @samp{fixuns_trunc@var{m}@var{n}2} +Like @samp{fixuns@var{m}@var{n}2} but works for any floating point +value of mode @var{m} by converting the value to an integer. + +@item @samp{trunc@var{m}@var{n}} +Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and +store in operand 0 (which has mode @var{n}). Both modes must be fixed +point or both floating point. + +@item @samp{extend@var{m}@var{n}} +Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and +store in operand 0 (which has mode @var{n}). Both modes must be fixed +point or both floating point. + +@item @samp{zero_extend@var{m}@var{n}} +Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and +store in operand 0 (which has mode @var{n}). Both modes must be fixed +point. + +@item @samp{extv} +Extract a bit-field from operand 1 (a register or memory operand), +where operand 2 specifies the width in bits and operand 3 the starting +bit, and store it in operand 0. Operand 0 must have @code{SImode}. +Operand 1 may have mode @code{QImode} or @code{SImode}; often +@code{SImode} is allowed only for registers. Operands 2 and 3 must be +valid for @code{SImode}. + +The RTL generation pass generates this instruction only with constants +for operands 2 and 3. + +The bit-field value is sign-extended to a full word integer +before it is stored in operand 0. + +@item @samp{extzv} +Like @samp{extv} except that the bit-field value is zero-extended. + +@item @samp{insv} +Store operand 3 (which must be valid for @code{SImode}) into a +bit-field in operand 0, where operand 1 specifies the width in bits +and operand 2 the starting bit. Operand 0 may have mode @code{QImode} +or @code{SImode}; often @code{SImode} is allowed only for registers. +Operands 1 and 2 must be valid for @code{SImode}. + +The RTL generation pass generates this instruction only with constants +for operands 1 and 2. + +@item @samp{s@var{cond}} +Store zero or nonzero in the operand according to the condition codes. +Value stored is nonzero iff the condition @var{cond} is true. +@var{cond} is the name of a comparison operation expression code, such +as @code{eq}, @code{lt} or @code{leu}. + +You specify the mode that the operand must have when you write the +@code{match_operand} expression. The compiler automatically sees +which mode you have used and supplies an operand of that mode. + +The value stored for a true condition must have 1 as its low bit, or +else must be negative. Otherwise the instruction is not suitable and +must be omitted from the machine description. You must tell the +compiler exactly which value is stored by defining the macro +@code{STORE_FLAG_VALUE}. + +@item @samp{b@var{cond}} +Conditional branch instruction. Operand 0 is a @code{label_ref} +that refers to the label to jump to. Jump if the condition codes +meet condition @var{cond}. + +@item @samp{call} +Subroutine call instruction returning no value. Operand 0 is the +function to call; operand 1 is the number of bytes of arguments pushed +(in mode @code{SImode}, except it is normally a @code{const_int}); +operand 2 is the number of registers used as operands. + +On most machines, operand 2 is not actually stored into the RTL +pattern. It is supplied for the sake of some RISC machines which need +to put this information into the assembler code; they can put it in +the RTL instead of operand 1. + +Operand 0 should be a @code{mem} RTX whose address is the address of +the function. + +@item @samp{call_value} +Subroutine call instruction returning a value. Operand 0 is the hard +register in which the value is returned. There are three more +operands, the same as the three operands of the @samp{call} +instruction (but with numbers increased by one). + +Subroutines that return @code{BLKmode} objects use the @samp{call} +insn. + +@item @samp{return} +Subroutine return instruction. This instruction pattern name should be +defined only if a single instruction can do all the work of returning +from a function. + +@item @samp{nop} +No-op instruction. This instruction pattern name should always be defined +to output a no-op in assembler code. @code{(const_int 0)} will do as an +RTL pattern. + +@item @samp{casesi} +Instruction to jump through a dispatch table, including bounds checking. +This instruction takes five operands: + +@enumerate +@item +The index to dispatch on, which has mode @code{SImode}. + +@item +The lower bound for indices in the table, an integer constant. + +@item +The total range of indices in the table---the largest index +minus the smallest one (both inclusive). + +@item +A label to jump to if the index has a value outside the bounds. +(If the machine-description macro @code{CASE_DROPS_THROUGH} is defined, +then an out-of-bounds index drops through to the code following +the jump table instead of jumping to this label. In that case, +this label is not actually used by the @samp{casesi} instruction, +but it is always provided as an operand.) + +@item +A label that precedes the table itself. +@end enumerate + +The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a +@code{jump_insn}. The number of elements in the table is one plus the +difference between the upper bound and the lower bound. + +@item @samp{tablejump} +Instruction to jump to a variable address. This is a low-level +capability which can be used to implement a dispatch table when there +is no @samp{casesi} pattern. + +This pattern requires two operands: the address or offset, and a label +which should immediately precede the jump table. If the macro +@code{CASE_VECTOR_PC_RELATIVE} is defined then the first operand is an +offset that counts from the address of the table; otherwise, it is an +absolute address to jump to. + +The @samp{tablejump} insn is always the last insn before the jump +table it uses. Its assembler code normally has no need to use the +second operand, but you should incorporate it in the RTL pattern so +that the jump optimizer will not delete the table as unreachable code. +@end table + +@node Pattern Ordering, Dependent Patterns, Standard Names, Machine Desc +@section When the Order of Patterns Matters + +Sometimes an insn can match more than one instruction pattern. Then the +pattern that appears first in the machine description is the one used. +Therefore, more specific patterns (patterns that will match fewer things) +and faster instructions (those that will produce better code when they +do match) should usually go first in the description. + +In some cases the effect of ordering the patterns can be used to hide +a pattern when it is not valid. For example, the 68000 has an +instruction for converting a fullword to floating point and another +for converting a byte to floating point. An instruction converting +an integer to floating point could match either one. We put the +pattern to convert the fullword first to make sure that one will +be used rather than the other. (Otherwise a large integer might +be generated as a single-byte immediate quantity, which would not work.) +Instead of using this pattern ordering it would be possible to make the +pattern for convert-a-byte smart enough to deal properly with any +constant value. + +@node Dependent Patterns, Jump Patterns, Pattern Ordering, Machine Desc +@section Interdependence of Patterns + +Every machine description must have a named pattern for each of the +conditional branch names @samp{b@var{cond}}. The recognition template +must always have the form + +@example +(set (pc) + (if_then_else (@var{cond} (cc0) (const_int 0)) + (label_ref (match_operand 0 "" "")) + (pc))) +@end example + +@noindent +In addition, every machine description must have an anonymous pattern +for each of the possible reverse-conditional branches. These patterns +look like + +@example +(set (pc) + (if_then_else (@var{cond} (cc0) (const_int 0)) + (pc) + (label_ref (match_operand 0 "" "")))) +@end example + +@noindent +They are necessary because jump optimization can turn direct-conditional +branches into reverse-conditional branches. + +The compiler does more with RTL than just create it from patterns +and recognize the patterns: it can perform arithmetic expression codes +when constant values for their operands can be determined. As a result, +sometimes having one pattern can require other patterns. For example, the +Vax has no `and' instruction, but it has `and not' instructions. Here +is the definition of one of them: + +@example +(define_insn "andcbsi2" + [(set (match_operand:SI 0 "general_operand" "") + (and:SI (match_dup 0) + (not:SI (match_operand:SI + 1 "general_operand" ""))))] + "" + "bicl2 %1,%0") +@end example + +@noindent +If operand 1 is an explicit integer constant, an instruction constructed +using that pattern can be simplified into an `and' like this: + +@example +(set (reg:SI 41) + (and:SI (reg:SI 41) + (const_int 0xffff7fff))) +@end example + +@noindent +(where the integer constant is the one's complement of what +appeared in the original instruction). + +To avoid a fatal error, the compiler must have a pattern that recognizes +such an instruction. Here is what is used: + +@example +(define_insn "" + [(set (match_operand:SI 0 "general_operand" "") + (and:SI (match_dup 0) + (match_operand:SI 1 "general_operand" "")))] + "GET_CODE (operands[1]) == CONST_INT" + "* +@{ operands[1] + = gen_rtx (CONST_INT, VOIDmode, ~INTVAL (operands[1])); + return \"bicl2 %1,%0\"; +@}") +@end example + +@noindent +Whereas a pattern to match a general `and' instruction is impossible to +support on the Vax, this pattern is possible because it matches only a +constant second argument: a special case that can be output as an `and not' +instruction. + +A ``compare'' instruction whose RTL looks like this: + +@example +(set (cc0) (compare @var{operand} (const_int 0))) +@end example + +@noindent +may be simplified by optimization into a ``test'' like this: + +@example +(set (cc0) @var{operand}) +@end example + +@noindent +So in the machine description, each ``compare'' pattern for an integer +mode must have a corresponding ``test'' pattern that will match the +result of such simplification. + +In some cases machines support instructions identical except for the +machine mode of one or more operands. For example, there may be +``sign-extend halfword'' and ``sign-extend byte'' instructions whose +patterns are + +@example +(set (match_operand:SI 0 @dots{}) + (extend:SI (match_operand:HI 1 @dots{}))) + +(set (match_operand:SI 0 @dots{}) + (extend:SI (match_operand:QI 1 @dots{}))) +@end example + +@noindent +Constant integers do not specify a machine mode, so an instruction to +extend a constant value could match either pattern. The pattern it +actually will match is the one that appears first in the file. For correct +results, this must be the one for the widest possible mode (@code{HImode}, +here). If the pattern matches the @code{QImode} instruction, the results +will be incorrect if the constant value does not actually fit that mode. + +Such instructions to extend constants are rarely generated because they are +optimized away, but they do occasionally happen in nonoptimized +compilations. + +When an instruction has the constraint letter @samp{o}, the reload +pass may generate instructions which copy a nonoffsettable address into +an index register. The idea is that the register can be used as a +replacement offsettable address. In order for these generated +instructions to work, there must be patterns to copy any kind of valid +address into a register. + +Most older machine designs have ``load address'' instructions which do +just what is needed here. Some RISC machines do not advertise such +instructions, but the possible addresses on these machines are very +limited, so it is easy to fake them. + +Auto-increment and auto-decrement addresses are an exception; there +need not be an instruction that can copy such an address into a +register, because reload handles these cases in a different manner. + +@node Jump Patterns, Peephole Definitions, Dependent Patterns, Machine Desc +@section Defining Jump Instruction Patterns + +GNU CC assumes that the machine has a condition code. A comparison insn +sets the condition code, recording the results of both signed and unsigned +comparison of the given operands. A separate branch insn tests the +condition code and branches or not according its value. The branch insns +come in distinct signed and unsigned flavors. Many common machines, such +as the Vax, the 68000 and the 32000, work this way. + +Some machines have distinct signed and unsigned compare instructions, and +only one set of conditional branch instructions. The easiest way to handle +these machines is to treat them just like the others until the final stage +where assembly code is written. At this time, when outputting code for the +compare instruction, peek ahead at the following branch using +@code{NEXT_INSN (insn)}. (The variable @code{insn} refers to the insn +being output, in the output-writing code in an instruction pattern.) If +the RTL says that is an unsigned branch, output an unsigned compare; +otherwise output a signed compare. When the branch itself is output, you +can treat signed and unsigned branches identically. + +The reason you can do this is that GNU CC always generates a pair of +consecutive RTL insns, one to set the condition code and one to test it, +and keeps the pair inviolate until the end. + +To go with this technique, you must define the machine-description macro +@code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no +compare instruction is superfluous. + +Some machines have compare-and-branch instructions and no condition code. +A similar technique works for them. When it is time to ``output'' a +compare instruction, record its operands in two static variables. When +outputting the branch-on-condition-code instruction that follows, actually +output a compare-and-branch instruction that uses the remembered operands. + +It also works to define patterns for compare-and-branch instructions. +In optimizing compilation, the pair of compare and branch instructions +will be combined according to these patterns. But this does not happen +if optimization is not requested. So you must use one of the solutions +above in addition to any special patterns you define. + +@node Peephole Definitions, Expander Definitions, Jump Patterns, Machine Desc +@section Defining Machine-Specific Peephole Optimizers + +In addition to instruction patterns the @file{md} file may contain +definitions of machine-specific peephole optimizations. + +The combiner does not notice certain peephole optimizations when the data +flow in the program does not suggest that it should try them. For example, +sometimes two consecutive insns related in purpose can be combined even +though the second one does not appear to use a register computed in the +first one. A machine-specific peephole optimizer can detect such +opportunities. + +A definition looks like this: + +@example +(define_peephole + [@var{insn-pattern-1} + @var{insn-pattern-2} + @dots{}] + "@var{condition}" + "@var{template}" + "@var{machine-specific info}") +@end example + +@noindent +The last string operand may be omitted if you are not using any +machine-specific information in this machine description. If present, +it must obey the same rules as in a @code{define_insn}. + +In this skeleton, @var{insn-pattern-1} and so on are patterns to match +consecutive insns. The optimization applies to a sequence of insns when +@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches +the next, and so on.@refill + +Each of the insns matched by a peephole must also match a +@code{define_insn}. Peepholes are checked only at the last stage just +before code generation, and only optionally. Therefore, any insn which +would match a peephole but no @code{define_insn} will cause a crash in code +generation in an unoptimized compilation, or at various optimization +stages. + +The operands of the insns are matched with @code{match_operands} and +@code{match_dup}, as usual. What is not usual is that the operand numbers +apply to all the insn patterns in the definition. So, you can check for +identical operands in two insns by using @code{match_operand} in one insn +and @code{match_dup} in the other. + +The operand constraints used in @code{match_operand} patterns do not have +any direct effect on the applicability of the peephole, but they will +be validated afterward, so make sure your constraints are general enough +to apply whenever the peephole matches. If the peephole matches +but the constraints are not satisfied, the compiler will crash. + +It is safe to omit constraints in all the operands of the peephole; or +you can write constraints which serve as a double-check on the criteria +previously tested. + +Once a sequence of insns matches the patterns, the @var{condition} is +checked. This is a C expression which makes the final decision whether to +perform the optimization (we do so if the expression is nonzero). If +@var{condition} is omitted (in other words, the string is empty) then the +optimization is applied to every sequence of insns that matches the +patterns. + +The defined peephole optimizations are applied after register allocation +is complete. Therefore, the peephole definition can check which +operands have ended up in which kinds of registers, just by looking at +the operands. + +The way to refer to the operands in @var{condition} is to write +@code{operands[@var{i}]} for operand number @var{i} (as matched by +@code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} to +refer to the last of the insns being matched; use @code{PREV_INSN} to find +the preceding insns (but be careful to skip over any @code{note} insns that +intervene).@refill + +When optimizing computations with intermediate results, you can use +@var{condition} to match only when the intermediate results are not used +elsewhere. Use the C expression @code{dead_or_set_p (@var{insn}, +@var{op})}, where @var{insn} is the insn in which you expect the value to +be used for the last time (from the value of @code{insn}, together with use +of @code{PREV_INSN}), and @var{op} is the intermediate value (from +@code{operands[@var{i}]}).@refill + +Applying the optimization means replacing the sequence of insns with one +new insn. The @var{template} controls ultimate output of assembler code +for this combined insn. It works exactly like the template of a +@code{define_insn}. Operand numbers in this template are the same ones +used in matching the original sequence of insns. + +The result of a defined peephole optimizer does not need to match any of +the insn patterns in the machine description; it does not even have an +opportunity to match them. The peephole optimizer definition itself serves +as the insn pattern to control how the insn is output. + +Defined peephole optimizers are run as assembler code is being output, +so the insns they produce are never combined or rearranged in any way. + +Here is an example, taken from the 68000 machine description: + +@example +(define_peephole + [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) + (set (match_operand:DF 0 "register_operand" "f") + (match_operand:DF 1 "register_operand" "ad"))] + "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" + "* +@{ + rtx xoperands[2]; + xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1); +#ifdef MOTOROLA + output_asm_insn (\"move.l %1,(sp)\", xoperands); + output_asm_insn (\"move.l %1,-(sp)\", operands); + return \"fmove.d (sp)+,%0\"; +#else + output_asm_insn (\"movel %1,sp@@\", xoperands); + output_asm_insn (\"movel %1,sp@@-\", operands); + return \"fmoved sp@@+,%0\"; +#endif +@} +") +@end example + +The effect of this optimization is to change + +@example +jbsr _foobar +addql #4,sp +movel d1,sp@@- +movel d0,sp@@- +fmoved sp@@+,fp0 +@end example + +@noindent +into + +@example +jbsr _foobar +movel d1,sp@@ +movel d0,sp@@- +fmoved sp@@+,fp0 +@end example + +@ignore +If a peephole matches a sequence including one or more jump insns, you must +take account of the flags such as @code{CC_REVERSED} which specify that the +condition codes are represented in an unusual manner. The compiler +automatically alters any ordinary conditional jumps which occur in such +situations, but the compiler cannot alter jumps which have been replaced by +peephole optimizations. So it is up to you to alter the assembler code +that the peephole produces. Supply C code to write the assembler output, +and in this C code check the condition code status flags and change the +assembler code as appropriate. +@end ignore + +@var{insn-pattern-1} and so on look @emph{almost} like the second +operand of @code{define_insn}. There is one important difference: the +second operand of @code{define_insn} consists of one or more RTX's +enclosed in square brackets. Usually, there is only one: then the same +action can be written as an element of a @code{define_peephole}. But +when there are multiple actions in a @code{define_insn}, they are +implicitly enclosed in a @code{parallel}. Then you must explicitly +write the @code{parallel}, and the square brackets within it, in the +@code{define_peephole}. Thus, if an insn pattern looks like this, + +@example +(define_insn "divmodsi4" + [(set (match_operand:SI 0 "general_operand" "=d") + (div:SI (match_operand:SI 1 "general_operand" "0") + (match_operand:SI 2 "general_operand" "dmsK"))) + (set (match_operand:SI 3 "general_operand" "=d") + (mod:SI (match_dup 1) (match_dup 2)))] + "TARGET_68020" + "divsl%.l %2,%3:%0") +@end example + +@noindent +then the way to mention this insn in a peephole is as follows: + +@example +(define_peephole + [@dots{} + (parallel + [(set (match_operand:SI 0 "general_operand" "=d") + (div:SI (match_operand:SI 1 "general_operand" "0") + (match_operand:SI 2 "general_operand" "dmsK"))) + (set (match_operand:SI 3 "general_operand" "=d") + (mod:SI (match_dup 1) (match_dup 2)))]) + @dots{}] + @dots{}) +@end example + +@node Expander Definitions,, Peephole Definitions, Machine Desc +@section Defining RTL Sequences for Code Generation + +On some target machines, some standard pattern names for RTL generation +cannot be handled with single insn, but a sequence of RTL insns can +represent them. For these target machines, you can write a +@code{define_expand} to specify how to generate the sequence of RTL. + +A @code{define_expand} is an RTL expression that looks almost like a +@code{define_insn}; but, unlike the latter, a @code{define_expand} is used +only for RTL generation and it can produce more than one RTL insn. + +A @code{define_expand} RTX has four operands: + +@itemize @bullet +@item +The name. Each @code{define_expand} must have a name, since the only +use for it is to refer to it by name. + +@item +The RTL template. This is just like the RTL template for a +@code{define_peephole} in that it is a vector of RTL expressions +each being one insn. + +@item +The condition, a string containing a C expression. This expression is +used to express how the availability of this pattern depends on +subclasses of target machine, selected by command-line options when +GNU CC is run. This is just like the condition of a +@code{define_insn} that has a standard name. + +@item +The preparation statements, a string containing zero or more C +statements which are to be executed before RTL code is generated from +the RTL template. + +Usually these statements prepare temporary registers for use as +internal operands in the RTL template, but they can also generate RTL +insns directly by calling routines such as @code{emit_insn}, etc. +Any such insns precede the ones that come from the RTL template. +@end itemize + +Every RTL insn emitted by a @code{define_expand} must match some +@code{define_insn} in the machine description. Otherwise, the compiler +will crash when trying to generate code for the insn or trying to optimize +it. + +The RTL template, in addition to controlling generation of RTL insns, +also describes the operands that need to be specified when this pattern +is used. In particular, it gives a predicate for each operand. + +A true operand, which need to be specified in order to generate RTL from +the pattern, should be described with a @code{match_operand} in its first +occurrence in the RTL template. This enters information on the operand's +predicate into the tables that record such things. GNU CC uses the +information to preload the operand into a register if that is required for +valid RTL code. If the operand is referred to more than once, subsequent +references should use @code{match_dup}. + +The RTL template may also refer to internal ``operands'' which are +temporary registers or labels used only within the sequence made by the +@code{define_expand}. Internal operands are substituted into the RTL +template with @code{match_dup}, never with @code{match_operand}. The +values of the internal operands are not passed in as arguments by the +compiler when it requests use of this pattern. Instead, they are computed +within the pattern, in the preparation statements. These statements +compute the values and store them into the appropriate elements of +@code{operands} so that @code{match_dup} can find them. + +There are two special macros defined for use in the preparation statements: +@code{DONE} and @code{FAIL}. Use them with a following semicolon, +as a statement. + +@table @code +@item DONE +Use the @code{DONE} macro to end RTL generation for the pattern. The +only RTL insns resulting from the pattern on this occasion will be +those already emitted by explicit calls to @code{emit_insn} within the +preparation statements; the RTL template will not be generated. + +@item FAIL +Make the pattern fail on this occasion. When a pattern fails, it means +that the pattern was not truly available. The calling routines in the +compiler will try other strategies for code generation using other patterns. + +Failure is currently supported only for binary operations (addition, +multiplication, shifting, etc.). + +Do not emit any insns explicitly with @code{emit_insn} before failing. +@end table + +Here is an example, the definition of left-shift for the SPUR chip: + +@example +(define_expand "ashlsi3" + [(set (match_operand:SI 0 "register_operand" "") + (ashift:SI + (match_operand:SI 1 "register_operand" "") + (match_operand:SI 2 "nonmemory_operand" "")))] + "" + " +@{ + if (GET_CODE (operands[2]) != CONST_INT + || (unsigned) INTVAL (operands[2]) > 3) + FAIL; +@}") +@end example + +@noindent +This example uses @code{define_expand} so that it can generate an RTL insn +for shifting when the shift-count is in the supported range of 0 to 3 but +fail in other cases where machine insns aren't available. When it fails, +the compiler tries another strategy using different patterns (such as, a +library call). + +If the compiler were able to handle nontrivial condition-strings in +patterns with names, then it would be possible to use a +@code{define_insn} in that case. Here is another case (zero-extension +on the 68000) which makes more use of the power of @code{define_expand}: + +@example +(define_expand "zero_extendhisi2" + [(set (match_operand:SI 0 "general_operand" "") + (const_int 0)) + (set (strict_low_part + (subreg:HI + (match_dup 0) + 0)) + (match_operand:HI 1 "general_operand" ""))] + "" + "operands[1] = make_safe_from (operands[1], operands[0]);") +@end example + +@noindent +Here two RTL insns are generated, one to clear the entire output operand +and the other to copy the input operand into its low half. This sequence +is incorrect if the input operand refers to [the old value of] the output +operand, so the preparation statement makes sure this isn't so. The +function @code{make_safe_from} copies the @code{operands[1]} into a +temporary register if it refers to @code{operands[0]}. It does this +by emitting another RTL insn. + +Finally, a third example shows the use of an internal operand. +Zero-extension on the SPUR chip is done by @code{and}-ing the result +against a halfword mask. But this mask cannot be represented by a +@code{const_int} because the constant value is too large to be legitimate +on this machine. So it must be copied into a register with +@code{force_reg} and then the register used in the @code{and}. + +@example +(define_expand "zero_extendhisi2" + [(set (match_operand:SI 0 "register_operand" "") + (and:SI (subreg:SI + (match_operand:HI 1 "register_operand" "") + 0) + (match_dup 2)))] + "" + "operands[2] + = force_reg (SImode, gen_rtx (CONST_INT, + VOIDmode, 65535)); ") +@end example + +@strong{Note:} If the @code{define_expand} is used to serve a standard +binary or unary arithmetic operation, then the last insn it generates +must not be a @code{code_label}, @code{barrier} or @code{note}. It must +be an @code{insn}, @code{jump_insn} or @code{call_insn}. + +@node Machine Macros, Config, Machine Desc, Top +@chapter Machine Description Macros + +The other half of the machine description is a C header file conventionally +given the name @file{tm-@var{machine}.h}. The file @file{tm.h} should be a +link to it. The header file @file{config.h} includes @file{tm.h} and most +compiler source files include @file{config.h}. + +@menu +* Run-time Target:: Defining @samp{-m} options like @samp{-m68000} and @samp{-m68020}. +* Storage Layout:: Defining sizes and alignments of data types. +* Registers:: Naming and describing the hardware registers. +* Register Classes:: Defining the classes of hardware registers. +* Stack Layout:: Defining which way the stack grows and by how much. +* Library Calls:: Specifying how to call certain library routines. +* Addressing Modes:: Defining addressing modes valid for memory operands. +* Delayed Branch:: Do branches execute the following instruction? +* Condition Code:: Defining how insns update the condition code. +* Cross-compilation:: Handling floating point for cross-compilers. +* Misc:: Everything else. +* Assembler Format:: Defining how to write insns and pseudo-ops to output. +@end menu + +@node Run-time Target, Storage Layout, Machine Macros, Machine Macros +@section Run-time Target Specification + +@table @code +@item CPP_PREDEFINES +Define this to be a string constant containing @samp{-D} options to +define the predefined macros that identify this machine and system. +These macros will be predefined unless the @samp{-ansi} option is +specified. + +In addition, a parallel set of macros are predefined, whose names are +made by appending @samp{__} at the beginning and at the end. These +@samp{__} macros are permitted by the ANSI standard, so they are +predefined regardless of whether @samp{-ansi} is specified. + +For example, on the Sun, one can use the following value: + +@example +"-Dmc68000 -Dsun -Dunix" +@end example + +The result is to define the macros @code{__mc68000__}, @code{__sun__} +and @code{__unix__} unconditionally, and the macros @code{mc68000}, +@code{sun} and @code{unix} provided @samp{-ansi} is not specified. + +@item CPP_SPEC +A C string constant that tells the GNU CC driver program options to +pass to CPP. It can also specify how to translate options you +give to GNU CC into options for GNU CC to pass to the CPP. + +Do not define this macro if it does not need to do anything. + +@item CC1_SPEC +A C string constant that tells the GNU CC driver program options to +pass to CC1. It can also specify how to translate options you +give to GNU CC into options for GNU CC to pass to the CC1. + +Do not define this macro if it does not need to do anything. + +@item extern int target_flags; +This declaration should be present. + +@item TARGET_@dots{} +This series of macros is to allow compiler command arguments to +enable or disable the use of optional features of the target machine. +For example, one machine description serves both the 68000 and +the 68020; a command argument tells the compiler whether it should +use 68020-only instructions or not. This command argument works +by means of a macro @code{TARGET_68020} that tests a bit in +@code{target_flags}. + +Define a macro @code{TARGET_@var{featurename}} for each such option. +Its definition should test a bit in @code{target_flags}; for example: + +@example +#define TARGET_68020 (target_flags & 1) +@end example + +One place where these macros are used is in the condition-expressions +of instruction patterns. Note how @code{TARGET_68020} appears +frequently in the 68000 machine description file, @file{m68k.md}. +Another place they are used is in the definitions of the other +macros in the @file{tm-@var{machine}.h} file. + +@item TARGET_SWITCHES +This macro defines names of command options to set and clear +bits in @code{target_flags}. Its definition is an initializer +with a subgrouping for each command option. + +Each subgrouping contains a string constant, that defines the option +name, and a number, which contains the bits to set in +@code{target_flags}. A negative number says to clear bits instead; +the negative of the number is which bits to clear. The actual option +name is made by appending @samp{-m} to the specified name. + +One of the subgroupings should have a null string. The number in +this grouping is the default value for @code{target_flags}. Any +target options act starting with that value. + +Here is an example which defines @samp{-m68000} and @samp{-m68020} +with opposite meanings, and picks the latter as the default: + +@example +#define TARGET_SWITCHES \ + @{ @{ "68020", 1@}, \ + @{ "68000", -1@}, \ + @{ "", 1@}@} +@end example + +@item OVERRIDE_OPTIONS +Sometimes certain combinations of command options do not make sense on +a particular target machine. You can define a macro +@code{OVERRIDE_OPTIONS} to take account of this. This macro, if +defined, is executed once just after all the command options have been +parsed. +@end table + +@node Storage Layout, Registers, Run-time Target, Machine Macros +@section Storage Layout + +Note that the definitions of the macros in this table which are sizes or +alignments measured in bits do not need to be constant. They can be C +expressions that refer to static variables, such as the @code{target_flags}. +@xref{Run-time Target}. + +@table @code +@item BITS_BIG_ENDIAN +Define this macro if the most significant bit in a byte has the lowest +number. This means that bit-field instructions count from the most +significant bit. If the machine has no bit-field instructions, this +macro is irrelevant. + +This macro does not affect the way structure fields are packed into +bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. + +@item BYTES_BIG_ENDIAN +Define this macro if the most significant byte in a word has the +lowest number. + +@item WORDS_BIG_ENDIAN +Define this macro if, in a multiword object, the most significant +word has the lowest number. + +@item BITS_PER_UNIT +Number of bits in an addressable storage unit (byte); normally 8. + +@item BITS_PER_WORD +Number of bits in a word; normally 32. + +@item UNITS_PER_WORD +Number of storage units in a word; normally 4. + +@item POINTER_SIZE +Width of a pointer, in bits. + +@item POINTER_BOUNDARY +Alignment required for pointers stored in memory, in bits. + +@item PARM_BOUNDARY +Normal alignment required for function parameters on the stack, in +bits. All stack parameters receive least this much alignment +regardless of data type. On most machines, this is the same as the +size of an integer. + +@item MAX_PARM_BOUNDARY +Largest alignment required for any stack parameters, in bits. If the +data type of the parameter calls for more alignment than +@code{PARM_BOUNDARY}, then it is given extra padding up to this limit. + +Don't define this macro if it would be equal to @code{PARM_BOUNDARY}; +in other words, if the alignment of a stack parameter should not +depend on its data type (as is the case on most machines). + +@item STACK_BOUNDARY +Define this macro if you wish to preserve a certain alignment for +the stack pointer at all times. The definition is a C expression +for the desired alignment (measured in bits). + +@item FUNCTION_BOUNDARY +Alignment required for a function entry point, in bits. + +@item BIGGEST_ALIGNMENT +Biggest alignment that any data type can require on this machine, in bits. + +@item CONSTANT_ALIGNMENT (@var{code}, @var{typealign}) +A C expression to compute the alignment for a constant. The argument +@var{typealign} is the alignment required for the constant's data type. +@var{code} is the tree code of the constant itself. + +If this macro is not defined, the default is to use @var{typealign}. If +you do define this macro, the value must be a multiple of +@var{typealign}. + +The purpose of defining this macro is usually to cause string constants +to be word aligned so that @file{dhrystone} can be made to run faster. + +@item EMPTY_FIELD_BOUNDARY +Alignment in bits to be given to a structure bit field that follows an +empty field such as @code{int : 0;}. + +@item STRUCTURE_SIZE_BOUNDARY +Number of bits which any structure or union's size must be a multiple of. +Each structure or union's size is rounded up to a multiple of this. + +If you do not define this macro, the default is the same as +@code{BITS_PER_UNIT}. + +@item STRICT_ALIGNMENT +Define this if instructions will fail to work if given data not +on the nominal alignment. If instructions will merely go slower +in that case, do not define this macro. + +@item PCC_BITFIELD_TYPE_MATTERS +Define this if you wish to imitate a certain bizarre behavior pattern +of some instances of PCC: a bit field whose declared type is +@code{int} has the same effect on the size and alignment of a +structure as an actual @code{int} would have. + +If the macro is defined, then its definition should be a C expression; +a nonzero value for the expression enables PCC-compatible behavior. + +Just what effect that is in GNU CC depends on other parameters, but on +most machines it would force the structure's alignment and size to a +multiple of 32 or @code{BIGGEST_ALIGNMENT} bits. + +@item MAX_FIXED_MODE_SIZE +An integer expression for the largest integer machine mode that should +actually be used. All integer machine modes of this size or smaller +can be used for structures and unions with the appropriate sizes. + +@item CHECK_FLOAT_VALUE (@var{mode}, @var{value}) +A C statement to validate the value @var{value} (or type +@code{double}) for mode @var{mode}. This means that you check whether +@var{value} fits within the possible range of values for mode +@var{mode} on this target machine. The mode @var{mode} is always +@code{SFmode} or @code{DFmode}. + +If @var{value} is not valid, you should call @code{error} to print an +error message and then assign some valid value to @var{value}. +Allowing an invalid value to go through the compiler can produce +incorrect assembler code which may even cause Unix assemblers to +crash. + +This macro need not be defined if there is no work for it to do. +@end table + +@node Registers, Register Classes, Storage Layout, Machine Macros +@section Register Usage + +@table @code +@item FIRST_PSEUDO_REGISTER +Number of hardware registers known to the compiler. They receive +numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first +pseudo register's number really is assigned the number +@code{FIRST_PSEUDO_REGISTER}. + +@item FIXED_REGISTERS +An initializer that says which registers are used for fixed purposes +all throughout the compiled code and are therefore not available for +general allocation. These would include the stack pointer, the frame +pointer (except on machines where that can be used as a general +register when no frame pointer is needed), the program counter on +machines where that is considered one of the addressable registers, +and any other numbered register with a standard use. + +This information is expressed as a sequence of numbers, separated by +commas and surrounded by braces. The @var{n}th number is 1 if +register @var{n} is fixed, 0 otherwise. + +The table initialized from this macro, and the table initialized by +the following one, may be overridden at run time either automatically, +by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by +the user with the command options @samp{-ffixed-@var{reg}}, +@samp{-fcall-used-@var{reg}} and @samp{-fcall-saved-@var{reg}}. + +@item CALL_USED_REGISTERS +Like @code{FIXED_REGISTERS} but has 1 for each register that is +clobbered (in general) by function calls as well as for fixed +registers. This macro therefore identifies the registers that are not +available for general allocation of values that must live across +function calls. + +If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler +automatically saves it on function entry and restores it on function +exit, if the register is used within the function. + +@item DEFAULT_CALLER_SAVES +Define this macro if function calls on the target machine do not preserve +any registers; in other words, if @code{CALL_USED_REGISTERS} has 1 +for all registers. This macro enables @samp{-fcaller-saves} by default. +Eventually that option will be enabled by default on all machines and both +the option and this macro will be eliminated. + +@item CONDITIONAL_REGISTER_USAGE +Zero or more C statements that may conditionally modify two variables +@code{fixed_regs} and @code{call_used_regs} (both of type @code{char +[]}) after they have been initialized from the two preceding macros. + +This is necessary in case the fixed or call-clobbered registers depend +on target flags. + +You need not define this macro if it has no work to do. + +If the usage of an entire class of registers depends on the target +flags, you may indicate this to GCC by using this macro to modify +@code{fixed_regs} and @code{call_used_regs} to 1 for each of the +registers in the classes which should not be used by GCC. Also define +the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it +is called with a letter for a class that shouldn't be used. + +(However, if this class is not included in @code{GENERAL_REGS} and all +of the insn patterns whose constraints permit this class are +controlled by target switches, then GCC will automatically avoid using +these registers when the target switches are opposed to them.) + +@item OVERLAPPING_REGNO_P (@var{regno}) +If defined, this is a C expression whose value is nonzero if hard +register number @var{regno} is an overlapping register. This means a +hard register which overlaps a hard register with a different number. +(Such overlap is undesirable, but occasionally it allows a machine to +be supported which otherwise could not be.) This macro must return +nonzero for @emph{all} the registers which overlap each other. GNU CC +can use an overlapping register only in certain limited ways. It can +be used for allocation within a basic block, and may be spilled for +reloading; that is all. + +If this macro is not defined, it means that none of the hard registers +overlap each other. This is the usual situation. + +@item INSN_CLOBBERS_REGNO_P (@var{insn}, @var{regno}) +If defined, this is a C expression whose value should be nonzero if +the insn @var{insn} has the effect of mysteriously clobbering the +contents of hard register number @var{regno}. By ``mysterious'' we +mean that the insn's RTL expression doesn't describe such an effect. + +If this macro is not defined, it means that no insn clobbers registers +mysteriously. This is the usual situation; all else being equal, +it is best for the RTL expression to show all the activity. + +@item PRESERVE_DEATH_INFO_REGNO_P (@var{regno}) +If defined, this is a C expression whose value is nonzero if accurate +@code{REG_DEAD} notes are needed for hard register number @var{regno} +at the time of outputting the assembler code. When this is so, a few +optimizations that take place after register allocation and could +invalidate the death notes are not done when this register is +involved. + +You would arrange to preserve death info for a register when some of the +code in the machine description which is executed to write the assembler +code looks at the death notes. This is necessary only when the actual +hardware feature which GNU CC thinks of as a register is not actually a +register of the usual sort. (It might, for example, be a hardware +stack.) + +If this macro is not defined, it means that no death notes need to be +preserved. This is the usual situation. + +@item HARD_REGNO_NREGS (@var{regno}, @var{mode}) +A C expression for the number of consecutive hard registers, starting +at register number @var{regno}, required to hold a value of mode +@var{mode}. + +On a machine where all registers are exactly one word, a suitable +definition of this macro is + +@example +#define HARD_REGNO_NREGS(REGNO, MODE) \ + ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ + / UNITS_PER_WORD)) +@end example + +@item HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) +A C expression that is nonzero if it is permissible to store a value +of mode @var{mode} in hard register number @var{regno} (or in several +registers starting with that one). For a machine where all registers +are equivalent, a suitable definition is + +@example +#define HARD_REGNO_MODE_OK(REGNO, MODE) 1 +@end example + +It is not necessary for this macro to check for the numbers of fixed +registers, because the allocation mechanism considers them to be always +occupied. + +On some machines, double-precision values must be kept in even/odd +register pairs. The way to implement that is to define this macro +to reject odd register numbers for such modes. + +GNU CC assumes that it can always move values between registers and +(suitably addressed) memory locations. If it is impossible to move a +value of a certain mode between memory and certain registers, then +@code{HARD_REGNO_MODE_OK} must not allow this mode in those registers. + +Many machines have special registers for floating point arithmetic. +Often people assume that floating point machine modes are allowed only +in floating point registers. This is not true. Any registers that +can hold integers can safely @emph{hold} a floating point machine +mode, whether or not floating arithmetic can be done on it in those +registers. + +On some machines, though, the converse is true: fixed-point machine +modes may not go in floating registers. This is true if the floating +registers normalize any value stored in them, because storing a +non-floating value there would garble it. In this case, +@code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in +floating registers. But if the floating registers do not automatically +normalize, if you can store any bit pattern in one and retrieve it +unchanged without a trap, then any machine mode may go in a floating +register and this macro should say so. + +The primary significance of special floating registers is rather that +they are the registers acceptable in floating point arithmetic +instructions. However, this is of no concern to +@code{HARD_REGNO_MODE_OK}. You handle it by writing the proper +constraints for those instructions. + +On some machines, the floating registers are especially slow to access, +so that it is better to store a value in a stack frame than in such a +register if floating point arithmetic is not being done. As long as the +floating registers are not in class @code{GENERAL_REGS}, they will not +be used unless some insn's constraint asks for one. + +@item MODES_TIEABLE_P (@var{mode1}, @var{mode2}) +A C expression that is nonzero if it is desirable to choose register +allocation so as to avoid move instructions between a value of mode +@var{mode1} and a value of mode @var{mode2}. + +If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and +@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different +for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, +@var{mode2})} must be zero. + +@item PC_REGNUM +If the program counter has a register number, define this as that +register number. Otherwise, do not define it. + +@item STACK_POINTER_REGNUM +The register number of the stack pointer register, which must also be +a fixed register according to @code{FIXED_REGISTERS}. On many +machines, the hardware determines which register this is. + +@item FRAME_POINTER_REGNUM +The register number of the frame pointer register, which is used to +access automatic variables in the stack frame. On some machines, the +hardware determines which register this is. On other machines, you +can choose any register you wish for this purpose. + +@item FRAME_POINTER_REQUIRED +A C expression which is nonzero if a function must have and use a frame +pointer. This expression is evaluated twice: at the beginning of +generating RTL, and in the reload pass. If its value is nonzero at +either time, then the function will have a frame pointer. + +The expression can in principle examine the current function and decide +according to the facts, but on most machines the constant 0 or the +constant 1 suffices. Use 0 when the machine allows code to be generated +with no frame pointer, and doing so saves some time or space. Use 1 +when there is no possible advantage to avoiding a frame pointer. + +In certain cases, the compiler does not know how to produce valid code +without a frame pointer. The compiler recognizes those cases and +automatically gives the function a frame pointer regardless of what +@code{FRAME_POINTER_REQUIRED} says. You don't need to worry about +them.@refill + +In a function that does not require a frame pointer, the frame pointer +register can be allocated for ordinary usage, unless you mark it as a +fixed register. See @code{FIXED_REGISTERS} for more information. + +@item ARG_POINTER_REGNUM +The register number of the arg pointer register, which is used to +access the function's argument list. On some machines, this is the +same as the frame pointer register. On some machines, the hardware +determines which register this is. On other machines, you can choose +any register you wish for this purpose. If this is not the same +register as the frame pointer register, then you must mark it as a +fixed register according to @code{FIXED_REGISTERS}. + +@item STATIC_CHAIN_REGNUM +The register number used for passing a function's static chain +pointer. This is needed for languages such as Pascal and Algol where +functions defined within other functions can access the local +variables of the outer functions; it is not currently used because C +does not provide this feature, but you must define the macro. + +The static chain register need not be a fixed register. + +@item STRUCT_VALUE_REGNUM +When a function's value's mode is @code{BLKmode}, the value is not +returned according to @code{FUNCTION_VALUE}. Instead, the caller +passes the address of a block of memory in which the value should be +stored. + +If this value is passed in a register, then @code{STRUCT_VALUE_REGNUM} +should be the number of that register. + +@item STRUCT_VALUE +If the structure value address is not passed in a register, define +@code{STRUCT_VALUE} as an expression returning an RTX for the place +where the address is passed. If it returns a @code{mem} RTX, the +address is passed as an ``invisible'' first argument. + +@item STRUCT_VALUE_INCOMING_REGNUM +On some architectures the place where the structure value address +is found by the called function is not the same place that the +caller put it. This can be due to register windows, or it could +be because the function prologue moves it to a different place. + +If the incoming location of the structure value address is in a +register, define this macro as the register number. + +@item STRUCT_VALUE_INCOMING +If the incoming location is not a register, define +@code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the +called function should find the value. If it should find the value on +the stack, define this to create a @code{mem} which refers to the +frame pointer. If the value is a @code{mem}, the compiler assumes it +is for an invisible first argument, and leaves space for it when +finding the first real argument. + +@item REG_ALLOC_ORDER +If defined, an initializer for a vector of integers, containing the +numbers of hard registers in the order in which the GNU CC should +prefer to use them (from most preferred to least). + +If this macro is not defined, registers are used lowest numbered first +(all else being equal). + +One use of this macro is on the 360, where the highest numbered +registers must always be saved and the save-multiple-registers +instruction supports only sequences of consecutive registers. This +macro is defined to cause the highest numbered allocatable registers +to be used first. +@end table + +@node Register Classes, Stack Layout, Registers, Machine Macros +@section Register Classes + +On many machines, the numbered registers are not all equivalent. +For example, certain registers may not be allowed for indexed addressing; +certain registers may not be allowed in some instructions. These machine +restrictions are described to the compiler using @dfn{register classes}. + +You define a number of register classes, giving each one a name and saying +which of the registers belong to it. Then you can specify register classes +that are allowed as operands to particular instruction patterns. + +In general, each register will belong to several classes. In fact, one +class must be named @code{ALL_REGS} and contain all the registers. Another +class must be named @code{NO_REGS} and contain no registers. Often the +union of two classes will be another class; however, this is not required. + +One of the classes must be named @code{GENERAL_REGS}. There is nothing +terribly special about the name, but the operand constraint letters +@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is +the same as @code{ALL_REGS}, just define it as a macro which expands +to @code{ALL_REGS}. + +The way classes other than @code{GENERAL_REGS} are specified in operand +constraints is through machine-dependent operand constraint letters. +You can define such letters to correspond to various classes, then use +them in operand constraints. + +You should define a class for the union of two classes whenever some +instruction allows both classes. For example, if an instruction allows +either a floating-point (coprocessor) register or a general register for a +certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} +which includes both of them. Otherwise you will get suboptimal code. + +You must also specify certain redundant information about the register +classes: for each class, which classes contain it and which ones are +contained in it; for each pair of classes, the largest class contained +in their union. + +When a value occupying several consecutive registers is expected in a +certain class, all the registers used must belong to that class. +Therefore, register classes cannot be used to enforce a requirement for +a register pair to start with an even-numbered register. The way to +specify this requirement is with @code{HARD_REGNO_MODE_OK}. + +Register classes used for input-operands of bitwise-and or shift +instructions have a special requirement: each such class must have, for +each fixed-point machine mode, a subclass whose registers can transfer that +mode to or from memory. For example, on some machines, the operations for +single-byte values (@code{QImode}) are limited to certain registers. When +this is so, each register class that is used in a bitwise-and or shift +instruction must have a subclass consisting of registers from which +single-byte values can be loaded or stored. This is so that +@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. + +@table @code +@item enum reg_class +An enumeral type that must be defined with all the register class names +as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS} +must be the last register class, followed by one more enumeral value, +@code{LIM_REG_CLASSES}, which is not a register class but rather +tells how many classes there are. + +Each register class has a number, which is the value of casting +the class name to type @code{int}. The number serves as an index +in many of the tables described below. + +@item N_REG_CLASSES +The number of distinct register classes, defined as follows: + +@example +#define N_REG_CLASSES (int) LIM_REG_CLASSES +@end example + +@item REG_CLASS_NAMES +An initializer containing the names of the register classes as C string +constants. These names are used in writing some of the debugging dumps. + +@item REG_CLASS_CONTENTS +An initializer containing the contents of the register classes, as integers +which are bit masks. The @var{n}th integer specifies the contents of class +@var{n}. The way the integer @var{mask} is interpreted is that +register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. + +When the machine has more than 32 registers, an integer does not suffice. +Then the integers are replaced by sub-initializers, braced groupings containing +several integers. Each sub-initializer must be suitable as an initializer +for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. + +@item REGNO_REG_CLASS (@var{regno}) +A C expression whose value is a register class containing hard register +@var{regno}. In general there is more that one such class; choose a class +which is @dfn{minimal}, meaning that no smaller class also contains the +register. + +@item BASE_REG_CLASS +A macro whose definition is the name of the class to which a valid +base register must belong. A base register is one used in an address +which is the register value plus a displacement. + +@item INDEX_REG_CLASS +A macro whose definition is the name of the class to which a valid +index register must belong. An index register is one used in an +address where its value is either multiplied by a scale factor or +added to another register (as well as added to a displacement). + +@item REG_CLASS_FROM_LETTER (@var{char}) +A C expression which defines the machine-dependent operand constraint +letters for register classes. If @var{char} is such a letter, the +value should be the register class corresponding to it. Otherwise, +the value should be @code{NO_REGS}. + +@item REGNO_OK_FOR_BASE_P (@var{num}) +A C expression which is nonzero if register number @var{num} is +suitable for use as a base register in operand addresses. It may be +either a suitable hard register or a pseudo register that has been +allocated such a hard register. + +@item REGNO_OK_FOR_INDEX_P (@var{num}) +A C expression which is nonzero if register number @var{num} is +suitable for use as an index register in operand addresses. It may be +either a suitable hard register or a pseudo register that has been +allocated such a hard register. + +The difference between an index register and a base register is that +the index register may be scaled. If an address involves the sum of +two registers, neither one of them scaled, then either one may be +labeled the ``base'' and the other the ``index''; but whichever +labeling is used must fit the machine's constraints of which registers +may serve in each capacity. The compiler will try both labelings, +looking for one that is valid, and will reload one or both registers +only if neither labeling works. + +@item PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) +A C expression that places additional restrictions on the register class +to use when it is necessary to copy value @var{x} into a register in class +@var{class}. The value is a register class; perhaps @var{class}, or perhaps +another, smaller class. On many machines, the definition + +@example +#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS +@end example + +@noindent +is safe. + +Sometimes returning a more restrictive class makes better code. For +example, on the 68000, when @var{x} is an integer constant that is in range +for a @samp{moveq} instruction, the value of this macro is always +@code{DATA_REGS} as long as @var{class} includes the data registers. +Requiring a data register guarantees that a @samp{moveq} will be used. + +If @var{x} is a @code{const_double}, by returning @code{NO_REGS} +you can force @var{x} into a memory constant. This is useful on +certain machines where immediate floating values cannot be loaded into +certain kinds of registers. + +In a shift instruction or a bitwise-and instruction, the mode of @var{x}, +the value being reloaded, may not be the same as the mode of the +instruction's operand. (They will both be fixed-point modes, however.) In +such a case, @var{class} may not be a safe value to return. @var{class} is +certainly valid for the instruction, but it may not be valid for reloading +@var{x}. This problem can occur on machines such as the 68000 and 80386 +where some registers can handle full-word values but cannot handle +single-byte values. + +On such machines, this macro must examine the mode of @var{x} and return a +subclass of @var{class} which can handle loads and stores of that mode. On +the 68000, where address registers cannot handle @code{QImode}, if @var{x} +has @code{QImode} then you must return @code{DATA_REGS}. If @var{class} is +@code{ADDR_REGS}, then there is no correct value to return; but the shift +and bitwise-and instructions don't use @code{ADDR_REGS}, so this fatal case +never arises. + +@item CLASS_MAX_NREGS (@var{class}, @var{mode}) +A C expression for the maximum number of consecutive registers +of class @var{class} needed to hold a value of mode @var{mode}. + +This is closely related to the macro @code{HARD_REGNO_NREGS}. +In fact, the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} +should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, @var{mode})} +for all @var{regno} values in the class @var{class}. + +This macro helps control the handling of multiple-word values +in the reload pass. +@end table + +Two other special macros describe which constants fit which constraint +letters. + +@table @code +@item CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) +A C expression that defines the machine-dependent operand constraint letters +that specify particular ranges of integer values. If @var{c} is one +of those letters, the expression should check that @var{value}, an integer, +is in the appropriate range and return 1 if so, 0 otherwise. If @var{c} is +not one of those letters, the value should be 0 regardless of @var{value}. + +@item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) +A C expression that defines the machine-dependent operand constraint +letters that specify particular ranges of floating values. If @var{c} is +one of those letters, the expression should check that @var{value}, an RTX +of code @code{const_double}, is in the appropriate range and return 1 if +so, 0 otherwise. If @var{c} is not one of those letters, the value should +be 0 regardless of @var{value}. +@end table + +@node Stack Layout, Library Calls, Register Classes, Machine Macros +@section Describing Stack Layout + +@table @code +@item STACK_GROWS_DOWNWARD +Define this macro if pushing a word onto the stack moves the stack +pointer to a smaller address. + +When we say, ``define this macro if @dots{},'' it means that the +compiler checks this macro only with @code{#ifdef} so the precise +definition used does not matter. + +@item FRAME_GROWS_DOWNWARD +Define this macro if the addresses of local variable slots are at negative +offsets from the frame pointer. + +@item STARTING_FRAME_OFFSET +Offset from the frame pointer to the first local variable slot to be allocated. + +If @code{FRAME_GROWS_DOWNWARD}, the next slot's offset is found by +subtracting the length of the first slot from @code{STARTING_FRAME_OFFSET}. +Otherwise, it is found by adding the length of the first slot to +the value @code{STARTING_FRAME_OFFSET}. + +@item PUSH_ROUNDING (@var{npushed}) +A C expression that is the number of bytes actually pushed onto the +stack when an instruction attempts to push @var{npushed} bytes. + +If the target machine does not have a push instruction, do not define +this macro. That directs GNU CC to use an alternate strategy: to +allocate the entire argument block and then store the arguments into +it. + +On some machines, the definition + +@example +#define PUSH_ROUNDING(BYTES) (BYTES) +@end example + +@noindent +will suffice. But on other machines, instructions that appear +to push one byte actually push two bytes in an attempt to maintain +alignment. Then the definition should be + +@example +#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) +@end example + +@item FIRST_PARM_OFFSET (@var{fundecl}) +Offset from the argument pointer register to the first argument's +address. On some machines it may depend on the data type of the +function. (In the next version of GNU CC, the argument will be +changed to the function data type rather than its declaration.) + +@item FIRST_PARM_CALLER_OFFSET (@var{fundecl}) +Define this macro on machines where register parameters have shadow +locations on the stack, at addresses below the nominal parameter. +This matters because certain arguments cannot be passed on the stack. +On these machines, such arguments must be stored into the shadow +locations. + +This macro should expand into a C expression whose value is the offset +of the first parameter's shadow location from the nominal stack +pointer value. (That value is itself computed by adding the value of +@code{STACK_POINTER_OFFSET} to the stack pointer register.) + +@item REG_PARM_STACK_SPACE +Define this macro if functions should assume that stack space has been +allocated for arguments even when their values are passed in +registers. + +The actual allocation of such space would be done either by +the call instruction or by the function prologue, or by +defining @code{FIRST_PARM_CALLER_OFFSET}. + +@item STACK_ARGS_ADJUST (@var{size}) +Define this macro if the machine requires padding on the stack for +certain function calls. This is padding on a per-function-call basis, +not padding for individual arguments. + +The argument @var{size} will be a C variable of type @code{struct +arg_data} which contains two fields, an integer named @code{constant} +and an RTX named @code{var}. These together represent a size measured +in bytes which is the sum of the integer and the RTX. Most of the +time @code{var} is 0, which means that the size is simply the integer. + +The definition should be a C statement or compound statement +which alters the variable supplied in whatever way you wish. + +Note that the value you leave in the variable @code{size} will +ultimately be rounded up to a multiple of @code{STACK_BOUNDARY} bits. + +This macro is not fully implemented for machines which have push +instructions (i.e., on which @code{PUSH_ROUNDING} is defined). + +@item RETURN_POPS_ARGS (@var{funtype}) +A C expression that should be 1 if a function pops its own arguments +on returning, or 0 if the function pops no arguments and the caller +must therefore pop them all after the function returns. + +@var{funtype} is a C variable whose value is a tree node that +describes the function in question. Normally it is a node of type +@code{FUNCTION_TYPE} that describes the data type of the function. +From this it is possible to obtain the data types of the value and +arguments (if known). + +When a call to a library function is being considered, @var{funtype} +will contain an identifier node for the library function. Thus, if +you need to distinguish among various library functions, you can do so +by their names. Note that ``library function'' in this context means +a function used to perform arithmetic, whose name is known specially +in the compiler and was not mentioned in the C code being compiled. + +On the Vax, all functions always pop their arguments, so the +definition of this macro is 1. On the 68000, using the standard +calling convention, no functions pop their arguments, so the value of +the macro is always 0 in this case. But an alternative calling +convention is available in which functions that take a fixed number of +arguments pop them but other functions (such as @code{printf}) pop +nothing (the caller pops all). When this convention is in use, +@var{funtype} is examined to determine whether a function takes a +fixed number of arguments. + +When this macro returns nonzero, the macro @code{FRAME_POINTER_REQUIRED} +must also return nonzero for proper operation. + +@item FUNCTION_VALUE (@var{valtype}, @var{func}) +A C expression to create an RTX representing the place where a +function returns a value of data type @var{valtype}. @var{valtype} is +a tree node representing a data type. Write @code{TYPE_MODE +(@var{valtype})} to get the machine mode used to represent that type. +On many machines, only the mode is relevant. (Actually, on most +machines, scalar values are returned in the same place regardless of +mode).@refill + +If the precise function being called is known, @var{func} is a tree +node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null +pointer. This makes it possible to use a different value-returning +convention for specific functions when all their calls are +known.@refill + +@item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) +Define this macro if the target machine has ``register windows'' +so that the register in which a function returns its value is not +the same as the one in which the caller sees the value. + +For such machines, @code{FUNCTION_VALUE} computes the register in +which the caller will see the value, and +@code{FUNCTION_OUTGOING_VALUE} should be defined in a similar fashion +to tell the function where to put the value.@refill + +If @code{FUNCTION_OUTGOING_VALUE} is not defined, +@code{FUNCTION_VALUE} serves both purposes.@refill + +@item RETURN_IN_MEMORY (@var{type}) +A C expression which can inhibit the returning of certain function +values in registers, based on the type of value. A nonzero value says +to return the function value in memory, just as large structures are +always returned. Here @var{type} will be a C expression of type +@code{tree}, representing the data type of the value. + +Note that values of mode @code{BLKmode} are returned in memory +regardless of this macro. Also, the option @samp{-fpcc-struct-return} +takes effect regardless of this macro. On most systems, it is +possible to leave the macro undefined; this causes a default +definition to be used, whose value is the constant 0. + +@item LIBCALL_VALUE (@var{mode}) +A C expression to create an RTX representing the place where a library +function returns a value of mode @var{mode}. If the precise function +being called is known, @var{func} is a tree node +(@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null +pointer. This makes it possible to use a different value-returning +convention for specific functions when all their calls are +known.@refill + +Note that ``library function'' in this context means a compiler +support routine, used to perform arithmetic, whose name is known +specially by the compiler and was not mentioned in the C code being +compiled. + +@item FUNCTION_VALUE_REGNO_P (@var{regno}) +A C expression that is nonzero if @var{regno} is the number of a hard +register in which the values of called function may come back. + +A register whose use for returning values is limited to serving as the +second of a pair (for a value of type @code{double}, say) need not be +recognized by this macro. So for most machines, this definition +suffices: + +@example +#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) +@end example + +If the machine has register windows, so that the caller and the called +function use different registers for the return value, this macro +should recognize only the caller's register numbers. + +@item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) +A C expression that controls whether a function argument is passed +in a register, and which register. + +The arguments are @var{cum}, which summarizes all the previous +arguments; @var{mode}, the machine mode of the argument; @var{type}, +the data type of the argument as a tree node or 0 if that is not known +(which happens for C support library functions); and @var{named}, +which is 1 for an ordinary argument and 0 for nameless arguments that +correspond to @samp{@dots{}} in the called function's prototype. + +The value of the expression should either be a @code{reg} RTX for the +hard register in which to pass the argument, or zero to pass the +argument on the stack. + +For the Vax and 68000, where normally all arguments are pushed, zero +suffices as a definition. + +The usual way to make the ANSI library @file{stdarg.h} work on a machine +where some arguments are usually passed in registers, is to cause +nameless arguments to be passed on the stack instead. This is done +by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0. + +@item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) +Define this macro if the target machine has ``register windows'', so +that the register in which a function sees an arguments is not +necessarily the same as the one in which the caller passed the +argument. + +For such machines, @code{FUNCTION_ARG} computes the register in which +the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should +be defined in a similar fashion to tell the function being called +where the arguments will arrive. + +If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG} +serves both purposes.@refill + +@item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named}) +A C expression for the number of words, at the beginning of an +argument, must be put in registers. The value must be zero for +arguments that are passed entirely in registers or that are entirely +pushed on the stack. + +On some machines, certain arguments must be passed partially in +registers and partially in memory. On these machines, typically the +first @var{n} words of arguments are passed in registers, and the rest +on the stack. If a multi-word argument (a @code{double} or a +structure) crosses that boundary, its first few words must be passed +in registers and the rest must be pushed. This macro tells the +compiler when this occurs, and how many of the words should go in +registers. + +@code{FUNCTION_ARG} for these arguments should return the first +register to be used by the caller for this argument; likewise +@code{FUNCTION_INCOMING_ARG}, for the called function. + +@item CUMULATIVE_ARGS +A C type for declaring a variable that is used as the first argument +of @code{FUNCTION_ARG} and other related values. For some target +machines, the type @code{int} suffices and can hold the number of +bytes of argument so far. + +@item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}) +A C statement (sans semicolon) for initializing the variable @var{cum} +for the state at the beginning of the argument list. The variable has +type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node +for the data type of the function which will receive the args, or 0 +if the args are to a compiler support library function. + +@item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) +A C statement (sans semicolon) to update the summarizer variable +@var{cum} to advance past an argument in the argument list. The +values @var{mode}, @var{type} and @var{named} describe that argument. +Once this is done, the variable @var{cum} is suitable for analyzing +the @emph{following} argument with @code{FUNCTION_ARG}, etc.@refill + +@item FUNCTION_ARG_REGNO_P (@var{regno}) +A C expression that is nonzero if @var{regno} is the number of a hard +register in which function arguments are sometimes passed. This does +@emph{not} include implicit arguments such as the static chain and +the structure-value address. On many machines, no registers can be +used for this purpose since all function arguments are pushed on the +stack. + +@item FUNCTION_ARG_PADDING (@var{mode}, @var{size}) +If defined, a C expression which determines whether, and in which direction, +to pad out an argument with extra space. The value should be of type +@code{enum direction}: either @code{upward} to pad above the argument, +@code{downward} to pad below, or @code{none} to inhibit padding. + +The argument @var{size} is an RTX which describes the size of the +argument, in bytes. It should be used only if @var{mode} is +@code{BLKmode}. Otherwise, @var{size} is 0. + +This macro does not control the @emph{amount} of padding; that is +always just enough to reach the next multiple of @code{PARM_BOUNDARY}. + +This macro has a default definition which is right for most systems. +For little-endian machines, the default is to pad upward. For +big-endian machines, the default is to pad downward for an argument of +constant size shorter than an @code{int}, and upward otherwise. + +@item FUNCTION_PROLOGUE (@var{file}, @var{size}) +A C compound statement that outputs the assembler code for entry to a +function. The prologue is responsible for setting up the stack frame, +initializing the frame pointer register, saving registers that must be +saved, and allocating @var{size} additional bytes of storage for the +local variables. @var{size} is an integer. @var{file} is a stdio +stream to which the assembler code should be output. + +The label for the beginning of the function need not be output by this +macro. That has already been done when the macro is run. + +To determine which registers to save, the macro can refer to the array +@code{regs_ever_live}: element @var{r} is nonzero if hard register +@var{r} is used anywhere within the function. This implies the +function prologue should save register @var{r}, but not if it is one +of the call-used registers. + +On machines where functions may or may not have frame-pointers, the +function entry code must vary accordingly; it must set up the frame +pointer if one is wanted, and not otherwise. To determine whether a +frame pointer is in wanted, the macro can refer to the variable +@code{frame_pointer_needed}. The variable's value will be 1 at run +time in a function that needs a frame pointer. + +On machines where an argument may be passed partly in registers and +partly in memory, this macro must examine the variable +@code{current_function_pretend_args_size}, and allocate that many bytes +of uninitialized space on the stack just underneath the first argument +arriving on the stack. (This may not be at the very end of the stack, +if the calling sequence has pushed anything else since pushing the stack +arguments. But usually, on such machines, nothing else has been pushed +yet, because the function prologue itself does all the pushing.) + +@item FUNCTION_PROFILER (@var{file}, @var{labelno}) +A C statement or compound statement to output to @var{file} some +assembler code to call the profiling subroutine @code{mcount}. +Before calling, the assembler code must load the address of a +counter variable into a register where @code{mcount} expects to +find the address. The name of this variable is @samp{LP} followed +by the number @var{labelno}, so you would generate the name using +@samp{LP%d} in a @code{fprintf}. + +The details of how the address should be passed to @code{mcount} are +determined by your operating system environment, not by GNU CC. To +figure them out, compile a small program for profiling using the +system's installed C compiler and look at the assembler code that +results. + +@item FUNCTION_BLOCK_PROFILER (@var{file}, @var{labelno}) +A C statement or compound statement to output to @var{file} some +assembler code to initialize basic-block profiling for the current +object module. This code should call the subroutine +@code{__bb_init_func} once per object module, passing it as its sole +argument the address of a block allocated in the object module. + +The name of the block is a local symbol made with this statement: + +@example +ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 0); +@end example + +Of course, since you are writing the definition of +@code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you +can take a short cut in the definition of this macro and use the name +that you know will result. + +The first word of this block is a flag which will be nonzero if the +object module has already been initialized. So test this word first, +and do not call @code{__bb_init_func} if the flag is nonzero. + +@item BLOCK_PROFILER (@var{file}, @var{blockno}) +A C statement or compound statement to increment the count associated +with the basic block number @var{blockno}. Basic blocks are numbered +separately from zero within each compilation. The count associated +with block number @var{blockno} is at index @var{blockno} in a vector +of words; the name of this array is a local symbol made with this +statement: + +@example +ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 2); +@end example + +Of course, since you are writing the definition of +@code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you +can take a short cut in the definition of this macro and use the name +that you know will result. + +@item EXIT_IGNORE_STACK +Define this macro as a C expression that is nonzero if the return +instruction or the function epilogue ignores the value of the stack +pointer; in other words, if it is safe to delete an instruction to +adjust the stack pointer before a return from the function. + +Note that this macro's value is relevant only for functions for which +frame pointers are maintained. It is never safe to delete a final +stack adjustment in a function that has no frame pointer, and the +compiler knows this regardless of @code{EXIT_IGNORE_STACK}. + +@item FUNCTION_EPILOGUE (@var{file}, @var{size}) +A C compound statement that outputs the assembler code for exit from a +function. The epilogue is responsible for restoring the saved +registers and stack pointer to their values when the function was +called, and returning control to the caller. This macro takes the +same arguments as the macro @code{FUNCTION_PROLOGUE}, and the +registers to restore are determined from @code{regs_ever_live} and +@code{CALL_USED_REGISTERS} in the same way. + +On some machines, there is a single instruction that does all the work +of returning from the function. On these machines, give that +instruction the name @samp{return} and do not define the macro +@code{FUNCTION_EPILOGUE} at all. + +Do not define a pattern named @samp{return} if you want the +@code{FUNCTION_EPILOGUE} to be used. If you want the target switches +to control whether return instructions or epilogues are used, define a +@samp{return} pattern with a validity condition that tests the target +switches appropriately. If the @samp{return} pattern's validity +condition is false, epilogues will be used. + +On machines where functions may or may not have frame-pointers, the +function exit code must vary accordingly. Sometimes the code for +these two cases is completely different. To determine whether a frame +pointer is in wanted, the macro can refer to the variable +@code{frame_pointer_needed}. The variable's value will be 1 at run +time in a function that needs a frame pointer. + +On some machines, some functions pop their arguments on exit while +others leave that for the caller to do. For example, the 68020 when +given @samp{-mrtd} pops arguments in functions that take a fixed +number of arguments. + +Your definition of the macro @code{RETURN_POPS_ARGS} decides which +functions pop their own arguments. @code{FUNCTION_EPILOGUE} needs to +know what was decided. The variable @code{current_function_pops_args} +is nonzero if the function should pop its own arguments. If so, use +the variable @code{current_function_args_size} as the number of bytes +to pop. + +@item FIX_FRAME_POINTER_ADDRESS (@var{addr}, @var{depth}) +A C compound statement to alter a memory address that uses the frame +pointer register so that it uses the stack pointer register instead. +This must be done in the instructions that load parameter values into +registers, when the reload pass determines that a frame pointer is not +necessary for the function. @var{addr} will be a C variable name, and +the updated address should be stored in that variable. @var{depth} +will be the current depth of stack temporaries (number of bytes of +arguments currently pushed). The change in offset between a +frame-pointer-relative address and a stack-pointer-relative address +must include @var{depth}. + +Even if your machine description specifies there will always be a +frame pointer in the frame pointer register, you must still define +@code{FIX_FRAME_POINTER_ADDRESS}, but the definition will never be +executed at run time, so it may be empty. + +@item LONGJMP_RESTORE_FROM_STACK +Define this macro if the @code{longjmp} function restores registers +from the stack frames, rather than from those saved specifically by +@code{setjmp}. Certain quantities must not be kept in registers +across a call to @code{setjmp} on such machines. +@end table + +@node Library Calls, Addressing Modes, Stack Layout, Machine Macros +@section Implicit Use of Library Routines + +@table @code +@item MULSI3_LIBCALL +A C string constant giving the name of the function to call for +multiplication of one signed full-word by another. If you do not +define this macro, the default name is used, which is @code{__mulsi3}, +a function defined in @file{gnulib}. + +@item UMULSI3_LIBCALL +A C string constant giving the name of the function to call for +multiplication of one unsigned full-word by another. If you do not +define this macro, the default name is used, which is +@code{__umulsi3}, a function defined in @file{gnulib}. + +@item DIVSI3_LIBCALL +A C string constant giving the name of the function to call for +division of one signed full-word by another. If you do not define +this macro, the default name is used, which is @code{__divsi3}, a +function defined in @file{gnulib}. + +@item UDIVSI3_LIBCALL +A C string constant giving the name of the function to call for +division of one unsigned full-word by another. If you do not define +this macro, the default name is used, which is @code{__udivsi3}, a +function defined in @file{gnulib}. + +@item MODSI3_LIBCALL +A C string constant giving the name of the function to call for the +remainder in division of one signed full-word by another. If you do +not define this macro, the default name is used, which is +@code{__modsi3}, a function defined in @file{gnulib}. + +@item UMODSI3_LIBCALL +A C string constant giving the name of the function to call for the +remainder in division of one unsigned full-word by another. If you do +not define this macro, the default name is used, which is +@code{__umodsi3}, a function defined in @file{gnulib}. + +@item TARGET_MEM_FUNCTIONS +Define this macro if GNU CC should generate calls to the System V +(and ANSI C) library functions @code{memcpy} and @code{memset} +rather than the BSD functions @code{bcopy} and @code{bzero}. + +@item GNULIB_NEEDS_DOUBLE +Define this macro if only @code{float} arguments cannot be passed to +library routines (so they must be converted to @code{double}). This +macro affects both how library calls are generated and how the library +routines in @file{gnulib.c} accept their arguments. It is useful on +machines where floating and fixed point arguments are passed +differently, such as the i860. +@end table + +@node Addressing Modes, Delayed Branch, Library Calls, Machine Macros +@section Addressing Modes + +@table @code +@item HAVE_POST_INCREMENT +Define this macro if the machine supports post-increment addressing. + +@item HAVE_PRE_INCREMENT +@itemx HAVE_POST_DECREMENT +@itemx HAVE_PRE_DECREMENT +Similar for other kinds of addressing. + +@item CONSTANT_ADDRESS_P (@var{x}) +A C expression that is 1 if the RTX @var{x} is a constant whose value +is an integer. This includes integers whose values are not explicitly +known, such as @code{symbol_ref} and @code{label_ref} expressions and +@code{const} arithmetic expressions. + +On most machines, this can be defined as @code{CONSTANT_P (@var{x})}, +but a few machines are more restrictive in which constant addresses +are supported. + +@item MAX_REGS_PER_ADDRESS +A number, the maximum number of registers that can appear in a valid +memory address. Note that it is up to you to specify a value equal to +the maximum number that @code{go_if_legitimate_address} would ever +accept. + +@item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) +A C compound statement with a conditional @code{goto @var{label};} +executed if @var{x} (an RTX) is a legitimate memory address on the +target machine for a memory operand of mode @var{mode}. + +It usually pays to define several simpler macros to serve as +subroutines for this one. Otherwise it may be too complicated to +understand. + +This macro must exist in two variants: a strict variant and a +non-strict one. The strict variant is used in the reload pass. It +must be defined so that any pseudo-register that has not been +allocated a hard register is considered a memory reference. In +contexts where some kind of register is required, a pseudo-register +with no hard register must be rejected. + +The non-strict variant is used in other passes. It must be defined to +accept all pseudo-registers in every context where some kind of +register is required. + +Compiler source files that want to use the strict variant of this +macro define the macro @code{REG_OK_STRICT}. You should use an +@code{#ifdef REG_OK_STRICT} conditional to define the strict variant +in that case and the non-strict variant otherwise. + +Typically among the subroutines used to define +@code{GO_IF_LEGITIMATE_ADDRESS} are subroutines to check for +acceptable registers for various purposes (one for base registers, one +for index registers, and so on). Then only these subroutine macros +need have two variants; the higher levels of macros may be the same +whether strict or not.@refill + +Normally, constant addresses which are the sum of a @code{symbol_ref} +and an integer are stored inside a @code{const} RTX to mark them as +constant. Therefore, there is no need to recognize such sums as +legitimate addresses. + +Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant +sums that are not marked with @code{const}. It assumes that a naked +@code{plus} indicates indexing. If so, then you @emph{must} reject such +naked constant sums as illegitimate addresses, so that none of them will +be given to @code{PRINT_OPERAND_ADDRESS}.@refill + +@item REG_OK_FOR_BASE_P (@var{x}) +A C expression that is nonzero if @var{x} (assumed to be a @code{reg} +RTX) is valid for use as a base register. For hard registers, it +should always accept those which the hardware permits and reject the +others. Whether the macro accepts or rejects pseudo registers must be +controlled by @code{REG_OK_STRICT} as described above. This usually +requires two variant definitions, of which @code{REG_OK_STRICT} +controls the one actually used. + +@item REG_OK_FOR_INDEX_P (@var{x}) +A C expression that is nonzero if @var{x} (assumed to be a @code{reg} +RTX) is valid for use as an index register. + +The difference between an index register and a base register is that +the index register may be scaled. If an address involves the sum of +two registers, neither one of them scaled, then either one may be +labeled the ``base'' and the other the ``index''; but whichever +labeling is used must fit the machine's constraints of which registers +may serve in each capacity. The compiler will try both labelings, +looking for one that is valid, and will reload one or both registers +only if neither labeling works. + +@item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) +A C compound statement that attempts to replace @var{x} with a valid +memory address for an operand of mode @var{mode}. @var{win} will be a +C statement label elsewhere in the code; the macro definition may use + +@example +GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win}); +@end example + +@noindent +to avoid further processing if the address has become legitimate. + +@var{x} will always be the result of a call to @code{break_out_memory_refs}, +and @var{oldx} will be the operand that was given to that function to produce +@var{x}. + +The code generated by this macro should not alter the substructure of +@var{x}. If it transforms @var{x} into a more legitimate form, it +should assign @var{x} (which will always be a C variable) a new value. + +It is not necessary for this macro to come up with a legitimate +address. The compiler has standard ways of doing so in all cases. In +fact, it is safe for this macro to do nothing. But often a +machine-dependent strategy can generate better code. + +@item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) +A C statement or compound statement with a conditional @code{goto +@var{label};} executed if memory address @var{x} (an RTX) can have +different meanings depending on the machine mode of the memory +reference it is used for. + +Autoincrement and autodecrement addresses typically have mode-dependent +effects because the amount of the increment or decrement is the size +of the operand being addressed. Some machines have other mode-dependent +addresses. Many RISC machines have no mode-dependent addresses. + +You may assume that @var{addr} is a valid address for the machine. + +@item LEGITIMATE_CONSTANT_P (@var{x}) +A C expression that is nonzero if @var{x} is a legitimate constant for +an immediate operand on the target machine. You can assume that +either @var{x} is a @code{const_double} or it satisfies +@code{CONSTANT_P}, so you need not check these things. In fact, +@samp{1} is a suitable definition for this macro on machines where any +@code{const_double} is valid and anything @code{CONSTANT_P} is valid.@refill +@end table + +@node Delayed Branch, Condition Code, Addressing Modes, Machine Macros +@section Parameters for Delayed Branch Optimization + +@table @code +@item HAVE_DELAYED_BRANCH +Define this macro if the target machine has delayed branches, that is, +a branch does not take effect immediately, and the actual branch +instruction may be followed by one or more instructions that will be +issued before the PC is actually changed. + +If defined, this allows a special scheduling pass to be run after the +second jump optimization to attempt to reorder instructions to exploit +this. Defining this macro also requires the definition of certain +other macros described below. + +@item DBR_SLOTS_AFTER (@var{insn}) +This macro must be defined if @code{HAVE_DELAYED_BRANCH} is defined. +Its definition should be a C expression returning the number of +available delay slots following the instruction(s) output by the +pattern for @var{insn}. The definition of ``slot'' is +machine-dependent, and may denote instructions, bytes, or whatever. + +@item DBR_INSN_SLOTS (@var{insn}) +This macro must be defined if @code{HAVE_DELAYED_BRANCH} is defined. +It should be a C expression returning the number of slots (typically +the number of machine instructions) consumed by @var{insn}. + +You may assume that @var{insn} is truly an insn, not a note, label, +barrier, dispatch table, @code{use}, or @code{clobber}. + +@item DBR_INSN_ELIGIBLE_P (@var{insn}, @var{dinsn}) +A C expression whose value is non-zero if it is legitimate to put +@var{insn} in the delay slot following @var{dinsn}. + +You do not need to take account of data flow considerations in the +definition of this macro, because the delayed branch optimizer always +does that. This macro is needed only when certain insns may not be +placed in certain delay slots for reasons not evident from the RTL +expressions themselves. If there are no such problems, you don't need +to define this macro. + +You may assume that @var{insn} is truly an insn, not a note, label, +barrier, dispatch table, @code{use}, or @code{clobber}. You may +assume that @var{dinsn} is a jump insn with a delay slot. + +@item DBR_OUTPUT_SEQEND(@var{file}) +A C statement, to be executed after all slot-filler instructions have +been output. If necessary, call @code{dbr_sequence_length} to +determine the number of slots filled in a sequence (zero if not +currently outputting a sequence), to decide how many no-ops to output, +or whatever. + +Don't define this macro if it has nothing to do, but it is helpful in +reading assembly output if the extent of the delay sequence is made +explicit (e.g. with white space). + +Note that output routines for instructions with delay slots must be +prepared to deal with not being output as part of a sequence (i.e. +when the scheduling pass is not run, or when no slot fillers could be +found.) The variable @code{final_sequence} is null when not +processing a sequence, otherwise it contains the @code{sequence} rtx +being output. +@end table + +@node Condition Code, Cross-compilation, Delayed Branch, Machine Macros +@section Condition Code Information + +The file @file{conditions.h} defines a variable @code{cc_status} to +describe how the condition code was computed (in case the interpretation of +the condition code depends on the instruction that it was set by). This +variable contains the RTL expressions on which the condition code is +currently based, and several standard flags. + +Sometimes additional machine-specific flags must be defined in the machine +description header file. It can also add additional machine-specific +information by defining @code{CC_STATUS_MDEP}. + +@table @code +@item CC_STATUS_MDEP +C code for a data type which is used for declaring the @code{mdep} +component of @code{cc_status}. It defaults to @code{int}. + +@item CC_STATUS_MDEP_INIT +A C expression to initialize the @code{mdep} field to ``empty''. +The default definition does nothing, since most machines don't use +the field anyway. If you want to use the field, you should probably +define this macro to initialize it. + +@item NOTICE_UPDATE_CC (@var{exp}, @var{insn}) +A C compound statement to set the components of @code{cc_status} +appropriately for an insn @var{insn} whose body is @var{exp}. It is +this macro's responsibility to recognize insns that set the condition +code as a byproduct of other activity as well as those that explicitly +set @code{(cc0)}. + +If there are insn that do not set the condition code but do alter +other machine registers, this macro must check to see whether they +invalidate the expressions that the condition code is recorded as +reflecting. For example, on the 68000, insns that store in address +registers do not set the condition code, which means that usually +@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such +insns. But suppose that the previous insn set the condition code +based on location @samp{a4@@(102)} and the current insn stores a new +value in @samp{a4}. Although the condition code is not changed by +this, it will no longer be true that it reflects the contents of +@samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter +@code{cc_status} in this case to say that nothing is known about the +condition code value. + +The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal +with the results of peephole optimization: insns whose patterns are +@code{parallel} RTXs containing various @code{reg}, @code{mem} or +constants which are just the operands. The RTL structure of these +insns is not sufficient to indicate what the insns actually do. What +@code{NOTICE_UPDATE_CC} should do when it sees one is just to run +@code{CC_STATUS_INIT}. +@end table + +@node Cross-compilation, Misc, Condition Code, Machine Macros +@section Cross Compilation and Floating-Point Format + +While all modern machines use 2's complement representation for integers, +there are a variety of representations for floating point numbers. This +means that in a cross-compiler the representation of floating point numbers +in the compiled program may be different from that used in the machine +doing the compilation. + +Because different representation systems may offer different amounts of +range and precision, the cross compiler cannot safely use the host +machine's floating point arithmetic. Therefore, floating point constants +must be represented in the target machine's format. This means that the +cross compiler cannot use @code{atof} to parse a floating point constant; +it must have its own special routine to use instead. Also, constant +folding must emulate the target machine's arithmetic (or must not be done +at all). + +The macros in the following table should be defined only if you are cross +compiling between different floating point formats. + +Otherwise, don't define them. Then default definitions will be set up which +use @code{double} as the data type, @code{==} to test for equality, etc. + +You don't need to worry about how many times you use an operand of any +of these macros. The compiler never uses operands which have side effects. + +@table @code +@item REAL_VALUE_TYPE +A macro for the C data type to be used to hold a floating point value +in the target machine's format. Typically this would be a +@code{struct} containing an array of @code{int}. + +@item REAL_VALUES_EQUAL (@var{x}, @var{y}) +A macro for a C expression which compares for equality the two values, +@var{x} and @var{y}, both of type @code{REAL_VALUE_TYPE}. + +@item REAL_VALUES_LESS (@var{x}, @var{y}) +A macro for a C expression which tests whether @var{x} is less than +@var{y}, both values being of type @code{REAL_VALUE_TYPE} and +interpreted as floating point numbers in the target machine's +representation. + +@item REAL_VALUE_LDEXP (@var{x}, @var{scale}) +A macro for a C expression which performs the standard library +function @code{ldexp}, but using the target machine's floating point +representation. Both @var{x} and the value of the expression have +type @code{REAL_VALUE_TYPE}. The second argument, @var{scale}, is an +integer. + +@item REAL_VALUE_ATOF (@var{string}) +A macro for a C expression which converts @var{string}, an expression +of type @code{char *}, into a floating point number in the target +machine's representation. The value has type @code{REAL_VALUE_TYPE}. +@end table + +Define the following additional macros if you want to make floating +point constant folding work while cross compiling. If you don't +define them, cross compilation is still possible, but constant folding +will not happen for floating point values. + +@table @code +@item REAL_ARITHMETIC (@var{output}, @var{code}, @var{x}, @var{y}) +A macro for a C statement which calculates an arithmetic operation of +the two floating point values @var{x} and @var{y}, both of type +@code{REAL_VALUE_TYPE} in the target machine's representation, to +produce a result of the same type and representation which is stored +in @var{output} (which will be a variable). + +The operation to be performed is specified by @var{code}, a tree code +which will always be one of the following: @code{PLUS_EXPR}, +@code{MINUS_EXPR}, @code{MULT_EXPR}, @code{RDIV_EXPR}, +@code{MAX_EXPR}, @code{MIN_EXPR}.@refill + +The expansion of this macro is responsible for checking for overflow. +If overflow happens, the macro expansion should execute the statement +@code{return 0;}, which indicates the inability to perform the +arithmetic operation requested. + +@item REAL_VALUE_NEGATE (@var{x}) +A macro for a C expression which returns the negative of the floating +point value @var{x}. Both @var{x} and the value of the expression +have type @code{REAL_VALUE_TYPE} and are in the target machine's +floating point representation. + +There is no way for this macro to report overflow, since overflow +can't happen in the negation operation. + +@item REAL_VALUE_TO_INT (@var{low}, @var{high}, @var{x}) +A macro for a C expression which converts a floating point value +@var{x} into a double-precision integer which is then stored into +@var{low} and @var{high}, two variables of type @var{int}. + +@item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high}) +A macro for a C expression which converts a double-precision integer +found in @var{low} and @var{high}, two variables of type @var{int}, +into a floating point value which is then stored into @var{x}. +@end table + +@node Misc, Assembler Format, Cross-compilation, Machine Macros +@section Miscellaneous Parameters + +@table @code +@item CASE_VECTOR_MODE +An alias for a machine mode name. This is the machine mode that +elements of a jump-table should have. + +@item CASE_VECTOR_PC_RELATIVE +Define this macro if jump-tables should contain relative addresses. + +@item CASE_DROPS_THROUGH +Define this if control falls through a @code{case} insn when the index +value is out of range. This means the specified default-label is +actually ignored by the @code{case} insn proper. + +@item IMPLICIT_FIX_EXPR +An alias for a tree code that should be used by default for conversion +of floating point values to fixed point. Normally, +@code{FIX_ROUND_EXPR} is used.@refill + +@item FIXUNS_TRUNC_LIKE_FIX_TRUNC +Define this macro if the same instructions that convert a floating +point number to a signed fixed point number also convert validly to an +unsigned one. + +@item EASY_DIV_EXPR +An alias for a tree code that is the easiest kind of division to +compile code for in the general case. It may be +@code{TRUNC_DIV_EXPR}, @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or +@code{ROUND_DIV_EXPR}. These four division operators differ in how +they round the result to an integer. @code{EASY_DIV_EXPR} is used +when it is permissible to use any of those kinds of division and the +choice should be made on the basis of efficiency.@refill + +@item DEFAULT_SIGNED_CHAR +An expression whose value is 1 or 0, according to whether the type +@code{char} should be signed or unsigned by default. The user can +always override this default with the options @samp{-fsigned-char} +and @samp{-funsigned-char}. + +@item SCCS_DIRECTIVE +Define this if the preprocessor should ignore @code{#sccs} directives +and print no error message. + +@item HAVE_VPRINTF +Define this if the library function @code{vprintf} is available on your +system. + +@item MOVE_MAX +The maximum number of bytes that a single instruction can move quickly +from memory to memory. + +@item INT_TYPE_SIZE +A C expression for the size in bits of the type @code{int} on the +target machine. If you don't define this, the default is one word. + +@item SHORT_TYPE_SIZE +A C expression for the size in bits of the type @code{short} on the +target machine. If you don't define this, the default is half a word. +(If this would be less than one storage unit, it is rounded up to one +unit.) + +@item LONG_TYPE_SIZE +A C expression for the size in bits of the type @code{long} on the +target machine. If you don't define this, the default is one word. + +@item LONG_LONG_TYPE_SIZE +A C expression for the size in bits of the type @code{long long} on the +target machine. If you don't define this, the default is two +words. + +@item CHAR_TYPE_SIZE +A C expression for the size in bits of the type @code{char} on the +target machine. If you don't define this, the default is one quarter +of a word. (If this would be less than one storage unit, it is rounded up +to one unit.) + +@item FLOAT_TYPE_SIZE +A C expression for the size in bits of the type @code{float} on the +target machine. If you don't define this, the default is one word. + +@item DOUBLE_TYPE_SIZE +A C expression for the size in bits of the type @code{double} on the +target machine. If you don't define this, the default is two +words. + +@item LONG_DOUBLE_TYPE_SIZE +A C expression for the size in bits of the type @code{long double} on +the target machine. If you don't define this, the default is two +words. + +@item SLOW_BYTE_ACCESS +Define this macro as a C expression which is nonzero if accessing less +than a word of memory (i.e. a @code{char} or a @code{short}) is slow +(requires more than one instruction). + +@item SLOW_ZERO_EXTEND +Define this macro if zero-extension (of a @code{char} or @code{short} +to an @code{int}) can be done faster if the destination is a register +that is known to be zero. + +If you define this macro, you must have instruction patterns that +recognize RTL structures like this: + +@example +(set (strict-low-part (subreg:QI (reg:SI @dots{}) 0)) @dots{}) +@end example + +@noindent +and likewise for @code{HImode}. + +@item SHIFT_COUNT_TRUNCATED +Define this macro if shift instructions ignore all but the lowest few +bits of the shift count. It implies that a sign-extend or zero-extend +instruction for the shift count can be omitted. + +@item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) +A C expression which is nonzero if on this machine it is safe to +``convert'' an integer of @var{inprec} bits to one of @var{outprec} +bits (where @var{outprec} is smaller than @var{inprec}) by merely +operating on it as if it had only @var{outprec} bits. + +On many machines, this expression can be 1. + +@item NO_FUNCTION_CSE +Define this macro if it is as good or better to call a constant +function address than to call an address kept in a register. + +@item PROMOTE_PROTOTYPES +Define this macro if an argument declared as @code{char} or +@code{short} in a prototype should actually be passed as an +@code{int}. In addition to avoiding errors in certain cases of +mismatch, it also makes for better code on certain machines. + +@item STORE_FLAG_VALUE +A C expression for the value stored by a store-flag instruction +(@code{s@var{cond}}) when the condition is true. This is usually 1 or +-1; it is required to be an odd number or a negative number. + +Do not define @code{STORE_FLAG_VALUE} if the machine has no store-flag +instructions. + +@item Pmode +An alias for the machine mode for pointers. Normally the definition +can be + +@example +#define Pmode SImode +@end example + +@item FUNCTION_MODE +An alias for the machine mode used for memory references to functions +being called, in @code{call} RTL expressions. On most machines this +should be @code{QImode}. + +@item INSN_MACHINE_INFO +This macro should expand into a C structure type to use for the +machine-dependent info field specified with the optional last argument +in @code{define_insn} and @code{define_peephole} patterns. For example, +it might expand into @code{struct machine_info}; then it would be up +to you to define this structure in the @file{tm.h} file. + +You do not need to define this macro if you do not write the optional +last argument in any of the patterns in the machine description. + +@item DEFAULT_MACHINE_INFO +This macro should expand into a C initializer to use to initialize +the machine-dependent info for one insn pattern. It is used for patterns +that do not specify the machine-dependent info. + +If you do not define this macro, zero is used. + +@item CONST_COSTS (@var{x}, @var{code}) +A part of a C @code{switch} statement that describes the relative +costs of constant RTL expressions. It must contain @code{case} labels +for expression codes @code{const_int}, @code{const}, @code{symbol_ref}, @code{label_ref} +and @code{const_double}. Each case must ultimately reach a +@code{return} statement to return the relative cost of the use of that +kind of constant value in an expression. The cost may depend on the +precise value of the constant, which is available for examination in +@var{x}. + +@var{code} is the expression code---redundant, since it can be +obtained with @code{GET_CODE (@var{x})}. + +@item DOLLARS_IN_IDENTIFIERS +Define this to be nonzero if the character @samp{$} should be allowed +by default in identifier names. +@end table + +@node Assembler Format,, Misc, Machine Macros +@section Output of Assembler Code + +@table @code +@item ASM_SPEC +A C string constant that tells the GNU CC driver program options to +pass to the assembler. It can also specify how to translate options +you give to GNU CC into options for GNU CC to pass to the assembler. +See the file @file{tm-sun3.h} for an example of this. + +Do not define this macro if it does not need to do anything. + +@item LINK_SPEC +A C string constant that tells the GNU CC driver program options to +pass to the linker. It can also specify how to translate options you +give to GNU CC into options for GNU CC to pass to the linker. + +Do not define this macro if it does not need to do anything. + +@item LIB_SPEC +Another C string constant used much like @code{LINK_SPEC}. The difference +between the two is that @code{LIBS_SPEC} is used at the end of the +command given to the linker. + +If this macro is not defined, a default is provided that +loads the standard C library from the usual place. See @file{gcc.c}. + +@item LIBG_SPEC +Another C string constant used much like @code{LINK_SPEC}. +This controls whether to link @file{libg.a} when debugging. +Some systems expect this; others do not have any @file{libg.a}. + +If this macro is not defined, a default is provided that loads the +@file{libg.a} provided @samp{-g} is specified. See @file{gcc.c}. + +@item STARTFILE_SPEC +Another C string constant used much like @code{LINK_SPEC}. The +difference between the two is that @code{STARTFILE_SPEC} is used at +the very beginning of the command given to the linker. + +If this macro is not defined, a default is provided that loads the +standard C startup file from the usual place. See @file{gcc.c}. + +@item STANDARD_EXEC_PREFIX +Define this macro as a C string constant if you wish to override the +standard choice of @file{/usr/local/lib/gcc-} as the default prefix to +try when searching for the executable files of the compiler. + +The prefix specified by the @samp{-B} option, if any, is tried before +the default prefix. After the default prefix, if the executable is +not found that way, @file{/usr/lib/gcc-} is tried next; then the +directories in your search path for shell commands are searched. + +@item STANDARD_STARTFILE_PREFIX +Define this macro as a C string constant if you wish to override the +standard choice of @file{/usr/local/lib/} as the default prefix to try +when searching for startup files such as @file{crt0.o}. + +In this search, all the prefixes tried for executable files are tried +first. Then comes the default startfile prefix specified by this +macro, followed by the prefixes @file{/lib/} and @file{/usr/lib/} as +last resorts. + +@item ASM_FILE_START (@var{stream}) +A C expression which outputs to the stdio stream @var{stream} +some appropriate text to go at the start of an assembler file. + +Normally this macro is defined to output a line containing +@samp{#NO_APP}, which is a comment that has no effect on most +assemblers but tells the GNU assembler that it can save time by not +checking for certain assembler constructs. + +On systems that use SDB, it is necessary to output certain commands; +see @file{tm-attasm.h}. + +@item ASM_FILE_END (@var{stream}) +A C expression which outputs to the stdio stream @var{stream} +some appropriate text to go at the end of an assembler file. + +If this macro is not defined, the default is to output nothing +special at the end of the file. Most systems don't require any +definition. + +On systems that use SDB, it is necessary to output certain commands; +see @file{tm-attasm.h}. + +@item ASM_IDENTIFY_GCC (@var{file}) +A C statement to output assembler commands which will identify +the object file as having been compiled with GNU CC (or another +GNU compiler). + +If you don't define this macro, the string @samp{gcc_compiled.:} +is output. This string is calculated to define a symbol which, +on BSD systems, will never be defined for any other reason. +GDB checks for the presence of this symbol when reading the +symbol table of an executable. + +On non-BSD systems, you must arrange communication with GDB in +some other fashion. If GDB is not used on your system, you can +define this macro with an empty body. + +@item ASM_APP_ON +A C string constant for text to be output before each @code{asm} +statement or group of consecutive ones. Normally this is +@code{"#APP"}, which is a comment that has no effect on most +assemblers but tells the GNU assembler that it must check the lines +that follow for all valid assembler constructs. + +@item ASM_APP_OFF +A C string constant for text to be output after each @code{asm} +statement or group of consecutive ones. Normally this is +@code{"#NO_APP"}, which tells the GNU assembler to resume making the +time-saving assumptions that are valid for ordinary compiler output. + +@item TEXT_SECTION_ASM_OP +A C string constant for the assembler operation that should precede +instructions and read-only data. Normally @code{".text"} is right. + +@item DATA_SECTION_ASM_OP +A C string constant for the assembler operation to identify the +following data as writable initialized data. Normally @code{".data"} +is right. + +@item EXTRA_SECTIONS +A list of names for sections other than the standard two, which are +@code{in_text} and @code{in_data}. You need not define this macro +on a system with no other sections (that GCC needs to use). + +@item EXTRA_SECTION_FUNCTIONS +One or more functions to be defined in @file{varasm.c}. These +functions should do jobs analogous to those of @code{text_section} and +@code{data_section}, for your additional sections. Do not define this +macro if you do not define @code{EXTRA_SECTIONS}. + +@item SELECT_SECTION (@var{exp}) +A C statement or statements to switch to the appropriate section for +output of @var{exp}. You can assume that @var{exp} is either a +@code{VAR_DECL} node or a constant of some sort. Select the section +by calling @code{text_section} or one of the alternatives for other +sections. + +Do not define this macro if you use only the standard two sections +and put all read-only variables and constants in the text section. + +@item SELECT_RTX_SECTION (@var{mode}, @var{rtx}) +A C statement or statements to switch to the appropriate section for +output of @var{rtx} in mode @var{mode}. You can assume that @var{rtx} +is some kind of constant in RTL. The argument @var{mode} is redundant +except in the case of a @code{const_int} rtx. Select the section by +calling @code{text_section} or one of the alternatives for other +sections. + +Do not define this macro if you use only the standard two sections and +put all constants in the text section. + +@item REGISTER_NAMES +A C initializer containing the assembler's names for the machine +registers, each one as a C string constant. This is what translates +register numbers in the compiler into assembler language. + +@item DBX_REGISTER_NUMBER (@var{regno}) +A C expression that returns the DBX register number for the compiler +register number @var{regno}. In simple cases, the value of this +expression may be @var{regno} itself. But sometimes there are some +registers that the compiler knows about and DBX does not, or vice +versa. In such cases, some register may need to have one number in +the compiler and another for DBX. + +@item DBX_DEBUGGING_INFO +Define this macro if GNU CC should produce debugging output for DBX +in response to the @samp{-g} option. + +@item SDB_DEBUGGING_INFO +Define this macro if GNU CC should produce debugging output for SDB +in response to the @samp{-g} option. + +@item PUT_SDB_@var{op} +Define these macros to override the assembler syntax for the special +SDB assembler directives. See @file{sdbout.c} for a list of these +macros and their arguments. If the standard syntax is used, you need +not define them yourself. + +@item SDB_GENERATE_FAKE +Define this macro to override the usual method of constructing a dummy +name for anonymous structure and union types. See @file{sdbout.c} for +more information. + +@item DBX_NO_XREFS +Define this macro if DBX on your system does not support the construct +@samp{xs@var{tagname}}. On some systems, this construct is used to +describe a forward reference to a structure named @var{tagname}. +On other systems, this construct is not supported at all. + +@item DBX_CONTIN_LENGTH +A symbol name in DBX-format debugging information is normally +continued (split into two separate @code{.stabs} directives) when it +exceeds a certain length (by default, 80 characters). On some +operating systems, DBX requires this splitting; on others, splitting +must not be done. You can inhibit splitting by defining this macro +with the value zero. You can override the default splitting-length by +defining this macro as an expression for the length you desire. + +@item DBX_CONTIN_CHAR +Normally continuation is indicated by adding a @samp{\} character to +the end of a @code{.stabs} string when a continuation follows. To use +a different character instead, define this macro as a character +constant for the character you want to use. Do not define this macro +if backslash is correct for your system. + +@item DBX_STATIC_STAB_DATA_SECTION +Define this macro if it is necessary to go to the data section before +outputting the @samp{.stabs} pseudo-op for a non-global static +variable. + +@item ASM_OUTPUT_LABEL (@var{stream}, @var{name}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} the assembler definition of a label named @var{name}. +Use the expression @code{assemble_name (@var{stream}, @var{name})} to +output the name itself; before and after that, output the additional +assembler syntax for defining the name, and a newline. + +@item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} any text necessary for declaring the name @var{name} of a +function which is being defined. This macro is responsible for +outputting the label definition (perhaps using +@code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the +@code{FUNCTION_DECL} tree node representing the function. + +If this macro is not defined, then the function name is defined in the +usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). + +@item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} some commands that will make the label @var{name} global; +that is, available for reference from other files. Use the expression +@code{assemble_name (@var{stream}, @var{name})} to output the name +itself; before and after that, output the additional assembler syntax +for making that name global, and a newline. + +@item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} any text necessary for declaring the name of an external +symbol named @var{name} which is referenced in this compilation but +not defined. The value of @var{decl} is the tree node for the +declaration. + +This macro need not be defined if it does not need to output anything. +The GNU assembler and most Unix assemblers don't require anything. + +@item ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) +A C statement to output to the stdio stream @var{stream} a reference +in assembler syntax to a label named @var{name}. The character +@samp{_} should be added to the front of the name, if that is +customary on your operating system, as it is in most Berkeley Unix +systems. This macro is used in @code{assemble_name}. + +@item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) +A C statement to store into the string @var{string} a label whose name +is made from the string @var{prefix} and the number @var{num}. + +This string, when output subsequently by @code{ASM_OUTPUT_LABELREF}, +should produce the same output that @code{ASM_OUTPUT_INTERNAL_LABEL} +would produce with the same @var{prefix} and @var{num}. + +@item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) +A C statement to output to the stdio stream @var{stream} a label whose +name is made from the string @var{prefix} and the number @var{num}. +These labels are used for internal purposes, and there is no reason +for them to appear in the symbol table of the object file. On many +systems, the letter @samp{L} at the beginning of a label has this +effect. The usual definition of this macro is as follows: + +@example +fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num}) +@end example + +@item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) +Define this if the label before a jump-table needs to be output +specially. The first three arguments are the same as for +@code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the +jump-table which follows (a @code{jump_insn} containing an +@code{addr_vec} or @code{addr_diff_vec}). + +This feature is used on system V to output a @code{swbeg} statement +for the table. + +If this macro is not defined, these labels are output with +@code{ASM_OUTPUT_INTERNAL_LABEL}. + +@item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) +Define this if something special must be output at the end of a +jump-table. The definition should be a C statement to be executed +after the assembler code for the table is written. It should write +the appropriate code to stdio stream @var{stream}. The argument +@var{table} is the jump-table insn, and @var{num} is the label-number +of the preceding label. + +If this macro is not defined, nothing special is output at the end of +the jump-table. + +@item ASM_OUTPUT_ALIGN_CODE (@var{file}) +A C expression to output text to align the location counter in the way +that is desirable at a point in the code that is reached only by +jumping. + +This macro need not be defined if you don't want any special alignment +to be done at such a time. Most machine descriptions do not currently +define the macro. + +@item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) +A C expression to assign to @var{outvar} (which is a variable of type +@code{char *}) a newly allocated string made from the string +@var{name} and the number @var{number}, with some suitable punctuation +added. Use @code{alloca} to get space for the string. + +This string will be used as the argument to @code{ASM_OUTPUT_LABELREF} +to produce an assembler label for an internal static variable whose +name is @var{name}. Therefore, the string must be such as to result +in valid assembler code. The argument @var{number} is different each +time this macro is executed; it prevents conflicts between +similarly-named internal static variables in different scopes. + +Ideally this string should not be a valid C identifier, to prevent any +conflict with the user's own symbols. Most assemblers allow periods +or percent signs in assembler symbols; putting at least one of these +between the name and the number will suffice. + +@item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) +A C expression to output to @var{stream} some assembler code +which will push hard register number @var{regno} onto the stack. +The code need not be optimal, since this macro is used only when +profiling. + +@item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) +A C expression to output to @var{stream} some assembler code +which will pop hard register number @var{regno} off of the stack. +The code need not be optimal, since this macro is used only when +profiling. + +@item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{value}, @var{rel}) +This macro should be provided on machines where the addresses +in a dispatch table are relative to the table's own address. + +The definition should be a C statement to output to the stdio stream +@var{stream} an assembler pseudo-instruction to generate a difference +between two labels. @var{value} and @var{rel} are the numbers of two +internal labels. The definitions of these labels are output using +@code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same +way here. For example, + +@example +fprintf (@var{stream}, "\t.word L%d-L%d\n", + @var{value}, @var{rel}) +@end example + +@item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) +This macro should be provided on machines where the addresses +in a dispatch table are absolute. + +The definition should be a C statement to output to the stdio stream +@var{stream} an assembler pseudo-instruction to generate a reference to +a label. @var{value} is the number of an internal label whose +definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}. +For example, + +@example +fprintf (@var{stream}, "\t.word L%d\n", @var{value}) +@end example + +@item ASM_OUTPUT_DOUBLE (@var{stream}, @var{value}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to assemble a @code{double} constant whose value is +@var{value}. @var{value} will be a C expression of type +@code{double}. + +@item ASM_OUTPUT_FLOAT (@var{stream}, @var{value}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to assemble a @code{float} constant whose value is +@var{value}. @var{value} will be a C expression of type @code{float}. + +@item ASM_OUTPUT_INT (@var{stream}, @var{exp}) +@itemx ASM_OUTPUT_SHORT (@var{stream}, @var{exp}) +@itemx ASM_OUTPUT_CHAR (@var{stream}, @var{exp}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to assemble a @code{int}, @code{short} or @code{char} +constant whose value is @var{value}. The argument @var{exp} will be an +RTL expression which represents a constant value. Use +@samp{output_addr_const (@var{stream}, @var{exp})} to output this value +as an assembler expression.@refill + +@item ASM_OUTPUT_DOUBLE_INT (@var{stream}, @var{exp}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to assemble a @code{long long} constant whose value is +@var{exp}. The argument @var{exp} will be an RTL expression which +represents a constant value. It may be a @code{const_double} RTX, +or it may be an ordinary single-precision constant. In the latter +case, you should zero-extend it. + +@item ASM_OUTPUT_BYTE (@var{stream}, @var{value}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to assemble a single byte containing the number @var{value}. + +@item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to assemble a string constant containing the @var{len} +bytes at @var{ptr}. @var{ptr} will be a C expression of type +@code{char *} and @var{len} a C expression of type @code{int}. + +If the assembler has a @code{.ascii} pseudo-op as found in the +Berkeley Unix assembler, do not define the macro +@code{ASM_OUTPUT_ASCII}. + +@item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to advance the location counter by @var{nbytes} bytes. +@var{nbytes} will be a C expression of type @code{int}. + +@item ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to advance the location counter to a multiple of 2 to the +@var{power} bytes. @var{power} will be a C expression of type @code{int}. + +@item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} the assembler definition of a common-label named +@var{name} whose size is @var{size} bytes. The variable @var{rounded} +is the size rounded up to whatever alignment the caller wants. + +Use the expression @code{assemble_name (@var{stream}, @var{name})} to +output the name itself; before and after that, output the additional +assembler syntax for defining the name, and a newline. + +This macro controls how the assembler definitions of uninitialized +global variables are output. + +@item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} the assembler definition of a local-common-label named +@var{name} whose size is @var{size} bytes. The variable @var{rounded} +is the size rounded up to whatever alignment the caller wants. + +Use the expression @code{assemble_name (@var{stream}, @var{name})} to +output the name itself; before and after that, output the additional +assembler syntax for defining the name, and a newline. + +This macro controls how the assembler definitions of uninitialized +static variables are output. + +@item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) +A C statment to output DBX or SDB debugging information which indicates +that filename @var{name} is the current source file to the stdio stream +@var{stream}. + +This macro need not be defined if the standard form of debugging +information for the debugger in use is appropriate. + +@item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) +A C statment to output DBX or SDB debugging information before code +for line number @var{line} of the current source file to the +stdio stream @var{stream}. + +This macro need not be defined if the standard form of debugging +information for the debugger in use is appropriate. + +@item ASM_OUTPUT_IDENT (@var{stream}, @var{string}) +A C statement to output something to the assembler file to handle a +@samp{#ident} directive containing the text @var{string}. If this +macro is not defined, nothing is output for a @samp{#ident} directive. + +@item TARGET_BELL +A C constant expression for the integer value for escape sequence +@samp{\a}. + +@item TARGET_BS +@itemx TARGET_TAB +@itemx TARGET_NEWLINE +C constant expressions for the integer values for escape sequences +@samp{\b}, @samp{\t} and @samp{\n}. + +@item TARGET_VT +@itemx TARGET_FF +@itemx TARGET_CR +C constant expressions for the integer values for escape sequences +@samp{\v}, @samp{\f} and @samp{\r}. + +@item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) +Define this macro if you are using an unusual assembler that +requires different names for the machine instructions. + +The definition is a C statement or statements which output an +assembler instruction opcode to the stdio stream @var{stream}. The +macro-operand @var{ptr} is a variable of type @code{char *} which +points to the opcode name in its ``internal'' form---the form that is +written in the machine description. The definition should output the +opcode name to @var{stream}, performing any translation you desire, and +increment the variable @var{ptr} to point at the end of the opcode +so that it will not be output twice. + +In fact, your macro definition may process less than the entire opcode +name, or more than the opcode name; but if you want to process text +that includes @samp{%}-sequences to substitute operands, you must take +care of the substitution yourself. Just be sure to increment +@var{ptr} over whatever text should not be output normally. + +If you need to look at the operand values, they can be found as the +elements of @code{recog_operand}. + +If the macro definition does nothing, the instruction is output +in the usual way. + +@item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) +If defined, a C statement to be executed just prior to the output of +assembler code for @var{insn}, to modify the extracted operands so +they will be output differently. + +Here the argument @var{opvec} is the vector containing the operands +extracted from @var{insn}, and @var{noperands} is the number of +elements of the vector which contain meaningful data for this insn. +The contents of this vector are what will be used to convert the insn +template into assembler code, so you can change the assembler output +by changing the contents of the vector. + +This macro is useful when various assembler syntaxes share a single +file of instruction patterns; by defining this macro differently, you +can cause a large class of instructions to be output differently (such +as with rearranged operands). Naturally, variations in assembler +syntax affecting individual insn patterns ought to be handled by +writing conditional output routines in those patterns. + +If this macro is not defined, it is equivalent to a null statement. + +@item PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) +A C compound statement to output to stdio stream @var{stream} the +assembler syntax for an instruction operand @var{x}. @var{x} is an +RTL expression. + +@var{code} is a value that can be used to specify one of several ways +of printing the operand. It is used when identical operands must be +printed differently depending on the context. @var{code} comes from +the @samp{%} specification that was used to request printing of the +operand. If the specification was just @samp{%@var{digit}} then +@var{code} is 0; if the specification was @samp{%@var{ltr} +@var{digit}} then @var{code} is the ASCII code for @var{ltr}. + +If @var{x} is a register, this macro should print the register's name. +The names can be found in an array @code{reg_names} whose type is +@code{char *[]}. @code{reg_names} is initialized from +@code{REGISTER_NAMES}. + +When the machine description has a specification @samp{%@var{punct}} +(a @samp{%} followed by a punctuation character), this macro is called +with a null pointer for @var{x} and the punctuation character for +@var{code}. + +@item PRINT_OPERAND_PUNCT_VALID_P (@var{code}) +A C expression which evaluates to true if @var{code} is a valid +punctuation character for use in the @code{PRINT_OPERAND} macro. If +@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no +punctuation characters (except for the standard one, @samp{%}) are used +in this way. + +@item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) +A C compound statement to output to stdio stream @var{stream} the +assembler syntax for an instruction operand that is a memory reference +whose address is @var{x}. @var{x} is an RTL expression. + +@item ASM_OPEN_PAREN +@itemx ASM_CLOSE_PAREN +These macros are defined as C string constant, describing the syntax +in the assembler for grouping arithmetic expressions. The following +definitions are correct for most assemblers: + +@example +#define ASM_OPEN_PAREN "(" +#define ASM_CLOSE_PAREN ")" +@end example +@end table + +@node Config,, Machine Macros, Top +@chapter The Configuration File + +The configuration file @file{xm-@var{machine}.h} contains macro definitions +that describe the machine and system on which the compiler is running. +Most of the values in it are actually the same on all machines that GNU CC +runs on, so large parts of all configuration files are identical. But +there are some macros that vary: + +@table @code +@item FAILURE_EXIT_CODE +A C expression for the status code to be returned when the compiler +exits after serious errors. + +@item SUCCESS_EXIT_CODE +A C expression for the status code to be returned when the compiler +exits without serious errors. + +@item USE_C_ALLOCA +Define this macro to indicate that the compiler is running with the +@code{alloca} implemented in C. This version of @code{alloca} can be +found in the file @file{alloca.c}; to use it, you must also alter the +@file{Makefile} variable @code{ALLOCA}. + +This macro, unlike most, describes the machine that the compiler is +running on, rather than the one the compiler is compiling for. +Therefore, it should be set in the @file{xm-@var{machine}.h} file +rather than in the @file{tm-@var{machine}.h} file. + +If you do define this macro, you should probably do it as follows: + +@example +#ifndef __GNUC__ +#define USE_C_ALLOCA +#else +#define alloca __builtin_alloca +#endif +@end example + +@noindent +so that when the compiler is compiled with GNU CC it uses the more +efficient built-in @code{alloca} function. +@end table + +In addition, configuration files for system V define @code{bcopy}, +@code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca} +as a macro when compiled with GNU CC, in order to take advantage of the +benefit of GNU CC's built-in @code{alloca}. + +@contents +@bye |