--- gcc/gcc.texinfo 2018/04/24 16:45:37 1.1 +++ gcc/gcc.texinfo 2018/04/24 17:02:43 1.1.1.14 @@ -6,7 +6,7 @@ @ifinfo This file documents the use and the internals of the GNU compiler. -Copyright (C) 1988 Free Software Foundation, Inc. +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 @@ -21,15 +21,18 @@ notice identical to this one except for @end ignore Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU CC General Public License'' is 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. +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 section entitled ``GNU CC General Public License'' and -this permission notice may be included in translations approved by the -Free Software Foundation instead of in the original English. +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 @@ -39,12 +42,12 @@ Free Software Foundation instead of in t @sp 2 @center Richard M. Stallman @sp 3 -@center last updated 3 October 1988 +@center last updated 19 Sep 1992 @sp 1 -@center for version 1.29 +@center for version 1.42 @page @vskip 0pt plus 1filll -Copyright @copyright{} 1988 Free Software Foundation, Inc. +Copyright @copyright{} 1988, 1989, 1990, 1991, 1992 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -52,15 +55,18 @@ 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 -section entitled ``GNU CC General Public License'' is 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. +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 section entitled ``GNU CC General Public License'' and -this permission notice may be included in translations approved by the -Free Software Foundation instead of in the original English. +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 @@ -73,12 +79,14 @@ well as its new features and incompatibi @end ifinfo @menu -* Copying:: GNU CC General Public License says +* 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). @@ -88,87 +96,131 @@ well as its new features and incompatibi * 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 CC GENERAL PUBLIC LICENSE -@center (Clarified 11 Feb 1988) +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 1, February 1989 - The license agreements of most software companies keep you at the -mercy of those companies. By contrast, our general public license is -intended to give everyone the right to share GNU CC. To make sure that -you get the rights we want you to have, we need to make restrictions -that forbid anyone to deny you these rights or to ask you to surrender -the rights. Hence this license agreement. - - Specifically, we want to make sure that you have the right to give -away copies of GNU CC, that you receive source code or else can get it -if you want it, that you can change GNU CC or use pieces of it in new -free programs, and that you know you can do these things. - - To make sure that everyone has such rights, we have to forbid you to -deprive anyone else of these rights. For example, if you distribute -copies of GNU CC, you must give the recipients all the rights that you -have. You must make sure that they, too, receive or can get the +@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. - Also, for our own protection, we must make certain that everyone -finds out that there is no warranty for GNU CC. If GNU CC is modified by -someone else and passed on, we want its recipients to know that what -they have is not what we distributed, so that any problems introduced -by others will not reflect on our reputation. - - Therefore we (Richard Stallman and the Free Software Foundation, -Inc.) make the following terms which say what you must do to be -allowed to distribute or change GNU CC. + 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. -@unnumberedsec COPYING POLICIES + The precise terms and conditions for copying, distribution and +modification follow. -@enumerate -@item -You may copy and distribute verbatim copies of GNU CC source code as -you receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy a valid copyright notice -``Copyright @copyright{} 1988 Free Software Foundation, Inc.'' (or -with whatever year is appropriate); keep intact the notices on all -files that refer to this License Agreement and to the absence of any -warranty; and give any other recipients of the GNU CC program a copy -of this License Agreement along with the program. You may charge a -distribution fee for the physical act of transferring a copy. +@iftex +@unnumberedsec TERMS AND CONDITIONS +@end iftex +@ifinfo +@center TERMS AND CONDITIONS +@end ifinfo +@enumerate @item -You may modify your copy or copies of GNU CC 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: +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 +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 or is a derivative of GNU CC or any -part thereof, to be licensed at no charge to all third parties on -terms identical to those contained in this License Agreement -(except that you may choose to grant more extensive warranty -protection to some or all third parties, at your option). - -@item -You may charge a distribution fee for the physical act of -transferring a copy, and you may at your option offer warranty -protection in exchange for a fee. +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 unrelated program with this program (or its +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 program under the scope of these terms. +the other work under the scope of these terms. @item -You may copy and distribute GNU CC (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: +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 @@ -178,8 +230,8 @@ 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 -shipping charge) a complete machine-readable copy of the +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, @@ -190,59 +242,162 @@ allowed only for noncommercial distribut received the program in object code or executable form alone.) @end itemize -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. - -@item -You may not copy, sublicense, distribute or transfer GNU CC except as -expressly provided under this License Agreement. Any attempt -otherwise to copy, sublicense, distribute or transfer GNU CC is void -and your rights to use the program under this License agreement shall -be automatically terminated. However, parties who have received -computer software programs from you with this License Agreement will -not have their licenses terminated so long as such parties remain in -full compliance. - -@item -If you wish to incorporate parts of GNU CC into other free programs -whose distribution conditions are different, write to the Free Software -Foundation at 675 Mass Ave, Cambridge, MA 02139. We have not yet worked -out a simple rule that can be stated here, but we will often permit this. -We 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. +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 -Your comments and suggestions about our licensing policies and our -software are welcome! Please contact the Free Software Foundation, Inc., -675 Mass Ave, Cambridge, MA 02139, or call (617) 876-3296. - -@unnumberedsec NO WARRANTY - - BECAUSE GNU CC IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO -WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT -WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC, -RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU CC "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 GNU CC IS WITH YOU. SHOULD GNU CC PROVE DEFECTIVE, YOU -ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL RICHARD M. -STALLMAN, THE FREE SOFTWARE FOUNDATION, INC., AND/OR ANY OTHER PARTY -WHO MAY MODIFY AND REDISTRIBUTE GNU CC AS PERMITTED ABOVE, BE LIABLE TO -YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER -SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR -INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA -BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A -FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) GNU CC, EVEN -IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR -ANY CLAIM BY ANY OTHER PARTY. +@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: -@node Contributors, Options, Copying, Top +@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 @@ -260,7 +415,7 @@ Optimization'', Software Practice and Ex Paul Rubin wrote most of the preprocessor. @item -Leonard Tower wrote parts of the parser, RTL generator, RTL +Leonard Tower wrote parts of the parser, RTL generator, and RTL definitions, and of the Vax machine description. @item @@ -272,7 +427,7 @@ loop optimizations. @item Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed -the support for the SONY NEWS machine. +the support for the Sony NEWS machine. @item Charles LaBrec contributed the support for the Integrated Solutions @@ -306,31 +461,186 @@ 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 -@node Options, Installation, Contributors, Top +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 @samp{-d -r}. +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; 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. +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. Some options control -the preprocessor and others the compiler itself. Yet other options -control the assembler and linker; these are not documented here because the -GNU assembler and linker are not yet released. +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. @@ -367,6 +677,12 @@ Compiler driver program prints the comma 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}, @@ -385,6 +701,33 @@ the @samp{-B} prefix, if needed. If it 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. @@ -399,6 +742,13 @@ keywords, and predefined macros such as 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}. @@ -406,8 +756,8 @@ 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. +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. @@ -421,7 +771,8 @@ declarations of functions. @item The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const} -and @code{volatile} are not recognized.@refill +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. @@ -434,6 +785,16 @@ to @code{unsigned int}. 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. @@ -491,15 +852,7 @@ Nevertheless it proves possible to debug it reasonable to use the optimizer for programs that might have bugs. @item -gg -Produce debugging information in GDB's own format. This requires the -GNU assembler and linker in order to work. - -This feature will probably be eliminated. It was intended to enable -GDB to read the symbol table faster, but it doesn't result in enough -of a speedup to be worth the larger object files and executables. We -are working on other ways of making GDB start faster, which work with -DBX format debugging information and could be made to work with SDB -format. +Produce debugging information in the old GDB format. This is obsolete. @item -w Inhibit all warning messages. @@ -513,17 +866,19 @@ An automatic variable is used without fi These warnings are possible only in optimizing compilation, because they require data flow information that is computed only -when optimizing. They 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 the flow analysis pass before the -warnings are printed. +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 @@ -562,6 +917,10 @@ another common case: @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 @@ -576,7 +935,7 @@ in fact be called at the place which wou @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 inspire such a +a value.) For example, this function would evoke such a warning: @example @@ -590,6 +949,9 @@ foo (a) 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 @@ -604,13 +966,50 @@ to @code{int}. Also warn about any @cod 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. +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. +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 @@ -629,6 +1028,13 @@ analysis program @code{prof}. 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 @@ -651,9 +1057,8 @@ Add directory @var{dir} to the list of d for @samp{-l}. @item -nostdlib -Don't use the standard system libraries and startup files when -linking. Only the files you specify (plus @file{gnulib}) will be -passed to the linker. +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 @@ -737,10 +1142,61 @@ will assemble with the GNU assembler. 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. These are the flags: +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 @@ -753,7 +1209,8 @@ Use @samp{-ffloat-store} for such progra @item -fno-asm Do not recognize @code{asm}, @code{inline} or @code{typeof} as a -keyword. These words may then be used as identifiers. +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 @@ -807,16 +1264,34 @@ If all calls to a given function are int 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. + +Don't use @samp{-fcaller-saves} together with +@samp{-fomit-frame-pointer}. This combination does not work. + @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. Writing into string -constants is a very bad idea; ``constants'' should be constant. +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 @@ -830,9 +1305,15 @@ optimizations performed when this option @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}. +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 @@ -843,9 +1324,20 @@ The type @code{char} is always a distinc @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, @@ -856,6 +1348,9 @@ accepted are machine-specific and are de @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 @@ -867,6 +1362,9 @@ Use of this flag for a register that has 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 @@ -879,6 +1377,9 @@ frame pointer, will produce disastrous r 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} @@ -890,8 +1391,6 @@ Here are the possible letters: Dump after RTL generation. @item j Dump after first jump optimization. -@item J -Dump after last jump optimization. @item s Dump after CSE (including the jump optimization that sometimes follows CSE). @@ -905,6 +1404,10 @@ Dump after instruction combination. 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 @@ -918,6 +1421,14 @@ this option (though a rare few will requ 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 @@ -945,12 +1456,23 @@ directives. (Ordinarily @emph{all} @sam this way.) In addition, the @samp{-I-} option inhibits the use of the current -directory as the first search directory for @samp{#include -"@var{file}"}. Therefore, the current directory is searched only if -it is requested explicitly with @samp{-I.}. Specifying both -@samp{-I-} and @samp{-I.} allows you to control precisely which -directories are searched before the current one and which are searched -after. +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 @@ -962,7 +1484,7 @@ directories from the search path except @item -M Tell the preprocessor to output a rule suitable for @code{make} -describing the dependencies of each source file. For each source +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 @@ -978,7 +1500,7 @@ included with @samp{#include <@var{file} @samp{-MM} implies @samp{-E}. @item -D@var{macro} -Define macro @var{macro} with the empty string as its definition. +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}. @@ -986,7 +1508,7 @@ Define macro @var{macro} as @var{defn}. @item -U@var{macro} Undefine macro @var{macro}. -@item -T +@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 @@ -995,24 +1517,201 @@ brain-damage. The @samp{-ansi} option a @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.) +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. +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. +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 i386-sysv4 +Intel 386 PCs running system V.4. You must run the shell script +@file{fixincludes-V4} in order for GNU CC to work properly. You must +also uncomment some lines in @file{Makefile}. +@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-os5 +The Mips computer, RS series, with the System V environment +running on revision 5.00 of RISC-OS as default. +Note that GNU CC cannot generate debugging information in the unusual +format used on the Mips, and also cannot be used to create +programs that use shared libraries. +@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-os5 +The Mips computer, RS series, with the BSD 4.3 environment +running revision 5.00 of RISC-OS as default. +Note that GNU CC cannot generate debugging information in the unusual +format used on the Mips, and also cannot be used to create +programs that use shared libraries. +@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-os5 +The Mips computer, M series running revision 5.00 of RISC-OS. +Note that GNU CC cannot generate debugging information in the +unusual format used on the Mips, and also cannot be used to +create programs that use shared libraries. +@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 @@ -1021,21 +1720,21 @@ config file for the machine you are usin file is responsible for defining information about the host machine. It includes @file{tm.h}. -The file's name should be @file{config-@var{machine}.h}, with these -exceptions: +The file is located in the subdirectory @file{config}. Its name +should be @file{xm-@var{machine}.h}, with these exceptions: @table @file -@item config-vms.h +@item xm-vms.h for vaxen running VMS. -@item config-vaxv.h +@item xm-vaxv.h for vaxen running system V. -@item config-i386v.h +@item xm-i386v.h for Intel 80386's running system V. -@item config-sun4.h -for Suns (model 2, 3 or 4) running @emph{operating system} version 4. -@item config-hp9k3.h +@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 config-gnx.h +@item xm-genix.h for the ns32000 running Genix @end table @@ -1045,23 +1744,34 @@ refers to the appropriate file. @item Make a symbolic link named @file{tm.h} to the machine-description -macro file for your machine (its name should be -@file{tm-@var{machine}.h}). +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. +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. +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. +for Sony NEWS systems. @item tm-hp9k320.h for HPUX systems, if you are using GNU CC with the system's assembler and linker. @@ -1070,26 +1780,33 @@ for HPUX systems, if you are using the G 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 SPARC (Sun 4), use @file{tm-sparc.h}. - For the Motorola 88000, use @file{tm-m88k.h}. The support for the -88000 has a few unfinished spots because there was no way to run the -output. Bugs are suspected in handling of branch-tables and in -the function prologue and epilogue. +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-seq386.h} for a Sequent 386 system, or @file{tm-compaq.h} for -a Compaq. +@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-gnx.h} if you are using Genix version 3; otherwise, perhaps +@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 @@ -1098,14 +1815,30 @@ get the compiled versions of these from 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 (its name should be @file{@var{machine}.md}). +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 (its name should be -@file{output-@var{machine}.c}). +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 @@ -1114,19 +1847,41 @@ unnecessary if the Bison output files @f @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 that Sept 8, 1988 will produce incorrect output +Bison versions older than Sept 8, 1988 will produce incorrect output for @file{c-parse.tab.c}. @item -If you are using a Sun, make sure the environment variable -@code{FLOAT_OPTION} is not set. 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 will not link -properly without special pains. +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: @@ -1146,6 +1901,8 @@ Recompile the compiler with itself, with 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: @@ -1156,7 +1913,7 @@ make CC=stage1/gcc CFLAGS="-g -O -Bstage @item If you wish to test the compiler by compiling it with itself one more -time, do this: +time, do this (in C shell): @example make stage2 @@ -1166,14 +1923,32 @@ cmp $file stage2/$file end @end example -This will notify you if any of these stage 3 object files differs from -those of stage 2. 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}). +@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 -Aside from the @samp{-B} option, the options should be the same as -when you made stage 2. +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. @@ -1184,12 +1959,23 @@ 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}, so that it appears in typical -execution search paths.@refill +On some machines, you will find that starts to recompile the @file{.c} +files, due to a bug in Make. If that happens, cancel it and try again +specifying the same values for Make variables that you used in the last +compilation; that may not prevent the spurious recompilation, but will +at least do it properly. For example: + +@example +make CC=stage2/gcc CFLAGS="-g -O -Bstage2/" install +@end example + +@noindent +The @samp{install} target 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 @@ -1213,10 +1999,30 @@ Alternatively, on Sun systems and 4.3BSD 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. +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 -See the file @file{fixincludes} for a list of all the files we know to -require correction. +@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. The same problem may occur +on some versions of SunOS. If you encounter this problem, try using +@file{fixinc.new} instead opf @code{fixincludes}. @end enumerate If you cannot install the compiler's passes and run-time support in @@ -1229,33 +2035,169 @@ specify @samp{-B/usr/foo/gcc/} when you Also, you can specify an alternative default directory for these files by setting the Make variable @code{libdir} when you make GNU CC. -@node VMS Install,, Installation, Installation -@section Installing GNU CC on VMS +@node Other Dir, Sun Install, Installation, Installation +@section Compilation in a Separate Directory -The VMS version of GNU CC is distributed in an unusual tape format which -consists of several tape files. The first is a command file; the second is -an executable program which reads Unix tar format; the third is another -command file which uses this program to read the remainder of the tape. - -To load the tape, it suffices to mount it @samp{/foreign} and then do -@samp{@@mta0:} to execute the command file at the beginning of the tape. - -The tape contains executables and object files as well as sources, so no -compilation is necessary unless you change the sources. (This is a good -thing, since you probably don't have any other C compiler.) If you must -recompile, here is how: +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 -Copy the file @file{tm-vms.h} to @file{tm.h}, @file{config-vms.h} to -@file{config.h}, @file{vax.md} to @file{md.} and @file{output-vax.c} -to @file{aux-output.c}.@refill +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 -Type @samp{@@make} to do recompile everything. +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 -To install the @samp{GCC} command so you can use the compiler easily, in +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 @samp{rcc -Di386 -DM_UNIX -DM_I386 -DM_SYSV -DM_COFF}. + +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. + +Note that the function @code{memmove} is broken in 3.2v2; it clobbers +register @code{%ebx}. See the file @file{sco-memmove.s}. + +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: @@ -1263,24 +2205,32 @@ file for GNU CC as follows: @item Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE} to point to the directories where the GNU CC executables -(@samp{gcc-cpp}, @samp{gcc-cc1}, etc.) and the C include files are +(@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 +$ 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. +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 @samp{GCC} command with the command line: +Install the @file{GCC} command with the command line: @example -$ set command /table=sys$library:dcltables gnu_cc:gcc +$ 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 @@ -1289,8 +2239,186 @@ file.c}, which is equivalent to the comm Unix. @end enumerate -@node Trouble, Incompatibilities, Installation, Top -@chapter Known Causes of Trouble with GNU CC. +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. @@ -1298,7 +2426,7 @@ or using GNU CC. @itemize @bullet @item On certain systems, defining certain environment variables such as -@samp{CC} can interfere with the functioning of @code{make}. +@code{CC} can interfere with the functioning of @code{make}. @item Cross compilation can run into trouble for certain machines because @@ -1312,27 +2440,92 @@ representation. But this does not work a different machine with an incompatible floating point format, or even a different byte-ordering. -It is possible to fix this by writing machine-independent code which -understands the floating point representation of the target machine. -I am not interested in doing that much work to compensate for bugs -in assemblers. +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 -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. +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 -@node Incompatibilities, Extensions, Trouble, Top +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. - -Ultimately our intention is that the @samp{-traditional} option will -eliminate most of these incompatibilities by telling GNU C to behave -like the other C compilers. +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 @@ -1347,13 +2540,14 @@ 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. +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 @@ -1364,7 +2558,7 @@ string constants. For example, the foll @end example @noindent -will produce output @samp{"a"} regardless of what the argument @var{a} is. +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. @@ -1400,6 +2594,11 @@ 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 @@ -1460,40 +2659,98 @@ with PCC compatibility, you should decla @item When compiling functions that return structures or unions, GNU CC -output code 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. +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 GCC is as follows: a structure or union which is 1, +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 GCC because it is slower and nonreentrant. +method is not used in GNU CC because it is slower and nonreentrant. -On systems where PCC works this way, you may be able to make GCC-compiled -code call such functions that were compiled with PCC by declaring them -to return a pointer to the structure or union instead of the structure -or union itself. For example, instead of this: +You can tell GNU CC to use the PCC convention with the option +@samp{-fpcc-struct-return}. +@end itemize -@example -struct foo nextfoo (); -@end example +There are also system-specific incompatibilities. -@noindent -write this: +@itemize @bullet +@item +On the Sparc, GNU CC uses an incompatible calling convention for +structures and unions. It passes them by including their contents in +the argument list, whereas the standard compiler passes them effectively +by reference. + +This is hard to fix in GCC version 1. GNU CC version 2 will use a +compatible calling convention. + +The convention for structure or union returning is also incompatible, +and @samp{-fpcc-struct-return} does not help. + +System functions which can't be called properly from code compiled with +GCC include @code{fetch}, @code{store}, @code{delete}, @code{firstkey}, +@code{nextkey}, @code{inet_makeaddr}, @code{inet_lnaof}, +@code{inet_netof}, @code{inet_ntoa}, @code{mallinfo}, +@code{pmap_rmtcall}, @code{clnt_call}, @code{clntudp_bufcreate} and +@code{clntudp_create}. + +@item +One consequence of the unusual calling convention used on the Sparc +is that structures with less than word alignment do not work right +when passed as arguments to varargs functions. + +It's not easy to fix this problem. In any case, it will be gone in +version 2 as a result of the changed calling convention. + +@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. However, the C compiler uses conventions compatible +with BSD Unix: registers 2 through 5 may be clobbered by function calls. + +GNU CC uses the same convention as the Ultrix C compiler. You can use +these options to produce code compatible with the Fortran compiler: @example -struct foo *nextfoo (); -#define nextfoo *nextfoo +-fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5 @end example -@noindent -(Note that this assumes you are using the GNU preprocessor and not -@samp{-traditional}, so that the ANSI antirecursion rules for macro -expansions are effective.) +@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 @@ -1508,21 +2765,26 @@ features in conditional compilation, che @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. -* Constructors:: Constructor expressions give structures, unions - or arrays as values. +* 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. +* 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 @@ -1627,6 +2889,10 @@ typeof (int *) @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}. @@ -1676,7 +2942,7 @@ array (pointer (char), 4) y; @end example @noindent -Thus, @samp{array (pointer (char), 4)} is the type of arrays of 4 +Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 pointers to @code{char}. @end itemize @@ -1713,27 +2979,17 @@ expressions are equivalent: (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 @samp{a} does not permit a cast to -@samp{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 -@samp{a} has type @samp{char *}, the following two expressions are -equivalent: +A cast is a valid lvalue if its operand is an lvalue. 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 +converted 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) +(int)(a = (char *)(int)5) @end example An assignment-with-arithmetic operation such as @samp{+=} applied to a cast @@ -1743,9 +2999,26 @@ equivalent: @example (int)a += 5 -(int)(a = (char *) ((int)a + 5)) +(int)(a = (char *)(int) ((int)a + 5)) +@end example + +You cannot take the address of an lvalue cast, because the use of its +address would not work out coherently. Suppose that @code{&(int)f} were +permitted, where @code{f} has type @code{float}. Then the following +statement would try to store an integer bit-pattern where a floating +point number belongs: + +@example +*&(int)f = 1; @end example +This is quite different from what @code{(int)f = 1} would do---that +would convert 1 to floating point and store it. Rather than cause this +inconsistancy, we think it is better to prohibit use of @samp{&} on a cast. + +If you really do want an @code{int *} pointer with the address of +@code{f}, you can simply write @code{(int *)&f}. + @node Conditionals, Zero-Length, Lvalues, Extensions @section Conditional Expressions with Omitted Middle-Operands @@ -1818,32 +3091,16 @@ FILE *concat_fopen (char *s1, char *s2, @} @end example -You can also define structure types containing variable-length arrays, and -use them even for arguments or function values, as shown here: +You can also use variable-length arrays as arguments to functions: @example -int foo; - struct entry +tester (int len, char data[len]) @{ - char data[foo]; -@}; - -struct entry -tester (struct entry arg) -@{ - struct entry new; - int i; - for (i = 0; i < foo; i++) - new.data[i] = arg.data[i] + 1; - return new; + @dots{} @} @end example -@noindent -(Eventually there will be a way to say that the size of the array is -another member of the same structure.) - 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}. @@ -1892,12 +3149,15 @@ size of a @code{void} or of a function a 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 are not required to be constant -expressions in GNU C. Here is an example of an initializer with run-time -varying elements: +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) @@ -1907,7 +3167,7 @@ foo (float f, float g) @} @end example -@node Constructors, Dollar Signs, Initializers, Extensions +@node Constructors, Function Attributes, Initializers, Extensions @section Constructor Expressions GNU C supports constructor expressions. A constructor looks like a cast @@ -1922,7 +3182,7 @@ struct foo @{int a; char b[2];@} structu @end example @noindent -Here is an example of constructing a @samp{struct foo} with a constructor: +Here is an example of constructing a @code{struct foo} with a constructor: @example structure = ((struct foo) @{x + y, 'a', 0@}); @@ -1957,29 +3217,85 @@ latter does the same thing an ordinary C output = ((int[]) @{ 2, x, 28 @}) [input]; @end example -@node Dollar Signs, Alignment, Constructors, Extensions +@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 int 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 +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. +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} +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 +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 @@ -1990,9 +3306,9 @@ 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 +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 @@ -2015,19 +3331,24 @@ inc (int *a) @} @end example -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. +(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, 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. +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 @@ -2036,6 +3357,20 @@ the other source files, so the calls the 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 @@ -2058,16 +3393,21 @@ asm ("fsinx %1,%0" : "=f" (result) : "f" 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 -constraints use the same language used in the machine description -(@pxref{Constraints}). +@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 number of operands is limited to the maximum number of +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 @@ -2076,20 +3416,21 @@ not know what it means, or whether it is extended @code{asm} feature is most often used for machine instructions that the compiler itself does not know exist. -If there are no output operands, and there are input operands, then you -should write two colons in a row where the output operands would go. - 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. For an operand that is read-write, or in which not all bits are -written and the other bits contain useful information, you must logically +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: +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)); @@ -2097,7 +3438,8 @@ asm ("combine %2,%0" : "=r" (foo) : "0" @noindent The constraint @samp{"0"} for operand 1 says that it must occupy the same -location as operand 0. +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 @@ -2123,9 +3465,10 @@ This assumption may be false if the asse 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). For example, on the vax, +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" @@ -2134,6 +3477,36 @@ asm volatile ("movc3 %0,%1,%2" : "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, @@ -2157,14 +3530,15 @@ example, if the desired type were @code{ argument to an @code{int} variable named @code{__arg} would warn about using a pointer unless the caller explicitly casts it. -GNU CC assumes for optimization purposes that these instructions have 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. +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 @@ -2175,6 +3549,10 @@ example: 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 @@ -2184,12 +3562,16 @@ instructions would alter the condition c test it. This problem doesn't arise for ordinary ``test'' and ``compare'' instructions because they don't have any output operands. -@node Asm Labels,,Extended Asm, Extensions +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} keyword after the declarator as -follows: +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; @@ -2222,15 +3604,194 @@ register name; that would produce comple 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. -Reporting a bug may help you by bringing a solution to your problem, or it -may not. But in any case the important 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. +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. @@ -2270,13 +3831,14 @@ by chance to give the desired results wi 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 @samp{return} +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 @samp{f (*p++, *p++)}. Your previous compiler might have +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. +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 @@ -2324,17 +3886,31 @@ bug-gcc@@prep.ai.mit.edu @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gcc @end example -As a last resort, snail them to: +@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 -545 Tech Sq +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 mention a -fact or leave it out, mention it! +@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 @@ -2343,10 +3919,20 @@ Well, probably it doesn't, but one canno 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 an exact example. +the bug. Play it safe and give a specific, complete example. That is the +easiest thing for you to do, and the most helpful. -If you want to enable me to fix the bug, you should include all these -things: +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 @@ -2412,13 +3998,14 @@ then when mine fails to crash, I would k 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. -In cases where GNU CC generates incorrect code, if you send me a small -complete sample program I will find the error myself by running the -program under a debugger. If you send me a large example or a part of -a larger program, I cannot do this; you must debug the compiled -program and narrow the problem down to one source line. Tell me which -source line it is, and what you believe is incorrect about the code -generated for that line. +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} @@ -2453,7 +4040,7 @@ they point to (and most of the contents 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, +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 @@ -2483,6 +4070,7 @@ 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 @@ -2491,28 +4079,34 @@ less time, etc. Most GNU CC bugs involv 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. +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. +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, because I might see -problems with your patch and decide to fix the problem another way. +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 using the debugger to find the facts. +things without first using the debugger to find the facts. @end itemize @node Portability, Interface, Bugs, Top @@ -2764,8 +4358,9 @@ this pass. This dump file's name is mad the input file name. @item -Loop optimization. This pass moves constant expressions out of loops. -Its source file is @file{loop.c}. +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 @@ -2844,17 +4439,25 @@ the input file name. @item Jump optimization is repeated, this time including cross-jumping -and deletion of no-op move instructions. Machine-specific peephole -optimizations are performed at the same time. +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. The function entry and exit sequences are generated +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 @@ -2934,9 +4537,9 @@ form uses nested parentheses to indicate * 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. +* Assembler:: Representing @code{asm} with operands. * Insns:: Expression types for entire insns. -* Calls:: RTL representation of function call insns. +* Calls:: RTL representation of function call insns. * Sharing:: Some expressions are unique; others *must* be copied. @end menu @@ -2949,7 +4552,7 @@ short) is a C structure, but it is usual 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 @samp{symbol_ref} expressions, +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. @@ -2978,10 +4581,10 @@ The expression code determines how many 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 @samp{subreg}, the first operand is +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 @samp{plus}, there are two operands, both of which -are to be regarded as expressions. In a @samp{symbol_ref} expression, +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 @@ -2990,10 +4593,10 @@ 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: @samp{const_int}. +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 @samp{(nil)}. +wanted. The written form of this is @code{(nil)}. @node Accessors, Flags, RTL Objects, RTL @section Access to Operands @@ -3003,7 +4606,7 @@ objects and their kinds, with four possi (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 -@samp{subreg} is @samp{ei}.@refill +@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 @@ -3048,7 +4651,7 @@ stored in the operand. You would do thi the containing expression. That is also how you would know how many operands there are. -For example, if @var{x} is a @samp{subreg} expression, you know that it has +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; @@ -3093,24 +4696,29 @@ in certain types of expression. Most of 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 @samp{mem} expressions, nonzero for volatile memory references. +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 @samp{mem} expressions, nonzero for reference to an entire +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 @samp{reg}, nonzero if it corresponds to a variable present in +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 @samp{reg} if it is the place in which this function's +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}. @@ -3120,7 +4728,7 @@ functions called by this one, but @code{ in this kind of use. @item RTX_UNCHANGING_P (@var{x}) -Nonzero in a @samp{reg} or @samp{mem} if the value is not changed +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}. @@ -3135,7 +4743,7 @@ In an insn, nonzero if the insn has been @code{volatil} field and printed as @samp{/v}. @item CONSTANT_POOL_ADDRESS_P (@var{x}) -Nonzero in a @samp{symbol_ref} if it refers to part of the current +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 @@ -3152,19 +4760,22 @@ Expressions that appear more than once a rules for shared structure (@pxref{Sharing}). @item volatil -This flag is used in @samp{mem} and @samp{reg} expressions and in insns. -In RTL dump files, it is printed as @samp{/v}. +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 @samp{mem} expression, it is 1 if the memory reference is volatile. +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 @samp{reg} expression, it is 1 if the value is a user-level variable. +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 @samp{mem} expressions. It is 1 if the memory +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. @@ -3175,7 +4786,7 @@ cases of aliasing. In an RTL dump, this flag is represented as @samp{/s}. @item unchanging -This flag is used in @samp{reg} and @samp{mem} expressions. 1 means +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). @@ -3185,7 +4796,7 @@ In an RTL dump, this flag is represented In some kinds of expressions, including insns, this flag means the rtl was produced by procedure integration. -In a @samp{reg} expression, this flag indicates the register +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 @@ -3204,7 +4815,7 @@ expressions (declarations and types, to 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 @samp{reg} +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. @@ -3217,9 +4828,19 @@ Here is a table of machine modes. @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. @@ -3234,6 +4855,11 @@ point number. ``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. @@ -3246,7 +4872,7 @@ which have no such instructions, @code{B @item VOIDmode Void mode means the absence of a mode or an unspecified mode. -For example, RTL expressions of code @samp{const_int} have 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. @@ -3279,12 +4905,45 @@ into the machine mode used for addresses 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 it would not be hard to program it to avoid this. Likewise, -you can arrange for the C type @code{short int} to avoid using -@code{HImode}. In the long term it would 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. +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: @@ -3295,6 +4954,17 @@ Returns the machine mode of the RTX @var @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}. @@ -3323,12 +4993,12 @@ is customarily accessed with the macro @ 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 @samp{const_int} and +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 or mode @var{m}. All floating point +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. @@ -3339,16 +5009,19 @@ precision), then they represent a @code{ @example union @{ double d; int i[2];@} u; -u.i[0] = XINT (x, 0); -u.i[1] = XINT (x, 1); +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 -@samp{const_double} expressions with value 0, in modes @code{DFmode} and -@code{SFmode}, respectively. +@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 @@ -3359,7 +5032,7 @@ the @samp{*}. Otherwise, the label is @ @item (label_ref @var{label}) Represents the value of an assembler label for code. It contains one -operand, an expression, which must be a @samp{code_label} that appears +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. @@ -3369,9 +5042,9 @@ references is so that jump optimization @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 (@samp{const_int}, @samp{symbol_ref} and -@samp{label_ref} expressions) combined with @samp{plus} and -@samp{minus}. However, not all combinations are valid, since the +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 @@ -3400,7 +5073,7 @@ hard register numbers, even those that c 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 @samp{reg} expression. +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. @@ -3415,16 +5088,16 @@ 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 @samp{subreg} +an access to a pseudo register using a nonnatural mode, a @code{subreg} expression is used. -A @samp{reg} expression with a machine mode that specifies more than +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 @samp{reg} expressions may not be live +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. @@ -3432,21 +5105,21 @@ The CSE pass must go out of its way to m not arise. @item (subreg:@var{m} @var{reg} @var{wordnum}) -@samp{subreg} expressions are used to refer to a register in a machine +@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 @samp{reg} that actually refers to several registers. +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 @samp{subreg}. In such -a case, @var{wordnum} is zero. +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 @samp{subreg} is to extract the individual registers +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 @samp{subreg} with mode @code{SImode} and a @var{wordnum} that +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 @@ -3454,26 +5127,43 @@ that word number zero is the most signif the least significant part. Between the combiner pass and the reload pass, it is possible to have -a @samp{subreg} which contains a @samp{mem} instead of a @samp{reg} as +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 @samp{mem} into a suitable register. +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 @samp{subreg}. On some machines the most significant part of a +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. It 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 (@samp{const_int} with value zero; that is to say, -@code{const0_rtx}). +operands and may not have a machine mode. There are two ways to use it: -There is only one expression object of code @samp{cc0}; it is the +@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 @samp{cc0} will return @code{cc0_rtx}. +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 @@ -3485,14 +5175,19 @@ the macro @code{NOTICE_UPDATE_CC}). Onl 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 @samp{pc}; it is the value +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 @samp{pc} will return @code{pc_rtx}. +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. @@ -3513,12 +5208,12 @@ carried out in machine mode @var{m}. Th @var{x} and @var{y} both are valid for mode @var{m}. @item (minus:@var{m} @var{x} @var{y}) -Like @samp{plus} but represents subtraction. +Like @code{plus} but represents subtraction. -@item (minus @var{x} @var{y}) +@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 @samp{minus} expression indicates that the result is +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. @@ -3543,13 +5238,13 @@ Widening multiplication and same-size mu distinct and supported by different machine instructions; machines may support one but not the other.@refill -@samp{mult} may be used for floating point division as well. +@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 @samp{mult} but represents unsigned multiplication. It may be -used in both same-size and widening forms, like @samp{mult}. -@samp{umult} is used only for fixed-point multiplication. +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}, @@ -3558,15 +5253,15 @@ mode, it represents the exact quotient; 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 @samp{div} +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 @samp{div} but represents unsigned division. +Like @code{div} but represents unsigned division. @item (mod:@var{m} @var{x} @var{y}) @itemx (umod:@var{m} @var{x} @var{y}) -Like @samp{div} and @samp{udiv} but represent the remainder instead of +Like @code{div} and @code{udiv} but represent the remainder instead of the quotient. @item (not:@var{m} @var{x}) @@ -3608,11 +5303,11 @@ to be negative constants or else compute by negation. @item (ashift:@var{m} @var{x} @var{c}) -Like @samp{lshift} but for arithmetic left shift. +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 @samp{lshift} and @samp{ashift} but for right shift. +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}) @@ -3628,7 +5323,7 @@ Represents the square root of @var{x}, c a floating point mode. @item (ffs:@var{m} @var{x}) -Represents the one plus the index of the least significant 1-bit in +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 @@ -3638,15 +5333,16 @@ valid. @node Comparisons, Bit Fields, Arithmetic, RTL @section Comparison Operations -Comparison operators test a relation on two operands and are considered to -represent the value 1 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. +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 @samp{gt} and @samp{gtu} for signed and +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 @@ -3678,19 +5374,19 @@ otherwise 0. the comparison is done in a signed sense. @item (gtu @var{x} @var{y}) -Like @samp{gt} but does unsigned comparison, on fixed-point numbers only. +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 @samp{gt} and @samp{gtu} but test for ``less than''. +Like @code{gt} and @code{gtu} but test for ``less than''. @item (ge @var{x} @var{y}) @item (geu @var{x} @var{y}) -Like @samp{gt} and @samp{gtu} but test for ``greater than or equal''. +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 @samp{gt} and @samp{gtu} but test for ``less than or equal''. +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 @@ -3699,7 +5395,7 @@ precise, @var{cond} is a comparison expr represents a choice, according to @var{cond}, between the value represented by @var{then} and the one represented by @var{else}. -On most machines, @samp{if_then_else} expressions are valid only +On most machines, @code{if_then_else} expressions are valid only to express conditional jumps. @end table @@ -3708,7 +5404,7 @@ to express conditional jumps. 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 a assignment, indicating insertion of a value +on the left side of an assignment, indicating insertion of a value into the specified bit field. @table @code @@ -3724,7 +5420,7 @@ but typically @var{loc} should be a sing or a full word in a register. @item (zero_extract:SI @var{loc} @var{size} @var{pos}) -Like @samp{sign_extract} but refers to an unsigned or zero-extended +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 @@ -3735,7 +5431,7 @@ are filled to an entire word with zeros 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 @samp{plus} +@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 @@ -3810,10 +5506,10 @@ but rather state assertions about their @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 -@samp{set} expression. In addition, the operand of this expression -must be a @samp{subreg} expression. +@code{set} expression. In addition, the operand of this expression +must be a @code{subreg} expression. -The presence of @samp{strict_low_part} says that the part of the +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 @@ -3836,23 +5532,23 @@ the operands of these. @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: @samp{reg} (or -@samp{subreg} or @samp{strict_low_part}), @samp{mem}, @samp{pc} or -@samp{cc0}.@refill +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 @samp{reg}, @samp{subreg} or @samp{mem}, it has a +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 @samp{reg} whose machine mode is less than the full +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 @samp{subreg} whose machine mode is narrower than +@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 @samp{strict_low_part} of a @samp{subreg}, then the +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 -@samp{subreg} is given the value @var{x} and the rest of the register +@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 @@ -3860,13 +5556,13 @@ have any mode. This represents a ``test If @var{lval} is @code{(pc)}, we have a jump instruction, and the possibilities for @var{x} are very limited. It may be a -@samp{label_ref} expression (unconditional jump). It may be an -@samp{if_then_else} (conditional jump), in which case either the +@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 @samp{label_ref} -(for the case which does jump). @var{x} may also be a @samp{mem} or -@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @samp{reg} or a -@samp{mem}; these unusual patterns are used to represent jumps through +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) @@ -3874,11 +5570,11 @@ Represents a return from the current fun 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 @samp{return} expression code is never +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 @samp{mem} expression +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 @@ -3893,8 +5589,8 @@ addressed. @item (clobber @var{x}) Represents the storing or possible storing of an unpredictable, -undescribed value into @var{x}, which must be a @samp{reg} or -@samp{mem} expression. +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 @@ -3909,22 +5605,41 @@ 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 -@samp{clobber} expressions to indicate this fact. Also, each function -call is assumed to have the potential to alter any memory location. +@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 instructions whose only effect is to store a -value in @var{x}. @var{x} must be a @samp{reg} expression. +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 @samp{parallel} is a +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 effects---expressions of code @samp{set}, @samp{call}, -@samp{return}, @samp{clobber} or @samp{use}.@refill +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 @@ -3939,28 +5654,46 @@ performed. For example, 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 instruction. +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 the last jump-optimization -pass, can produce insns whose patterns consist of a @samp{parallel} +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 @samp{reg}, @samp{mem} or constant expressions. +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} may need -to deal with such insns. +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 @samp{insn}, @samp{jump_insn}, @samp{call_insn}, -@samp{code_label}, @samp{barrier} or @samp{note}. +must be an @code{insn}, @code{jump_insn}, @code{call_insn}, +@code{code_label}, @code{barrier} or @code{note}. -A @samp{sequence} RTX never appears in an actual insn. It represents -the sequence of insns that result from a @samp{define_expand} +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 @samp{sequence} is forgotten. +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 @@ -3972,13 +5705,13 @@ Represents literal assembler code as des @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}]) Represents a table of jump addresses. The vector elements @var{lr0}, -etc., are @samp{label_ref} expressions. The mode @var{m} specifies +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 @samp{label_ref} +@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 @@ -3992,8 +5725,8 @@ Four special side-effect expression 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 @samp{reg} or @samp{mem}, but most -machines allow only a @samp{reg}. @var{m} must be the machine mode +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 @@ -4011,7 +5744,7 @@ value and use the result to address a @c Similar, but specifies incrementing @var{x} instead of decrementing it. @item (post_dec:@var{m} @var{x}) -Represents the same side effect as @samp{pre_decrement} but a different +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. @@ -4032,8 +5765,8 @@ combination pass could move the popping the meaning of the code. An instruction that can be represented with an embedded side effect -could also be represented using @samp{parallel} containing an additional -@samp{set} to describe how the address register is altered. This is not +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 @@ -4042,17 +5775,17 @@ in the machine description. @node Assembler, Insns, IncDec, RTL @section Assembler Instructions as Expressions -The RTX code @samp{asm_operands} represents a value produced by a +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)); +asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z)); @end example @noindent -is represented using a single @samp{asm_operands} RTX which represents +is represented using a single @code{asm_operands} RTX which represents the value that is stored in @code{outputvar}: @example @@ -4064,7 +5797,7 @@ the value that is stored in @code{output @end example @noindent -Here the operands of the @samp{asm_operands} RTX are the assembler +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 @@ -4072,8 +5805,8 @@ mode @var{m1} is the mode of the sum @co @code{*z}. When an @code{asm} statement has multiple output values, its insn has -several such @samp{set} RTX's inside of a @samp{parallel}. Each @samp{set} -contains a @samp{asm_operands}; all of these share the same assembler +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. @@ -4109,7 +5842,7 @@ If @var{i} is the last insn, this is a n @end table The @code{NEXT_INSN} and @code{PREV_INSN} pointers must always -correspond: if @var{i} is not the first insn, +correspond: if @var{insn} is not the first insn, @example NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn} @@ -4120,30 +5853,31 @@ is always true. Every insn has one of the following six expression codes: -@table @samp +@table @code @item insn -The expression code @samp{insn} is used for instructions that do not jump -and do not do function calls. Insns with code @samp{insn} have four +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 @samp{jump_insn} is used for instructions that may jump -(or, more generally, may contain @samp{label_ref} expressions). -@samp{jump_insn} insns have the same extra fields as @samp{insn} insns, -accessed in the same way. +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 @samp{call_insn} is used for instructions that may do +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. -@samp{call_insn} insns have the same extra fields as @samp{insn} insns, +@code{call_insn} insns have the same extra fields as @code{insn} insns, accessed in the same way. @item code_label -A @samp{code_label} insn represents a label that a jump insn can jump to. +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 @@ -4156,7 +5890,7 @@ jump instructions to indicate that the j They contain no information beyond the three standard fields. @item note -@samp{note} insns are used to represent additional debugging and +@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}. @@ -4186,52 +5920,67 @@ of debugging information. 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 -Here is a table of the extra fields of @samp{insn}, @samp{jump_insn} -and @samp{call_insn} insns: +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 REG_NOTES (@var{i}) -A list (chain of @samp{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. +@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 @samp{insn_list} expressions) of previous ``related'' +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 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 @samp{use}, @samp{clobber}, -@samp{asm}, @samp{addr_vec} or @samp{addr_diff_vec} expression. +@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 @samp{insn_list} +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 @samp{insn_list} expression (the next one in -the chain). The last @samp{insn_list} in the chain has a null pointer +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 @samp{insn_list} +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 -@samp{expr_list} expressions instead of @samp{insn_list}. There are four -kinds of register notes, which are distinguished by the machine mode of the -@samp{expr_list}, which a register note is really understood as being an -@code{enum reg_note}. The first operand @var{op} of the @samp{expr_list} -is data whose meaning depends on the kind of note. Here are the four -kinds: +@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 @@ -4242,8 +5991,8 @@ 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. +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 @@ -4298,23 +6047,26 @@ The register @var{op} is known to have n insn is reached. @end table -(The only difference between the expression codes @samp{insn_list} and -@samp{expr_list} is that the first operand of an @samp{insn_list} is +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 @samp{expr_list} is printed in the -ordinary way as an expression.) +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 @samp{call_insn}. +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, @samp{call}. +RTL expression code, @code{call}. -A @samp{call} expression has two operands, as follows: +A @code{call} expression has two operands, as follows: @example -(call @var{nbytes} (mem:@var{fm} @var{addr})) +(call (mem:@var{fm} @var{addr}) @var{nbytes}) @end example @noindent @@ -4324,7 +6076,7 @@ argument data being passed to the subrou the machine description) and @var{addr} represents the address of the subroutine. -For a subroutine that returns no value, the @samp{call} RTX as shown above +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}, @@ -4333,7 +6085,7 @@ the value is returned in a hard register @example (set (reg:@var{m} @var{r}) - (call @var{nbytes} (mem:@var{fm} @var{addr}))) + (call (mem:@var{fm} @var{addr}) @var{nbytes})) @end example @noindent @@ -4362,7 +6114,7 @@ value the call produced, and no operatio @noindent Between the call insn and this following insn there may intervene only a -stack-adjustment insn (and perhaps some @samp{note} insns). +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. @@ -4384,41 +6136,49 @@ no RTL objects are common to two functio @itemize @bullet @item -Each pseudo-register has only a single @samp{reg} object to represent it, +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 @samp{symbol_ref} object +For any symbolic label, there is only one @code{symbol_ref} object referring to it. @item -There is only one @samp{const_int} expression with value zero, +There is only one @code{const_int} expression with value zero, and only one with value one. @item -There is only one @samp{pc} expression. +There is only one @code{pc} expression. @item -There is only one @samp{cc0} expression. +There is only one @code{cc0} expression. @item -There is only one @samp{const_double} expression with mode +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 @samp{label_ref} appears in more than one place in the RTL +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 @samp{label_ref} is +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 @samp{mem} object is normally created for each static +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 @@ -4434,7 +6194,7 @@ after which the above rules are guarante 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 @samp{combine.c}. +@code{copy_substitutions} in @file{combine.c}. @end itemize @node Machine Desc, Machine Macros, RTL, Top @@ -4453,7 +6213,7 @@ See the next chapter for information on @menu * Patterns:: How to write instruction patterns. -* Example:: An explained example of a @samp{define_insn} pattern. +* 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. @@ -4475,9 +6235,9 @@ See the next chapter for information on 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 @samp{define_insn} expression. +output, all wrapped up in a @code{define_insn} expression. -A @samp{define_insn} is an RTL expression containing four or five operands: +A @code{define_insn} is an RTL expression containing four or five operands: @enumerate @item @@ -4498,14 +6258,14 @@ effect; they are equivalent to no name a @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 @samp{match_operand} -and @samp{match_dup} expressions that stand for operands of the +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 what the -instruction should look like. If the vector has multiple elements, -then the instruction looks like a @samp{parallel} expression -containing that many elements as described. +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 @@ -4542,7 +6302,7 @@ whose definition is up to you (@pxref{Mi @end enumerate @node Example, RTL Template, Patterns, Machine Desc -@section Example of @samp{define_insn} +@section Example of @code{define_insn} Here is an actual example of an instruction pattern, for the 68000/68020. @@ -4584,41 +6344,48 @@ controlled by special expression types t substitution of the operands. @table @code -@item (match_operand:@var{m} @var{n} @var{testfn} @var{constraint}) +@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{testfn} or this instruction +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 @samp{match_operand} +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 @samp{match_operand} +are numbered in the order of appearance in @code{match_operand} expressions. -@var{testfn} is a string that is the name of a C function that accepts -two arguments, a machine mode and an expression. During matching, -the function will be called with @var{m} as the mode argument -and the putative operand as the other argument. If it returns zero, -this instruction pattern fails to match. @var{testfn} may be -an empty string; then it means no test is to be done on the operand. - -@var{constraint} is explained later (@pxref{Constraints}). - -Most often, @var{testfn} is @code{"general_operand"}. It checks -that the putative operand is either a constant, a register or a -memory reference, and that it is valid for mode @var{m}. +@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{testfn} should be +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{testfn} should be +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, @@ -4630,13 +6397,80 @@ This expression is also a placeholder fo It is used when the operand needs to appear more than once in the insn. -In construction, @samp{match_dup} behaves exactly like -@samp{match_operand}: the operand is substituted into the insn being -constructed. But in matching, @samp{match_dup} behaves differently. +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 @samp{match_operand} appearing earlier in the recognition template, +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 @@ -4644,7 +6478,7 @@ a memory location in the usual way, but value used is the address of the location, not the contents of the location. -@samp{address} expressions never appear in RTL code, only in machine +@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. @@ -4653,22 +6487,22 @@ in use, the letter @samp{p} in the const 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 @samp{address} expression. If +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 @samp{address} +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 different variants of the assembler require +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 @@ -4698,12 +6532,14 @@ 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. +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 operand which are required by constraint to match +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 @@ -4746,7 +6582,7 @@ vector may be @code{operands}, or it may that you declare locally and initialize yourself. When an insn pattern has multiple alternatives in its constraints, often -the appearance of the assembler code determined mostly by which alternative +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, @@ -4758,7 +6594,7 @@ a pattern could use @code{which_alternat @example (define_insn "" - [(set (match_operand:SI 0 "general_operand" "r,m") + [(set (match_operand:SI 0 "general_operand" "=r,m") (const_int 0))] "" "* @@ -4770,7 +6606,7 @@ a pattern could use @code{which_alternat @node Constraints, Standard Names, Output Statement, Machine Desc @section Operand Constraints -Each @samp{match_operand} in an instruction pattern can specify a +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 @@ -4799,17 +6635,17 @@ supports in general. @item @samp{o} A memory operand is allowed, but only if the address is -@dfn{offsetable}. This means that adding a small integer (actually, +@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 offsetable; so is an +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 offsetable. More complicated indirect/indexed -addresses may or may not be offsetable depending on the other +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 @@ -4818,9 +6654,9 @@ by both @samp{<} (if the target machine 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 nonoffsetable address into an index +generate instructions which copy a nonoffsettable address into an index register. The idea is that the register can be used as a replacement -offsetable address. But this method requires that there be patterns +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 @@ -4869,7 +6705,7 @@ This is the range permitted as a shift c instructions. @item @samp{F} -An immediate floating operand (expression code @samp{const_double}) is +An immediate floating operand (expression code @code{const_double}) is allowed. @item @samp{G}, @samp{H} @@ -4886,12 +6722,12 @@ value. So why use @samp{s} instead of @ 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 -32 -and 31, better code results from loading the value into a register and +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 -32 to 31'', and then specifying @samp{Ks} in the operand +range -128 to 127'', and then specifying @samp{Ks} in the operand constraints. @item @samp{g} @@ -4912,7 +6748,8 @@ 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. +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 @@ -4925,8 +6762,8 @@ use the output-operand's number when pri An operand that is a valid memory address is allowed. This is for ``load address'' and ``push address'' instructions. -If @samp{p} is used in the constraint, the test-function in the -@samp{match_operand} must be @code{address_operand}. +@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 @@ -4939,7 +6776,7 @@ Contrast, therefore, the two instruction @example (define_insn "" - [(set (match_operand:SI 0 "general_operand" "r") + [(set (match_operand:SI 0 "general_operand" "=r") (plus:SI (match_dup 0) (match_operand:SI 1 "general_operand" "r")))] "" @@ -4951,7 +6788,7 @@ which has two operands, one of which mus @example (define_insn "" - [(set (match_operand:SI 0 "general_operand" "r") + [(set (match_operand:SI 0 "general_operand" "=r") (plus:SI (match_operand:SI 1 "general_operand" "0") (match_operand:SI 2 "general_operand" "r")))] "" @@ -5009,7 +6846,7 @@ registers is safe provided its predicate 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, than the constraints may also be +if the predicate is more selective, then the constraints may also be more selective. @item @@ -5020,14 +6857,15 @@ compiler knows how to copy a register in proper class in order to make an instruction valid. @item -A nonoffsetable memory reference can be reloaded by copying the +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 storing it in memory; it then -becomes an offsetable memory reference. So if the constraint uses the -letters @samp{o} or @samp{m}, constant operands are not a problem. +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 @@ -5053,17 +6891,17 @@ Here is how it is done for fullword logi @example (define_insn "iorsi3" - [(set (match_operand:SI 0 "general_operand" "=%m,d") - (ior:SI (match_operand:SI 1 "general_operand" "0,0") + [(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 constraint for operand 0 are not part of any alternative; their meaning +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. @@ -5086,16 +6924,16 @@ When operands must be copied into regist 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 determined mostly by which +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: +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") + [(set (match_operand:SI 0 "general_operand" "=r,m") (const_int 0))] "" "* @@ -5213,12 +7051,14 @@ refer to its address. They would have c 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 @samp{match_operand}. -Address operands are identified by writing an @samp{address} expression -around the @samp{match_operand}, not by their 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. +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 @@ -5230,12 +7070,12 @@ pattern in to accomplish a certain task. @table @asis @item @samp{mov@var{m}} -Here @var{m} is 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. +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 @samp{subreg} with mode @var{m} of a register whose -natural mode is wider than @var{m}, the effect of this instruction is +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. @@ -5245,36 +7085,57 @@ to copy a datum from one place to anothe 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 have a reload. - -Therefore, when given such a pair of operands, the pattern must -generate RTL which 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 you mustn't call -@code{force_reg} or any other such function which might generate new -pseudo registers. +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 is satisfied. +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. -In addition, the constraints 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 each of the registers). +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 @samp{subreg} +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{movsi_unaligned} +Like @samp{movsi} except that the memory reference will not trap +if loading or storing into unaligned memory. You must define this +pattern if you can pass structures or unions in registers when they +have less than a full word of alignment. + @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 @@ -5308,15 +7169,6 @@ in operand 0 and a remainder stored in o @item @samp{udivmod@var{m}4} Similar, but does unsigned division. -@item @samp{divmod@var{m}@var{n}4} -Like @samp{divmod@var{m}4} except that only the dividend has mode -@var{m}; the divisor, quotient and remainder have mode @var{n}. -For example, the Vax has a @samp{divmoddisi4} instruction -(but it is omitted from the machine description, because it -is so slow that it is faster to compute remainders by the -circumlocution that the compiler will use if this instruction is -not available). - @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 @@ -5360,8 +7212,8 @@ Compare operand 0 and operand 1, and set The RTL pattern should look like this: @example -(set (cc0) (minus (match_operand:@var{m} 0 @dots{}) - (match_operand:@var{m} 1 @dots{}))) +(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 @@ -5381,6 +7233,8 @@ The RTL pattern should look like this: 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}} @@ -5389,8 +7243,14 @@ in lexicographic order. The effect of t the condition codes. @item @samp{float@var{m}@var{n}2} -Convert 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}). +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 @@ -5435,7 +7295,7 @@ 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}. +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}. @@ -5463,26 +7323,27 @@ for operands 1 and 2. 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 @samp{eq}, @samp{lt} or @samp{leu}. +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. -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}. +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 @samp{label_ref} +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 @samp{const_int}); +(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 @@ -5490,7 +7351,7 @@ pattern. It is supplied for the sake of to put this information into the assembler code; they can put it in the RTL instead of operand 1. -Operand 0 should be a @samp{mem} RTX whose address is the address of +Operand 0 should be a @code{mem} RTX whose address is the address of the function. @item @samp{call_value} @@ -5507,6 +7368,11 @@ Subroutine return instruction. This ins 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: @@ -5519,7 +7385,8 @@ The index to dispatch on, which has mode The lower bound for indices in the table, an integer constant. @item -The upper bound for indices in the table, an integer constant. +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. @@ -5533,8 +7400,8 @@ but it is always provided as an operand. A label that precedes the table itself. @end enumerate -The table is a @samp{addr_vec} or @samp{addr_diff_vec} inside of a -@samp{jump_insn}. The number of elements in the table is one plus the +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} @@ -5545,8 +7412,8 @@ 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 -absolute address to jump to; otherwise, it is an offset which counts -from the address of the table. +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 @@ -5661,7 +7528,7 @@ instruction. A ``compare'' instruction whose RTL looks like this: @example -(set (cc0) (minus @var{operand} (const_int 0))) +(set (cc0) (compare @var{operand} (const_int 0))) @end example @noindent @@ -5702,9 +7569,9 @@ optimized away, but they do occasionally compilations. When an instruction has the constraint letter @samp{o}, the reload -pass may generate instructions which copy a nonoffsetable address into +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 offsetable address. In order for these generated +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. @@ -5754,7 +7621,7 @@ output a compare-and-branch instruction It also works to define patterns for compare-and-branch instructions. In optimizing compilation, the pair of compare and branch instructions -will be combined accoprding to these patterns. But this does not happen +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. @@ -5786,49 +7653,53 @@ A definition looks like this: @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 @samp{define_insn}. +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 instructions. The optimization applies to a sequence of -instructions when @var{insn-pattern-1} matches the first one, -@var{insn-pattern-2} matches the next, and so on.@refill - -@var{insn-pattern-1} and so on look @emph{almost} like the second operand -of @code{define_insn}. There is one important difference: this pattern is -an RTX, not a vector. If the @code{define_insn} pattern would be a vector -of one element, the @var{insn-pattern} should be just that element, no -vector. If the @code{define_insn} pattern would have multiple elements -then the @var{insn-pattern} must place the vector inside an explicit -@code{parallel} RTX.@refill - -The operands of the instructions 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 instruction patterns in the definition. So, you can check -for identical operands in two instructions by using @code{match_operand} -in one instruction and @code{match_dup} in the other. +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 optimization, but they will -be validated afterward, so write constraints that are sure to fit whenever -the optimization is applied. It is safe to use @code{"g"} for each -operand. - -Once a sequence of instructions matches the patterns, the @var{condition} -is checked. This is a C expression which makes the final decision whether -to perform the optimization (do so if the expression is nonzero). If +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 instructions that matches 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 optimizer can check which operands have ended up -in which kinds of registers, just by looking at the operands. +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 @samp{note} insns that +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 @@ -5839,27 +7710,26 @@ be used for the last time (from the valu 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 instructions with -one new instruction. The @var{template} controls ultimate output of -assembler code for this combined instruction. 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 instructions. +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 instruction patterns, and it does not have an opportunity to match -them. The peephole optimizer definition itself serves as the instruction -pattern to control how the instruction is output. - -Defined peephole optimizers are run in the last jump optimization pass, so -the instructions they produce are never combined or rearranged -automatically in any way. +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") + (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])" "* @@ -5899,28 +7769,77 @@ 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 -@samp{define_expand} to specify how to generate the sequence of RTL. +@code{define_expand} to specify how to generate the sequence of RTL. -A @samp{define_expand} is an RTL expression that looks almost like a -@samp{define_insn}; but, unlike the latter, a @samp{define_expand} is used +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 @samp{define_expand} RTX has four operands: +A @code{define_expand} RTX has four operands: @itemize @bullet @item -The name. Each @samp{define_expand} must have a name, since the only +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 -@samp{define_peephole} in that it is a vector of RTL expressions +@code{define_peephole} in that it is a vector of RTL expressions each being one insn. @item @@ -5928,7 +7847,7 @@ The condition, a string containing a C e 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 -@samp{define_insn} that has a standard name. +@code{define_insn} that has a standard name. @item The preparation statements, a string containing zero or more C @@ -5937,31 +7856,36 @@ 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 @samp{emit_insn}, etc. +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 @samp{match_operand} in its first +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 @samp{match_dup}. +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 -@samp{define_expand}. Internal operands are substituted into the RTL -template with @samp{match_dup}, never with @samp{match_operand}. 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 @samp{match_dup} can find them. +@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, @@ -6003,16 +7927,16 @@ Here is an example, the definition of le @end example @noindent -This example uses @samp{define_expand} so that it can generate an RTL insn +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 there would be possible to use a -@samp{define_insn} in that case. Here is another case (zero-extension on -the 68000) which makes more use of the power of @samp{define_expand}: +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" @@ -6020,7 +7944,7 @@ the 68000) which makes more use of the p (const_int 0)) (set (strict_low_part (subreg:HI - (match_operand:SI 0 "general_operand" "") + (match_dup 0) 0)) (match_operand:HI 1 "general_operand" ""))] "" @@ -6037,11 +7961,11 @@ temporary register if it refers to @code 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 @samp{and}-ing the result +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 -@samp{const_int} because the constant value is too large to be legitimate +@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 @samp{and}. +@code{force_reg} and then the register used in the @code{and}. @example (define_expand "zero_extendhisi2" @@ -6056,6 +7980,11 @@ on this machine. So it must be copied i 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 @@ -6065,16 +7994,18 @@ link to it. The header file @file{confi compiler source files include @file{config.h}. @menu -* Run-time Target:: Defining -m options like -m68000 and -m68020. +* 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 Names:: Specifying names of subroutines to call automatically. +* 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. -* Assembler Format:: Defining how to write insns and pseudo-ops to output. +* 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 @@ -6087,12 +8018,21 @@ define the predefined macros that identi These macros will be predefined unless the @samp{-ansi} option is specified. -For example, on the Sun, one can use the value +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 @@ -6180,6 +8120,9 @@ number. This means that bit-field instr 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. @@ -6204,7 +8147,19 @@ Width of a pointer, in bits. Alignment required for pointers stored in memory, in bits. @item PARM_BOUNDARY -Alignment required for function parameters on the stack, in bits. +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 @@ -6217,6 +8172,18 @@ Alignment required for a function entry @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;}. @@ -6239,10 +8206,18 @@ of some instances of PCC: a bit field wh @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 @@ -6299,6 +8274,13 @@ If a register has 0 in @code{CALL_USED_R 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 @@ -6310,9 +8292,9 @@ 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 +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 +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. @@ -6322,15 +8304,15 @@ controlled by target switches, then GCC 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 @var{regno} 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 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. @@ -6353,17 +8335,17 @@ optimizations that take place after regi 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 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.) +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_REGS (@var{regno}, @var{mode}) +@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}. @@ -6387,8 +8369,18 @@ are equivalent, a suitable definition is #define HARD_REGNO_MODE_OK(REGNO, MODE) 1 @end example -It is not necessary for this macro to check for fixed register numbers -because the allocation mechanism considers them to be always occupied. +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 @@ -6397,34 +8389,27 @@ can hold integers can safely @emph{hold} mode, whether or not floating arithmetic can be done on it in those registers. -The true significance of special floating registers is rather than -non-floating-point machine modes @emph{may not} go in those registers. -This is true if the floating registers normalize any value stored in -them, because storing a non-floating value there would garble it. 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. - -Sometimes there are floating registers that 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. - -It is obligatory to support floating point `move' instructions into -and out of any registers that can hold fixed point values, because -unions and structures (which have modes @samp{SImode} or -@samp{DImode}) can be in those registers and they may have floating -point members. - -There may also be a need to support fixed point `move' 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 `move' instructions -must be designed to avoid ever trying to reload into a floating point -register. +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 @@ -6452,18 +8437,20 @@ hardware determines which register this 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 in the reload pass, in -the function @code{reload}, and it 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 do without a frame -pointer. The compiler recognizes those cases and automatically gives -the function a frame pointer regardless of what +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 @@ -6501,7 +8488,7 @@ 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 @samp{mem} RTX, the +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 @@ -6517,8 +8504,8 @@ register, define this macro as the regis 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 @samp{mem} which refers to the -frame pointer. If the value is a @samp{mem}, the compiler assumes it +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. @@ -6576,6 +8563,12 @@ classes: for each class, which classes c 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 @@ -6683,7 +8676,7 @@ for a @samp{moveq} instruction, the valu @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 @samp{const_double}, by returning @code{NO_REGS} +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. @@ -6733,12 +8726,12 @@ not one of those letters, the value shou 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 @samp{const_double}, is in the appropriate range and return 1 if +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 Names, Register Classes, Machine Macros +@node Stack Layout, Library Calls, Register Classes, Machine Macros @section Describing Stack Layout @table @code @@ -6804,6 +8797,35 @@ of the first parameter's shadow location 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 @@ -6832,6 +8854,9 @@ nothing (the caller pops all). When thi @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 @@ -6860,6 +8885,19 @@ to tell the function where to put the va 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 @@ -6900,15 +8938,20 @@ arguments; @var{mode}, the machine mode 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{...} in the called function's prototype. +correspond to @samp{@dots{}} in the called function's prototype. -The value of the expression should either be a @samp{reg} RTX for the +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 @@ -6956,11 +8999,11 @@ for the data type of the function which if the args are to a compiler support library function. @item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) -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 +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 @@ -7012,6 +9055,15 @@ frame pointer is in wanted, the macro ca @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}. @@ -7027,16 +9079,55 @@ figure them out, compile a small program system's installed C compiler and look at the assembler code that results. -@item EXIT_IGNORES_STACK +@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 for which frame -pointers are maintained. It is never possible to delete a final stack -adjustment in a function that has no frame pointer, and the compiler -knows this regardless of @code{EXIT_IGNORES_STACK}. +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 @@ -7094,31 +9185,69 @@ Even if your machine description specifi 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 Names, Addressing Modes, Stack Layout, Machine Macros -@section Library Subroutine Names +@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 a full-word by a full-word. If you do not define this -macro, the default name is used, which is @code{_udivsi3}, a function -defined in @file{gnulib}. +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 a full-word by a full-word. If you do not -define this macro, the default name is used, which is @code{_umodsi3}, -a function defined in @file{gnulib}. +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, Misc, Library Names, Machine Macros +@node Addressing Modes, Delayed Branch, Library Calls, Machine Macros @section Addressing Modes @table @code @@ -7133,8 +9262,8 @@ 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 @samp{symbol_ref} and @samp{label_ref} expressions and -@samp{const} arithmetic expressions. +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 @@ -7142,7 +9271,9 @@ are supported. @item MAX_REGS_PER_ADDRESS A number, the maximum number of registers that can appear in a valid -memory address. +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};} @@ -7176,8 +9307,19 @@ for index registers, and so on). Then o 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} (asumed to be a @code{reg} +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 @@ -7186,7 +9328,7 @@ requires two variant definitions, of whi controls the one actually used. @item REG_OK_FOR_INDEX_P (@var{x}) -A C expression that is nonzero if @var{x} (asumed to be a @code{reg} +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 @@ -7239,13 +9381,230 @@ You may assume that @var{addr} is a vali @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 @samp{const_double} or it satisfies +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 -@samp{const_double} is valid and anything @code{CONSTANT_P} is valid.@refill +@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 Misc, Condition Code, Addressing Modes, Machine Macros +@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 @@ -7290,9 +9649,9 @@ and @samp{-funsigned-char}. Define this if the preprocessor should ignore @code{#sccs} directives and print no error message. -@item IDENT_DIRECTIVE -Define this if the preprocessor should ignore @code{#ident} 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 @@ -7300,7 +9659,42 @@ 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. +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 @@ -7348,7 +9742,7 @@ mismatch, it also makes for better code @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. +-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. @@ -7363,24 +9757,31 @@ can be @item FUNCTION_MODE An alias for the machine mode used for memory references to functions -being called, in @samp{call} RTL expressions. On most machines this +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 @samp{define_insn} and @samp{define_peephole} patterns. For example, -it might expand into @samp{struct machine_info}; then it would be up +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 @samp{const_int}, @samp{const}, @samp{symbol_ref}, @samp{label_ref} -and @samp{const_double}. Each case must ultimately reach a +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 @@ -7394,59 +9795,7 @@ Define this to be nonzero if the charact by default in identifier names. @end table -@node Condition Code, Assembler Format, Misc, 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 for the initial value of the @code{mdep} field. It -defaults to 0. - -@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 -@samp{parallel} RTXs containing various @samp{reg}, @samp{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 Assembler Format,, Condition Code, Machine Macros +@node Assembler Format,, Misc, Machine Macros @section Output of Assembler Code @table @code @@ -7473,6 +9822,14 @@ 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 @@ -7481,6 +9838,26 @@ the very beginning of the command given 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. @@ -7493,6 +9870,32 @@ checking for certain assembler construct 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 @@ -7515,6 +9918,38 @@ A C string constant for the assembler op 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 @@ -7545,7 +9980,7 @@ 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 infomation. +more information. @item DBX_NO_XREFS Define this macro if DBX on your system does not support the construct @@ -7569,11 +10004,16 @@ a different character instead, define th 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 +@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}) @@ -7595,7 +10035,7 @@ that is, available for reference from ot 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{name}, @var{decl}) +@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 @@ -7606,15 +10046,15 @@ This macro need not be defined if it doe 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}. +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}. +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} @@ -7636,8 +10076,8 @@ fprintf (@var{stream}, "L%s%d:\n", @var{ 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 @samp{jump_insn} containing an -@samp{addr_vec} or @samp{addr_diff_vec}). +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. @@ -7646,15 +10086,25 @@ If this macro is not defined, these labe @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. +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 @@ -7731,10 +10181,18 @@ instruction to assemble a @code{float} c @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{exp})} to output this value as an -assembler expression.@refill +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 @@ -7760,28 +10218,40 @@ A C statement to output to the stdio str 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}) +@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. 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. +@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}) +@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. 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. +@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 @@ -7793,10 +10263,7 @@ information for the debugger in use is a @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, the assembler code @samp{.ident "@var{string}"} -will be output by default. - -This macro is significant only if @code{IDENT_DIRECTIVE} is defined. +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 @@ -7833,6 +10300,9 @@ that includes @samp{%}-sequences to subs 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. @@ -7880,6 +10350,13 @@ When the machine description has a speci 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 @@ -7900,10 +10377,10 @@ definitions are correct for most assembl @node Config,, Machine Macros, Top @chapter The Configuration File -The configuration file @file{config-@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 most all configuration files are identical. But +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 @@ -7914,7 +10391,37 @@ 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