diff options
| author | kan <kan@FreeBSD.org> | 2003-07-11 03:40:53 +0000 |
|---|---|---|
| committer | kan <kan@FreeBSD.org> | 2003-07-11 03:40:53 +0000 |
| commit | b2a8872fbe1ec1c49094559ac7b78e6ea4ab7180 (patch) | |
| tree | f6b0610f4a17fd26aa234354f050080f789861a4 /contrib/gcc/doc | |
| parent | 52e69d78eee5612ac195e0701a5cebe40d1ab0e1 (diff) | |
| download | FreeBSD-src-b2a8872fbe1ec1c49094559ac7b78e6ea4ab7180.zip FreeBSD-src-b2a8872fbe1ec1c49094559ac7b78e6ea4ab7180.tar.gz | |
Gcc 3.3.1-pre as of 2003-07-11.
Diffstat (limited to 'contrib/gcc/doc')
31 files changed, 6934 insertions, 3446 deletions
diff --git a/contrib/gcc/doc/bugreport.texi b/contrib/gcc/doc/bugreport.texi index 1ac26c5..d9613ef 100644 --- a/contrib/gcc/doc/bugreport.texi +++ b/contrib/gcc/doc/bugreport.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001 Free Software Foundation, Inc. +@c 1999, 2000, 2001, 2003 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -14,29 +14,14 @@ When you encounter a problem, the first thing to do is to see if it is already known. @xref{Trouble}. 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 GCC work -better. Bug reports are your contribution to the maintenance of GCC@. - -Since the maintainers are very overloaded, we cannot respond to every -bug report. However, if the bug has not been fixed, we are likely to -send you a patch and ask you to tell us whether it works. - -In order for a bug report to serve its purpose, you must include the -information that makes for fixing the bug. - @menu * Criteria: Bug Criteria. Have you really found a bug? -* Where: Bug Lists. Where to send your bug report. * Reporting: Bug Reporting. How to report a bug effectively. -* GNATS: gccbug. You can use a bug reporting tool. * Known: Trouble. Known problems. * Help: Service. Where to ask for help. @end menu -@node Bug Criteria,Bug Lists,,Bugs +@node Bug Criteria,Bug Reporting,,Bugs @section Have You Found a Bug? @cindex bug criteria @@ -64,13 +49,9 @@ prevent the assembler from being run. If the compiler produces valid assembly code that does not correctly execute the input source code, that is a compiler bug. -However, you must double-check to make sure, because you may have run -into an incompatibility between GNU C and traditional C -(@pxref{Incompatibilities}). These incompatibilities might be considered -bugs, but they are inescapable consequences of valuable features. - -Or you may have a program whose behavior is undefined, which happened -by chance to give the desired results with another C or C++ compiler. +However, you must double-check to make sure, because you may have a +program whose behavior is undefined, which happened by chance to give +the desired results with another C or C++ compiler. For example, in many nonoptimizing compilers, you can write @samp{x;} at the end of a function instead of @samp{return x;}, with the same @@ -103,292 +84,11 @@ If you are an experienced user of one of the languages GCC supports, your suggestions for improvement of GCC are welcome in any case. @end itemize -@node Bug Lists,Bug Reporting,Bug Criteria,Bugs -@section Where to Report Bugs -@cindex bug report mailing lists -@kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org -Send bug reports for the GNU Compiler Collection to -@email{gcc-bugs@@gcc.gnu.org}. In accordance with the GNU-wide -convention, in which bug reports for tool ``foo'' are sent -to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org} -may also be used; it will forward to the address given above. - -Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or -more up-to-date bug reporting instructions before you post a bug report. - -@node Bug Reporting,gccbug,Bug Lists,Bugs -@section How to Report Bugs +@node Bug Reporting,,Bug Criteria,Bugs +@section How and where to Report Bugs @cindex compiler bugs, reporting -The fundamental principle of reporting bugs usefully is this: -@strong{report all the facts}. If you are not sure whether to state a -fact or leave it out, state it! - -Often people omit facts because they think they know what causes the -problem and they conclude that some details don't matter. Thus, you might -assume that the name of the variable you use in an example does not matter. -Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a -stray memory reference which happens to fetch from the location where that -name is stored in memory; perhaps, if the name were different, the contents -of that location would fool the compiler into doing the right thing despite -the bug. Play it safe and give a specific, complete example. That is the -easiest thing for you to do, and the most helpful. - -Keep in mind that the purpose of a bug report is to enable someone 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?'' This cannot help us fix a bug, so it is basically useless. We -respond by asking for enough details to enable us to investigate. -You might as well expedite matters by sending them to begin with. - -Try to make your bug report self-contained. If we have to ask you for -more information, it is best if you include all the previous information -in your response, as well as the information that was missing. - -Please report each bug in a separate message. This makes it easier for -us to track which bugs have been fixed and to forward your bugs reports -to the appropriate maintainer. - -To enable someone to investigate the bug, you should include all these -things: - -@itemize @bullet -@item -The version of GCC@. You can get this by running it with the -@option{-v} option. - -Without this, we won't know whether there is any point in looking for -the bug in the current version of GCC@. - -@item -A complete input file that will reproduce the bug. If the bug is in the -C preprocessor, send a source file and any header files that it -requires. If the bug is in the compiler proper (@file{cc1}), send the -preprocessor output generated by adding @option{-save-temps} to the -compilation command (@pxref{Debugging Options}). When you do this, use -the same @option{-I}, @option{-D} or @option{-U} options that you used in -actual compilation. Then send the @var{input}.i or @var{input}.ii files -generated. - -A single statement is not enough of an example. In order to compile it, -it must be embedded in a complete file of compiler input; and the bug -might depend on the details of how this is done. - -Without a real example one can compile, all anyone can do about your bug -report is wish you luck. It would be futile to try to guess how to -provoke the bug. For example, bugs in register allocation and reloading -frequently depend on every little detail of the function they happen in. - -Even if the input file that fails comes from a GNU program, you should -still send the complete test case. Don't ask the GCC maintainers to -do the extra work of obtaining the program in question---they are all -overworked as it is. Also, the problem may depend on what is in the -header files on your system; it is unreliable for the GCC maintainers -to try the problem with the header files available to them. By sending -CPP output, you can eliminate this source of uncertainty and save us -a certain percentage of wild goose chases. - -@item -The command arguments you gave GCC to compile that example -and observe the bug. For example, did you use @option{-O}? To guarantee -you won't omit something important, list all the options. - -If we were to try to guess the arguments, we would probably guess wrong -and then we would not encounter the bug. - -@item -The type of machine you are using, and the operating system name and -version number. - -@item -The operands you gave to the @code{configure} command when you installed -the compiler. - -@item -A complete list of any modifications you have made to the compiler -source. (We don't promise to investigate the bug unless it happens in -an unmodified compiler. But if you've made modifications and don't tell -us, then you are sending us on a wild goose chase.) - -Be precise about these changes. A description in English is not -enough---send a context diff for them. - -Adding files of your own (such as a machine description for a machine we -don't support) is a modification of the compiler source. - -@item -Details of any other deviations from the standard procedure for installing -GCC@. - -@item -A description of what behavior you observe that you believe is -incorrect. For example, ``The compiler gets a fatal signal,'' or, -``The assembler instruction at line 208 in the output is incorrect.'' - -Of course, if the bug is that the compiler gets a fatal signal, then one -can't miss it. But if the bug is incorrect output, the maintainer might -not notice unless it is glaringly wrong. None of us has time to study -all the assembler code from a 50-line C program just on the chance that -one instruction might be wrong. We need @emph{you} to do this part! - -Even if the problem you experience is a fatal signal, you should still -say so explicitly. Suppose something strange is going on, such as, your -copy of the compiler is out of synch, or you have encountered a bug in -the C library on your system. (This has happened!) Your copy might -crash and the copy here would not. If you @i{said} to expect a crash, -then when the compiler here fails to crash, we would know that the bug -was not happening. If you don't say to expect a crash, then we would -not know whether the bug was happening. We would not be able to draw -any conclusion from our observations. - -If the problem is a diagnostic when compiling GCC with some other -compiler, say whether it is a warning or an error. - -Often the observed symptom is incorrect output when your program is run. -Sad to say, this is not enough information unless the program is short -and simple. None of us has time to study a large program 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 us which source line -it is, and what incorrect result happens when that line is executed. A -person who understands the program can find this as easily as finding a -bug in the program itself. - -@item -If you send examples of assembler code output from GCC, -please use @option{-g} when you make them. The debugging information -includes source line numbers which are essential for correlating the -output with the input. - -@item -If you wish to mention something in the GCC source, refer to it by -context, not by line number. - -The line numbers in the development sources don't match those in your -sources. Your line numbers would convey no useful information to the -maintainers. - -@item -Additional information from a debugger might enable someone to find a -problem on a machine which he does not have available. However, you -need to think when you collect this information if you want it to have -any chance of being useful. - -@cindex backtrace for bug reports -For example, many people send just a backtrace, but that is never -useful by itself. A simple backtrace with arguments conveys little -about GCC because the compiler is largely data-driven; the same -functions are called over and over for different RTL insns, doing -different things depending on the details of the insn. - -Most of the arguments listed in the backtrace are useless because they -are pointers to RTL list structure. The numeric values of the -pointers, which the debugger prints in the backtrace, have no -significance whatever; all that matters is the contents of the objects -they point to (and most of the contents are other such pointers). - -In addition, most compiler passes consist of one or more loops that -scan the RTL insn sequence. The most vital piece of information about -such a loop---which insn it has reached---is usually in a local variable, -not in an argument. - -@findex debug_rtx -What you need to provide in addition to a backtrace are the values of -the local variables for several stack frames up. When a local -variable or an argument is an RTX, first print its value and then use -the GDB command @code{pr} to print the RTL expression that it points -to. (If GDB doesn't run on your machine, use your debugger to call -the function @code{debug_rtx} with the RTX as an argument.) In -general, whenever a variable is a pointer, its value is no use -without the data it points to. -@end itemize - -Here are some things that are not necessary: - -@itemize @bullet -@item -A description of the envelope of the bug. - -Often people who encounter a bug spend a lot of time investigating -which changes to the input file will make the bug go away and which -changes will not affect it. - -This is often time consuming and not very useful, because the way we -will find the bug is by running a single example under the debugger with -breakpoints, not by pure deduction from a series of examples. You might -as well 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. Errors in the output will be -easier to spot, running under the debugger will take less time, etc. -Most GCC bugs involve just one function, so the most straightforward -way to simplify an example is to delete all the function definitions -except the one where the bug occurs. Those earlier in the file may be -replaced by external declarations if the crucial function depends on -them. (Exception: inline functions may affect compilation of functions -defined later in the file.) - -However, simplification is not vital; if you don't want to do this, -report the bug anyway and send the entire test case you used. - -@item -In particular, some people insert conditionals @samp{#ifdef BUG} around -a statement which, if removed, makes the bug not happen. These are just -clutter; we won't pay any attention to them anyway. Besides, you should -send us cpp output, and that can't have conditionals. - -@item -A patch for the bug. - -A patch for the bug is useful if it is a good one. But don't omit the -necessary information, such as the test case, on the assumption that a -patch is all we need. We might see problems with your patch and decide -to fix the problem another way, or we might not understand it at all. - -Sometimes with a program as complicated as GCC 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 the example, we won't be able to -construct one, so we won't be able to verify that the bug is fixed. - -And if we can't understand what bug you are trying to fix, or why your -patch should be an improvement, we won't install it. A test case will -help us to understand. - -See @uref{http://gcc.gnu.org/contribute.html} -for guidelines on how to make it easy for us to -understand and install your patches. - -@item -A guess about what the bug is or what it depends on. - -Such guesses are usually wrong. Even I can't guess right about such -things without first using the debugger to find the facts. - -@item -A core dump file. - -We have no way of examining a core dump for your type of machine -unless we have an identical system---and if we do have one, -we should be able to reproduce the crash ourselves. -@end itemize - -@node gccbug,, Bug Reporting, Bugs -@section The gccbug script -@cindex gccbug script - -To simplify creation of bug reports, and to allow better tracking of -reports, we use the GNATS bug tracking system. Part of that system is -the @code{gccbug} script. This is a Unix shell script, so you need a -shell to run it. It is normally installed in the same directory where -@code{gcc} is installed. - -The gccbug script is derived from send-pr, @pxref{using -send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When -invoked, it starts a text editor so you can fill out the various fields -of the report. When the you quit the editor, the report is automatically -send to the bug reporting address. - -A number of fields in this bug report form are specific to GCC, and are -explained at @uref{http://gcc.gnu.org/gnats.html}. +Bugs should be reported to our bug database. Please refer to +@uref{http://gcc.gnu.org/bugs.html} for up-to-date instructions how to +submit bug reports. Copies of this file in HTML (@file{bugs.html}) and +plain text (@file{BUGS}) are also part of GCC releases. diff --git a/contrib/gcc/doc/c-tree.texi b/contrib/gcc/doc/c-tree.texi index 35da90a..8f5a5bb 100644 --- a/contrib/gcc/doc/c-tree.texi +++ b/contrib/gcc/doc/c-tree.texi @@ -84,8 +84,8 @@ we will refer to trees in ordinary type, rather than in @code{this font}, except when talking about the actual C type @code{tree}. You can tell what kind of node a particular tree is by using the -@code{TREE_CODE} macro. Many, many macros take a trees as input and -return trees as output. However, most macros require a certain kinds of +@code{TREE_CODE} macro. Many, many macros take trees as input and +return trees as output. However, most macros require a certain kind of tree node as input. In other words, there is a type-system for trees, but it is not reflected in the C type-system. @@ -1771,6 +1771,7 @@ This macro returns the attributes on the type @var{type}. @tindex CLEANUP_POINT_EXPR @tindex ARRAY_REF @tindex VTABLE_REF +@tindex VA_ARG_EXPR The internal representation for expressions is for the most part quite straightforward. However, there are a few facts that one must bear in @@ -2062,7 +2063,7 @@ integral type. The result of a @code{TRUNC_DIV_EXPR} is always rounded towards zero. The @code{TRUNC_MOD_EXPR} of two operands @code{a} and @code{b} is -always @code{a - a/b} where the division is as if computed by a +always @code{a - (a/b)*b} where the division is as if computed by a @code{TRUNC_DIV_EXPR}. @item ARRAY_REF @@ -2126,25 +2127,21 @@ These nodes represent @code{?:} expressions. The first operand is of boolean or integral type. If it evaluates to a nonzero value, the second operand should be evaluated, and returned as the value of the expression. Otherwise, the third operand is evaluated, and returned as -the value of the expression. As a GNU extension, the middle operand of -the @code{?:} operator may be omitted in the source, like this: - -@example -x ? : 3 -@end example -@noindent -which is equivalent to - -@example -x ? x : 3 -@end example - -@noindent -assuming that @code{x} is an expression without side-effects. However, -in the case that the first operation causes side effects, the -side-effects occur only once. Consumers of the internal representation -do not need to worry about this oddity; the second operand will be -always be present in the internal representation. +the value of the expression. + +The second operand must have the same type as the entire expression, +unless it unconditionally throws an exception or calls a noreturn +function, in which case it should have void type. The same constraints +apply to the third operand. This allows array bounds checks to be +represented conveniently as @code{(i >= 0 && i < 10) ? i : abort()}. + +As a GNU extension, the C language front-ends allow the second +operand of the @code{?:} operator may be omitted in the source. +For example, @code{x ? : 3} is equivalent to @code{x ? x : 3}, +assuming that @code{x} is an expression without side-effects. +In the tree representation, however, the second operand is always +present, possibly protected by @code{SAVE_EXPR} if the first +argument does cause side-effects. @item CALL_EXPR These nodes are used to represent calls to functions, including @@ -2312,4 +2309,10 @@ The first operand is the expression that computes the vtable reference. The second operand is the @code{VAR_DECL} of the vtable. The third operand is an @code{INTEGER_CST} of the byte offset into the vtable. +@item VA_ARG_EXPR +This node is used to implement support for the C/C++ variable argument-list +mechanism. It represents expressions like @code{va_arg (ap, type)}. +Its @code{TREE_TYPE} yields the tree representation for @code{type} and +its sole argument yields the representation for @code{ap}. + @end table diff --git a/contrib/gcc/doc/collect2.texi b/contrib/gcc/doc/collect2.texi index 2cd1d3c..a3d43b2 100644 --- a/contrib/gcc/doc/collect2.texi +++ b/contrib/gcc/doc/collect2.texi @@ -52,7 +52,7 @@ if specified. @end itemize ``The compiler's search directories'' means all the directories where -@code{gcc} searches for passes of the compiler. This includes +@command{gcc} searches for passes of the compiler. This includes directories that you specify with @option{-B}. Cross-compilers search a little differently: diff --git a/contrib/gcc/doc/compat.texi b/contrib/gcc/doc/compat.texi index 3c2931b..274368a 100644 --- a/contrib/gcc/doc/compat.texi +++ b/contrib/gcc/doc/compat.texi @@ -130,11 +130,11 @@ C++ library. This requires specifying the location of the C++ library header files when invoking the compiler whose usual library is not being used. The location of GCC's C++ header files depends on how the GCC build was configured, but can be seen by using the G++ @option{-v} option. -With default configuration options for G++ 3.2 the compile line for a +With default configuration options for G++ 3.3 the compile line for a different C++ compiler needs to include @example - -I@var{gcc_install_directory}/include/c++/3.2 + -I@var{gcc_install_directory}/include/c++/3.3 @end example Similarly, compiling code with G++ that must use a C++ library other diff --git a/contrib/gcc/doc/contrib.texi b/contrib/gcc/doc/contrib.texi index 8cafaeb..1c3aa25 100644 --- a/contrib/gcc/doc/contrib.texi +++ b/contrib/gcc/doc/contrib.texi @@ -1,5 +1,5 @@ -@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002 -@c Free Software Foundation, Inc. +@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000, +@c 2001,2002,2003 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -10,8 +10,8 @@ The GCC project would like to thank its many contributors. Without them the project would not have been nearly as successful as it has been. Any omissions in this list are accidental. Feel free to contact -@email{law@@redhat.com} if you have been left out -or some of your contributions are not listed. Please keep this list in +@email{law@@redhat.com} or @email{gerald@@pfeifer.com} if you have been left +out or some of your contributions are not listed. Please keep this list in alphabetical order. @itemize @bullet @@ -29,7 +29,7 @@ James van Artsdalen wrote the code that makes efficient use of the Intel 80387 register stack. @item -Alasdair Baird for various bugfixes. +Alasdair Baird for various bug fixes. @item Gerald Baumgartner added the signature extension to the C++ front end. @@ -41,7 +41,14 @@ Godmar Back for his Java improvements and encouragement. Scott Bambrough for help porting the Java compiler. @item -Jon Beniston for his Win32 port of Java. +Wolfgang Bangerth for processing tons of bug reports. + +@item +Jon Beniston for his Windows port of Java. + +@item +Daniel Berlin for better DWARF2 support, faster/better optimizations, +improved alias analysis, plus migrating us to Bugzilla. @item Geoff Berry for his Java object serialization work and various patches. @@ -51,6 +58,9 @@ Eric Blake for helping to make GCJ and libgcj conform to the specifications. @item +Segher Boessenkool for various fixes. + +@item Hans-J. Boehm for his @uref{http://www.hpl.hp.com/personal/Hans_Boehm/gc/,, garbage collector}, IA-64 libffi port, and other Java work. @@ -59,6 +69,9 @@ Neil Booth for work on cpplib, lang hooks, debug hooks and other miscellaneous clean-ups. @item +Eric Botcazou for fixing middle- and backend bugs left and right. + +@item Per Bothner for his direction via the steering committee and various improvements to our infrastructure for supporting new languages. Chill front end implementation. Initial implementations of @@ -105,7 +118,10 @@ John Carr for his alias work, SPARC hacking, infrastructure improvements, previous contributions to the steering committee, loop optimizations, etc. @item -Steve Chamberlain for support for the Hitachi SH and H8 processors +Stephane Carrez for 68HC11 and 68HC12 ports. + +@item +Steve Chamberlain for support for the Renesas SH and H8 processors and the PicoJava processor, and for GCJ config fixes. @item @@ -158,6 +174,10 @@ Russell Davidson for fstream and stringstream fixes in libstdc++. Mo DeJong for GCJ and libgcj bug fixes. @item +DJ Delorie for the DJGPP port, build and libiberty maintenance, and +various bug fixes. + +@item Gabriel Dos Reis for contributions to g++, contributions and maintenance of GCC diagnostics infrastructure, libstdc++-v3, including valarray<>, complex<>, maintaining the numerics library @@ -172,12 +192,16 @@ maintaining complex<>, sanity checking and disbursement, configuration architecture, libio maintenance, and early math work. @item +Zdenek Dvorak for a new loop unroller and various fixes. + +@item Richard Earnshaw for his ongoing work with the ARM@. @item David Edelsohn for his direction via the steering committee, ongoing work -with the RS6000/PowerPC port, help cleaning up Haifa loop changes, and -for doing the entire AIX port of libstdc++ with his bare hands. +with the RS6000/PowerPC port, help cleaning up Haifa loop changes, +doing the entire AIX port of libstdc++ with his bare hands, and for +ensuring GCC properly keeps working on AIX. @item Kevin Ediger for the floating point formatting of num_put::do_put in @@ -186,7 +210,7 @@ libstdc++. @item Phil Edwards for libstdc++ work including configuration hackery, documentation maintainer, chief breaker of the web pages, the occasional -iostream bugfix, and work on shared library symbol versioning. +iostream bug fix, and work on shared library symbol versioning. @item Paul Eggert for random hacking all over GCC@. @@ -199,6 +223,9 @@ configuration support for locales and fstream-related fixes. Vadim Egorov for libstdc++ fixes in strings, streambufs, and iostreams. @item +Christian Ehrhardt for dealing with bug reports. + +@item Ben Elliston for his work to move the Objective-C runtime into its own subdirectory and for his work on autoconf. @@ -210,17 +237,22 @@ Doug Evans for much of the global optimization framework, arc, m32r, and SPARC work. @item +Christopher Faylor for his work on the Cygwin port and for caring and +feeding the gcc.gnu.org box and saving its users tons of spam. + +@item Fred Fish for BeOS support and Ada fixes. @item Ivan Fontes Garcia for the Portugese translation of the GCJ FAQ. @item -Peter Gerwinski for various bugfixes and the Pascal front end. +Peter Gerwinski for various bug fixes and the Pascal front end. @item -Kaveh Ghazi for his direction via the steering committee and -amazing work to make @samp{-W -Wall} useful. +Kaveh Ghazi for his direction via the steering committee, +amazing work to make @samp{-W -Wall} useful, and continuously testing +GCC on a plethora of platforms. @item John Gilmore for a donation to the FSF earmarked improving GNU Java. @@ -251,7 +283,7 @@ Intel 386 and 860 support. @item Bruno Haible for improvements in the runtime overhead for EH, new -warnings and assorted bugfixes. +warnings and assorted bug fixes. @item Andrew Haley for his amazing Java compiler and library efforts. @@ -268,18 +300,25 @@ fixes. Kate Hedstrom for staking the g77 folks with an initial testsuite. @item -Richard Henderson for his ongoing SPARC, alpha, and ia32 work, loop +Richard Henderson for his ongoing SPARC, alpha, ia32, and ia64 work, loop opts, and generally fixing lots of old problems we've ignored for years, flow rewrite and lots of further stuff, including reviewing tons of patches. @item +Aldy Hernandez for working on the PowerPC port, SIMD support, and +various fixes. + +@item Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed the support for the Sony NEWS machine. @item +Kazu Hirata for caring and feeding the Renesas H8/300 port and various fixes. + +@item Manfred Hollstein for his ongoing work to keep the m88k alive, lots -of testing an bugfixing, particularly of our configury code. +of testing and bug fixing, particularly of our configury code. @item Steve Holmgren for MachTen patches. @@ -288,7 +327,7 @@ Steve Holmgren for MachTen patches. Jan Hubicka for his x86 port improvements. @item -Christian Iseli for various bugfixes. +Christian Iseli for various bug fixes. @item Kamil Iskra for general m68k hacking. @@ -297,7 +336,7 @@ Kamil Iskra for general m68k hacking. Lee Iverson for random fixes and MIPS testing. @item -Andreas Jaeger for various fixes to the MIPS port +Andreas Jaeger for testing and benchmarking of GCC and various bug fixes. @item Jakub Jelinek for his SPARC work and sibling call optimizations as well @@ -305,11 +344,11 @@ as lots of bug fixes and test cases, and for improving the Java build system. @item -Janis Johnson for ia64 testing and fixes and for her quality improvement -sidetracks. +Janis Johnson for ia64 testing and fixes, her quality improvement +sidetracks, and web page maintenance. @item -J. Kean Johnston for OpenServer support. +Kean Johnston for SCO OpenServer support and various fixes. @item Tim Josling for the sample language treelang based originally on Richard @@ -325,7 +364,7 @@ Klaus Kaempf for his ongoing work to make alpha-vms a viable target. David Kashtan of SRI adapted GCC to VMS@. @item -Ryszard Kabatek for many, many libstdc++ bugfixes and optimizations of +Ryszard Kabatek for many, many libstdc++ bug fixes and optimizations of strings, especially member functions, and for auto_ptr fixes. @item @@ -363,7 +402,7 @@ Robin Kirkham for cpu32 support. Mark Klein for PA improvements. @item -Thomas Koenig for various bugfixes. +Thomas Koenig for various bug fixes. @item Bruce Korb for the new and improved fixincludes code. @@ -389,7 +428,8 @@ with analysis and improvements of x86 performance. Ted Lemon wrote parts of the RTL reader and printer. @item -Kriang Lerdsuwanakij for improvements to demangler and various c++ fixes. +Kriang Lerdsuwanakij for C++ improvements including template as template +parameter support, and many C++ fixes. @item Warren Levy for tremendous work on libgcj (Java Runtime Library) and @@ -406,7 +446,7 @@ patches. Robert Lipe for OpenServer support, new testsuites, testing, etc. @item -Weiwen Liu for testing and various bugfixes. +Weiwen Liu for testing and various bug fixes. @item Dave Love for his ongoing work with the Fortran front end and @@ -450,7 +490,7 @@ for Java test code. Bryce McKinlay for numerous GCJ and libgcj fixes and improvements. @item -Adam Megacz for his work on the Win32 port of GCJ. +Adam Megacz for his work on the Windows port of GCJ. @item Michael Meissner for LRS framework, ia32, m32r, v850, m88k, MIPS, @@ -469,7 +509,7 @@ developers. Gary Miller ported GCC to Charles River Data Systems machines. @item -Alfred Minarik for libstdc++ string and ios bugfixes, and turning the +Alfred Minarik for libstdc++ string and ios bug fixes, and turning the entire libstdc++ testsuite namespace-compatible. @item @@ -527,6 +567,9 @@ MT-safe string and shadow headers. Felix Natter for documentation on porting libstdc++. @item +Nathanael Nerode for cleaning up the configuration/build process. + +@item NeXT, Inc.@: donated the front end that supports the Objective-C language. @@ -538,6 +581,10 @@ engine setup, various documentation fixes and other small fixes. Geoff Noer for this work on getting cygwin native builds working. @item +Diego Novillo for his SPEC performance tracking web pages and assorted +fixes in the middle end and various back ends. + +@item David O'Brien for the FreeBSD/alpha, FreeBSD/AMD x86-64, FreeBSD/ARM, FreeBSD/PowerPC, and FreeBSD/SPARC64 ports and related infrastructure improvements. @@ -555,6 +602,9 @@ ABI support, improvements to dejagnu's MIPS support, Java configuration clean-ups and porting work, etc. @item +Hartmut Penner for work on the s390 port. + +@item Paul Petersen wrote the machine description for the Alliant FX/8. @item @@ -585,13 +635,17 @@ David Reese of Sun Microsystems contributed to the Solaris on PowerPC port. @item +Volker Reichelt for keeping up with the problem reports. + +@item Joern Rennecke for maintaining the sh port, loop, regmove & reload hacking. @item Loren J. Rittle for improvements to libstdc++-v3 including the FreeBSD port, threading fixes, thread-related configury changes, critical -threading documentation, and solutions to really tricky I/O problems. +threading documentation, and solutions to really tricky I/O problems, +as well as keeping GCC properly working on FreeBSD and continuous testing. @item Craig Rodrigues for processing tons of bug reports. @@ -616,6 +670,10 @@ Juha Sarlin for improvements to the H8 code generator. Greg Satz assisted in making GCC work on HP-UX for the 9000 series 300. @item +Roger Sayle for improvements to constant folding and GCC's RTL optimizers +as well as for fixing numerous bugs. + +@item Bradley Schatz for his work on the GCJ FAQ. @item @@ -667,6 +725,9 @@ Andrey Slepuhin for assorted AIX hacking. Christopher Smith did the port for Convex machines. @item +Danny Smith for his major efforts on the Mingw (and Cygwin) ports. + +@item Randy Smith finished the Sun FPA support. @item @@ -716,7 +777,7 @@ Holger Teutsch provided the support for the Clipper CPU. Gary Thomas for his ongoing work to make the PPC work for GNU/Linux. @item -Philipp Thomas for random bugfixes throughout the compiler +Philipp Thomas for random bug fixes throughout the compiler @item Jason Thorpe for thread support in libstdc++ on NetBSD. @@ -726,7 +787,7 @@ Kresten Krab Thorup wrote the run time support for the Objective-C language and the fantastic Java bytecode interpreter. @item -Michael Tiemann for random bugfixes, the first instruction scheduler, +Michael Tiemann for random bug fixes, the first instruction scheduler, initial C++ support, function integration, NS32k, SPARC and M88k machine description work, delay slot scheduling. @@ -767,7 +828,7 @@ Dean Wakerley for converting the install documentation from HTML to texinfo in time for GCC 3.0. @item -Krister Walfridsson for random bugfixes. +Krister Walfridsson for random bug fixes. @item Stephen M. Webb for time and effort on making libstdc++ shadow files @@ -780,7 +841,10 @@ related infrastructure improvements to help x86 code generation, value range propagation and other work, WE32k port. @item -Zack Weinberg for major work on cpplib and various other bugfixes. +Ulrich Weigand for work on the s390 port. + +@item +Zack Weinberg for major work on cpplib and various other bug fixes. @item Matt Welsh for help with Linux Threads support in GCJ. @@ -821,9 +885,9 @@ Gilles Zunino for help porting Java to Irix. @end itemize - -We'd also like to thank the folks who have contributed time and energy in -testing GCC: +In addition to the above, all of which also contributed time and energy in +testing GCC, we would like to thank the following for their contributions +to testing: @itemize @bullet @item @@ -860,12 +924,6 @@ Frank Braun Rodney Brown @item -Joe Buck - -@item -Craig Burley - -@item Sidney Cadot @item @@ -875,12 +933,6 @@ Bradford Castalia Ralph Doncaster @item -Ulrich Drepper - -@item -David Edelsohn - -@item Richard Emberson @item @@ -905,9 +957,6 @@ Charles-Antoine Gauthier Yung Shing Gene @item -Kaveh Ghazi - -@item David Gilbert @item @@ -932,21 +981,9 @@ Amancio Hasty Bryan W. Headley @item -Kate Hedstrom - -@item -Richard Henderson - -@item Kevin B. Hendricks @item -Manfred Hollstein - -@item -Kamil Iskra - -@item Joep Jansen @item @@ -962,30 +999,15 @@ Tobias Kuipers Anand Krishnaswamy @item -Jeff Law - -@item -Robert Lipe - -@item llewelly @item Damon Love @item -Dave Love - -@item -H.J. Lu - -@item Brad Lucier @item -Mumit Khan - -@item Matthias Klose @item @@ -995,12 +1017,6 @@ Martin Knoblauch Jesse Macnish @item -David Miller - -@item -Toon Moene - -@item Stefan Morrell @item @@ -1013,9 +1029,6 @@ Matthias Mueller Pekka Nikander @item -Alexandre Oliva - -@item Jon Olson @item @@ -1037,9 +1050,6 @@ Paul Reilly Tom Reilly @item -Loren J. Rittle - -@item Torsten Rueger @item @@ -1049,24 +1059,15 @@ Danny Sadinoff Marc Schifer @item -Peter Schmid - -@item David Schuler @item Vin Shelton @item -Franz Sirl - -@item Tim Souder @item -Mike Stump - -@item Adam Sulmicki @item @@ -1076,9 +1077,6 @@ George Talbot Gregory Warnes @item -Carlo Wood - -@item David E. Young @item diff --git a/contrib/gcc/doc/cpp.texi b/contrib/gcc/doc/cpp.texi index 39e6a28..a6d6fb0 100644 --- a/contrib/gcc/doc/cpp.texi +++ b/contrib/gcc/doc/cpp.texi @@ -6,10 +6,10 @@ @c @cropmarks @c @finalout -@macro copyrightnotice +@copying @c man begin COPYRIGHT Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998, 1999, 2000, 2001 +1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document @@ -23,9 +23,7 @@ section entitled ``GNU Free Documentation License''. man page gfdl(7). @c man end @end ignore -@end macro -@macro covertexts @c man begin COPYRIGHT This manual contains no Invariant Sections. The Front-Cover Texts are (a) (see below), and the Back-Cover Texts are (b) (see below). @@ -40,7 +38,7 @@ This manual contains no Invariant Sections. The Front-Cover Texts are software. Copies published by the Free Software Foundation raise funds for GNU development. @c man end -@end macro +@end copying @macro gcctabopt{body} @code{\body\} @@ -48,6 +46,7 @@ This manual contains no Invariant Sections. The Front-Cover Texts are @c Create a separate index for command line options. @defcodeindex op +@syncodeindex vr op @c Used in cppopts.texi and cppenv.texi. @set cppmanual @@ -69,12 +68,12 @@ This manual contains no Invariant Sections. The Front-Cover Texts are @c There is a fill at the bottom of the page, so we need a filll to @c override it. @vskip 0pt plus 1filll -@copyrightnotice{} -@covertexts{} +@insertcopying @end titlepage @contents @page +@ifnottex @node Top @top The C preprocessor implements the macro language used to transform C, @@ -96,8 +95,8 @@ useful on its own. * Invocation:: * Environment Variables:: * GNU Free Documentation License:: -* Option Index:: * Index of Directives:: +* Option Index:: * Concept Index:: @detailmenu @@ -129,6 +128,7 @@ Macros * Variadic Macros:: * Predefined Macros:: * Undefining and Redefining Macros:: +* Directives Within Macro Arguments:: * Macro Pitfalls:: Predefined Macros @@ -173,14 +173,11 @@ Obsolete Features * Assertions:: * Obsolete once-only headers:: -* Miscellaneous obsolete features:: @end detailmenu @end menu -@ifnottex -@copyrightnotice{} -@covertexts{} +@insertcopying @end ifnottex @node Overview @@ -203,7 +200,7 @@ will be removed, and the Makefile will not work. Having said that, you can often get away with using cpp on things which are not C@. Other Algol-ish programming languages are often safe -(Pascal, Ada, etc.) So is assembly, with caution. @option{-traditional} +(Pascal, Ada, etc.) So is assembly, with caution. @option{-traditional-cpp} mode preserves more white space, and is otherwise more permissive. Many of the problems can be avoided by writing C or C++ style comments instead of native language comments, and keeping macros simple. @@ -223,6 +220,16 @@ of a program which does not expect them. To get strict ISO Standard C, you should use the @option{-std=c89} or @option{-std=c99} options, depending on which version of the standard you want. To get all the mandatory diagnostics, you must also use @option{-pedantic}. @xref{Invocation}. + +This manual describes the behavior of the ISO preprocessor. To +minimize gratuitous differences, where the ISO preprocessor's +behavior does not conflict with traditional semantics, the +traditional preprocessor should behave the same way. The various +differences that do exist are detailed in the section @ref{Traditional +Mode}. + +For clarity, unless noted otherwise, references to @samp{CPP} in this +manual refer to GNU CPP. @c man end @menu @@ -237,7 +244,7 @@ diagnostics, you must also use @option{-pedantic}. @xref{Invocation}. The preprocessor performs a series of textual transformations on its input. These happen before all other processing. Conceptually, they happen in a rigid order, and the entire file is run through each -transformation before the next one begins. GNU CPP actually does them +transformation before the next one begins. CPP actually does them all at once, for performance reasons. These transformations correspond roughly to the first three ``phases of translation'' described in the C standard. @@ -248,7 +255,7 @@ standard. @cindex line endings The input file is read into memory and broken into lines. -GNU CPP expects its input to be a text file, that is, an unstructured +CPP expects its input to be a text file, that is, an unstructured stream of ASCII characters, with some characters indicating the end of a line of text. Extended ASCII character sets, such as ISO Latin-1 or Unicode encoded in UTF-8, are also acceptable. Character sets that are @@ -274,16 +281,17 @@ warning message. @item @cindex trigraphs -If trigraphs are enabled, they are replaced by their corresponding -single characters. +@anchor{trigraphs}If trigraphs are enabled, they are replaced by their +corresponding single characters. By default GCC ignores trigraphs, +but if you request a strictly conforming mode with the @option{-std} +option, or you specify the @option{-trigraphs} option, then it +converts them. These are nine three-character sequences, all starting with @samp{??}, that are defined by ISO C to stand for single characters. They permit obsolete systems that lack some of C's punctuation to use C@. For example, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character -constant for a newline. By default, GCC ignores trigraphs, but if you -request a strictly conforming mode with the @option{-std} option, then -it converts them. +constant for a newline. Trigraphs are not popular and many compilers implement them incorrectly. Portable code should not rely on trigraphs being either converted or @@ -401,26 +409,8 @@ extremely confusing and should not be used in code intended to be readable. There is no way to prevent a backslash at the end of a line from being -interpreted as a backslash-newline. - -@example -"foo\\ -bar" -@end example - -@noindent -is equivalent to @code{"foo\bar"}, not to @code{"foo\\bar"}. To avoid -having to worry about this, do not use the deprecated GNU extension -which permits multi-line strings. Instead, use string literal -concatenation: - -@example - "foo\\" - "bar" -@end example - -@noindent -Your program will be more portable this way, too. +interpreted as a backslash-newline. This cannot affect any correct +program, however. @node Tokenization @section Tokenization @@ -535,11 +525,10 @@ closing quote or angle bracket. The preprocessor looks for the header file in different places depending on which form you use. @xref{Include Operation}. -In standard C, no string literal may extend past the end of a line. GNU -CPP accepts multi-line string constants, but not multi-line character -constants or header file names. This extension is deprecated and will -be removed in GCC 3.1. You may use continued lines instead, or string -constant concatenation. @xref{Differences from previous versions}. +No string literal may extend past the end of a line. Older versions +of GCC accepted multi-line string constants. You may use continued +lines instead, or string constant concatenation. @xref{Differences +from previous versions}. @cindex punctuators @cindex digraphs @@ -795,10 +784,10 @@ those are merely the typical uses. Any fragment of a C program can be included from another file. The include file could even contain the beginning of a statement that is concluded in the containing file, or the end of a statement that was started in the including file. However, -a comment or a string or character constant may not start in the -included file and finish in the including file. An unterminated -comment, string constant or character constant in an included file is -considered to end (with an error message) at the end of the file. +an included file must consist of complete tokens. Comments and string +literals which have not been closed by the end of an included file are +invalid. For error recovery, they are considered to end at the end of +the file. To avoid confusion, it is best if header files contain only complete syntactic units---function declarations or definitions, type @@ -909,7 +898,7 @@ because @code{FILE_FOO_SEEN} is defined. The preprocessor will skip over the entire contents of the file, and the compiler will not see it twice. -GNU CPP optimizes even further. It remembers when a header file has a +CPP optimizes even further. It remembers when a header file has a wrapper @samp{#ifndef}. If a subsequent @samp{#include} specifies that header, and the macro in the @samp{#ifndef} is still defined, it does not bother to rescan the file at all. @@ -1128,6 +1117,7 @@ macros when you are compiling C++. * Variadic Macros:: * Predefined Macros:: * Undefining and Redefining Macros:: +* Directives Within Macro Arguments:: * Macro Pitfalls:: @end menu @@ -1621,7 +1611,7 @@ or to paste its leading or trailing token with another token. (But see below for an important special case for @samp{##}.) If your macro is complicated, you may want a more descriptive name for -the variable argument than @code{@w{__VA_ARGS__}}. GNU CPP permits +the variable argument than @code{@w{__VA_ARGS__}}. CPP permits this, as an extension. You may write an argument name immediately before the @samp{@dots{}}; that name is used for the variable argument. The @code{eprintf} macro above could be written @@ -1631,7 +1621,7 @@ The @code{eprintf} macro above could be written @end example @noindent -using this extension. You cannot use @code{__VA_ARGS__} and this +using this extension. You cannot use @code{@w{__VA_ARGS__}} and this extension in the same macro. You can have named arguments as well as variable arguments in a variadic @@ -1705,7 +1695,7 @@ only named variable arguments. On the other hand, if you are concerned with portability to other conforming implementations of C99, you should use only @code{@w{__VA_ARGS__}}. -Previous versions of GNU CPP implemented the comma-deletion extension +Previous versions of CPP implemented the comma-deletion extension much more generally. We have restricted it in this release to minimize the differences from C99. To get the same effect with both this and previous versions of GCC, the token preceding the special @samp{##} must @@ -1800,23 +1790,31 @@ the preprocessor is being run. The string constant contains eleven characters and looks like @code{@w{"Feb 12 1996"}}. If the day of the month is less than 10, it is padded with a space on the left. +If GCC cannot determine the current date, it will emit a warning message +(once per compilation) and @code{__DATE__} will expand to +@code{@w{"??? ?? ????"}}. + @item __TIME__ This macro expands to a string constant that describes the time at which the preprocessor is being run. The string constant contains eight characters and looks like @code{"23:59:01"}. +If GCC cannot determine the current time, it will emit a warning message +(once per compilation) and @code{__TIME__} will expand to +@code{"??:??:??"}. + @item __STDC__ In normal operation, this macro expands to the constant 1, to signify that this compiler conforms to ISO Standard C@. If GNU CPP is used with a compiler other than GCC, this is not necessarily true; however, the -preprocessor always conforms to the standard, unless the -@option{-traditional} option is used. +preprocessor always conforms to the standard unless the +@option{-traditional-cpp} option is used. -This macro is not defined if the @option{-traditional} option is used. +This macro is not defined if the @option{-traditional-cpp} option is used. On some hosts, the system compiler uses a different convention, where @code{__STDC__} is normally 0, but is 1 if the user specifies strict -conformance to the C Standard. GNU CPP follows the host convention when +conformance to the C Standard. CPP follows the host convention when processing system header files, but when processing user files @code{__STDC__} is always 1. This has been reported to cause problems; for instance, some versions of Solaris provide X Windows headers that @@ -1835,8 +1833,8 @@ The value @code{199409L} signifies the 1989 C standard as amended in the 1999 revision of the C standard. Support for the 1999 revision is not yet complete. -This macro is not defined if the @option{-traditional} option is used, nor -when compiling C++ or Objective-C@. +This macro is not defined if the @option{-traditional-cpp} option is +used, nor when compiling C++ or Objective-C@. @item __STDC_HOSTED__ This macro is defined, with value 1, if the compiler's target is a @@ -1970,6 +1968,10 @@ unsigned on the target machine. It exists to cause the standard header file @file{limits.h} to work correctly. You should not use this macro yourself; instead, refer to the standard macros defined in @file{limits.h}. +@item __WCHAR_UNSIGNED__ +Like @code{__CHAR_UNSIGNED__}, this macro is defined if and only if the +data type @code{wchar_t} is unsigned and the front-end is in C++ mode. + @item __REGISTER_PREFIX__ This macro expands to a single token (not a string constant) which is the prefix applied to CPU register names in assembly language for this @@ -2000,10 +2002,35 @@ typedefs, respectively. They exist to make the standard header files these macros directly; instead, include the appropriate headers and use the typedefs. +@item __CHAR_BIT__ +Defined to the number of bits used in the representation of the +@code{char} data type. It exists to make the standard header given +numerical limits work correctly. You should not use +this macro directly; instead, include the appropriate headers. + +@item __SCHAR_MAX__ +@itemx __WCHAR_MAX__ +@itemx __SHRT_MAX__ +@itemx __INT_MAX__ +@itemx __LONG_MAX__ +@itemx __LONG_LONG_MAX__ +Defined to the maximum value of the @code{signed char}, @code{wchar_t}, +@code{signed short}, +@code{signed int}, @code{signed long}, and @code{signed long long} types +respectively. They exist to make the standard header given numerical limits +work correctly. You should not use these macros directly; instead, include +the appropriate headers. + @item __USING_SJLJ_EXCEPTIONS__ This macro is defined, with value 1, if the compiler uses the old mechanism based on @code{setjmp} and @code{longjmp} for exception handling. + +@item __NEXT_RUNTIME__ +This macro is defined, with value 1, if (and only if) the NeXT runtime +(as in @option{-fnext-runtime}) is in use for Objective-C. If the GNU +runtime is used, this macro is not defined, so that you can use this +macro to determine which runtime (NeXT or GNU) is being used. @end table @node System-specific Predefined Macros @@ -2136,6 +2163,50 @@ the same, the redefinition is silently ignored. This allows, for instance, two different headers to define a common macro. The preprocessor will only complain if the definitions do not match. +@node Directives Within Macro Arguments +@section Directives Within Macro Arguments +@cindex macro arguments and directives + +Occasionally it is convenient to use preprocessor directives within +the arguments of a macro. The C and C++ standards declare that +behavior in these cases is undefined. + +Versions of CPP prior to 3.2 would reject such constructs with an +error message. This was the only syntactic difference between normal +functions and function-like macros, so it seemed attractive to remove +this limitation, and people would often be surprised that they could +not use macros in this way. Moreover, sometimes people would use +conditional compilation in the argument list to a normal library +function like @samp{printf}, only to find that after a library upgrade +@samp{printf} had changed to be a function-like macro, and their code +would no longer compile. So from version 3.2 we changed CPP to +successfully process arbitrary directives within macro arguments in +exactly the same way as it would have processed the directive were the +function-like macro invocation not present. + +If, within a macro invocation, that macro is redefined, then the new +definition takes effect in time for argument pre-expansion, but the +original definition is still used for argument replacement. Here is a +pathological example: + +@smallexample +#define f(x) x x +f (1 +#undef f +#define f 2 +f) +@end smallexample + +@noindent +which expands to + +@smallexample +1 2 1 2 +@end smallexample + +@noindent +with the semantics described above. + @node Macro Pitfalls @section Macro Pitfalls @cindex problems with macros @@ -2723,7 +2794,7 @@ good practice if there is a lot of @var{controlled text}, because it helps people match the @samp{#endif} to the corresponding @samp{#ifdef}. Older programs sometimes put @var{MACRO} directly after the @samp{#endif} without enclosing it in a comment. This is invalid code -according to the C standard. GNU CPP accepts it with a warning. It +according to the C standard. CPP accepts it with a warning. It never affects which @samp{#ifndef} the @samp{#endif} matches. @findex #ifndef @@ -3059,7 +3130,7 @@ file it specifies, until something else happens to change that. constant: backslash escapes are interpreted. This is different from @samp{#include}. -Previous versions of GNU CPP did not interpret escapes in @samp{#line}; +Previous versions of CPP did not interpret escapes in @samp{#line}; we have changed it because the standard requires they be interpreted, and most other compilers do. @@ -3226,8 +3297,8 @@ This directive is not part of the C standard, but it is not an official GNU extension either. We believe it came from System V@. @findex #sccs -The @samp{#sccs} directive is recognized on some systems, because it -appears in their header files. It is a very old, obscure, extension +The @samp{#sccs} directive is recognized, because it appears in the +header files of some systems. It is a very old, obscure, extension which we did not invent, and we have been unable to find any documentation of what it should do, so GCC simply ignores it. @@ -3321,91 +3392,230 @@ the directive name. Traditional (pre-standard) C preprocessing is rather different from the preprocessing specified by the standard. When GCC is given the -@option{-traditional} option, it attempts to emulate a traditional -preprocessor. We do not guarantee that GCC's behavior under -@option{-traditional} matches any pre-standard preprocessor exactly. +@option{-traditional-cpp} option, it attempts to emulate a traditional +preprocessor. -Traditional mode exists only for backward compatibility. We have no -plans to augment it in any way nor will we change it except to fix -catastrophic bugs. You should be aware that modern C libraries often -have header files which are incompatible with traditional mode. +GCC versions 3.2 and later only support traditional mode semantics in +the preprocessor, and not in the compiler front ends. This chapter +outlines the traditional preprocessor semantics we implemented. -This is a list of the differences. It may not be complete, and may not -correspond exactly to the behavior of either GCC or a true traditional -preprocessor. +The implementation does not correspond precisely to the behavior of +earlier versions of GCC, nor to any true traditional preprocessor. +After all, inconsistencies among traditional implementations were a +major motivation for C standardization. However, we intend that it +should be compatible with true traditional preprocessors in all ways +that actually matter. -@itemize @bullet -@item -Traditional macro expansion pays no attention to single-quote or -double-quote characters; macro argument symbols are replaced by the -argument values even when they appear within apparent string or -character constants. +@menu +* Traditional lexical analysis:: +* Traditional macros:: +* Traditional miscellany:: +* Traditional warnings:: +@end menu -@item -Traditionally, it is permissible for a macro expansion to end in the -middle of a string or character constant. The constant continues into -the text surrounding the macro call. +@node Traditional lexical analysis +@section Traditional lexical analysis -@item -However, the end of the line terminates a string or character constant, -with no error. (This is a kluge. Traditional mode is commonly used to -preprocess things which are not C, and have a different comment syntax. -Single apostrophes often appear in comments. This kluge prevents the -traditional preprocessor from issuing errors on such comments.) +The traditional preprocessor does not decompose its input into tokens +the same way a standards-conforming preprocessor does. The input is +simply treated as a stream of text with minimal internal form. -@item -Preprocessing directives are recognized in traditional C only when their -leading @samp{#} appears in the first column. There can be no -whitespace between the beginning of the line and the @samp{#}. +This implementation does not treat trigraphs (@pxref{trigraphs}) +specially since they were an invention of the standards committee. It +handles arbitrarily-positioned escaped newlines properly and splices +the lines as you would expect; many traditional preprocessors did not +do this. -@item -In traditional C, a comment is equivalent to no text at all. (In ISO -C, a comment counts as whitespace.) It can be used sort of the same way -that @samp{##} is used in ISO C, to paste macro arguments together. +The form of horizontal whitespace in the input file is preserved in +the output. In particular, hard tabs remain hard tabs. This can be +useful if, for example, you are preprocessing a Makefile. -@item -Traditional C does not have the concept of a preprocessing number. +Traditional CPP only recognizes C-style block comments, and treats the +@samp{/*} sequence as introducing a comment only if it lies outside +quoted text. Quoted text is introduced by the usual single and double +quotes, and also by an initial @samp{<} in a @code{#include} +directive. -@item -A macro is not suppressed within its own definition, in traditional C@. -Thus, any macro that is used recursively inevitably causes an error. +Traditionally, comments are completely removed and are not replaced +with a space. Since a traditional compiler does its own tokenization +of the output of the preprocessor, this means that comments can +effectively be used as token paste operators. However, comments +behave like separators for text handled by the preprocessor itself, +since it doesn't re-lex its input. For example, in -@item -The @samp{#} and @samp{##} operators are not available in traditional -C@. +@smallexample +#if foo/**/bar +@end smallexample + +@noindent +@samp{foo} and @samp{bar} are distinct identifiers and expanded +separately if they happen to be macros. In other words, this +directive is equivalent to + +@smallexample +#if foo bar +@end smallexample + +@noindent +rather than + +@smallexample +#if foobar +@end smallexample + +Generally speaking, in traditional mode an opening quote need not have +a matching closing quote. In particular, a macro may be defined with +replacement text that contains an unmatched quote. Of course, if you +attempt to compile preprocessed output containing an unmatched quote +you will get a syntax error. +However, all preprocessing directives other than @code{#define} +require matching quotes. For example: + +@smallexample +#define m This macro's fine and has an unmatched quote +"/* This is not a comment. */ +/* This is a comment. The following #include directive + is ill-formed. */ +#include <stdio.h +@end smallexample + +Just as for the ISO preprocessor, what would be a closing quote can be +escaped with a backslash to prevent the quoted text from closing. + +@node Traditional macros +@section Traditional macros + +The major difference between traditional and ISO macros is that the +former expand to text rather than to a token sequence. CPP removes +all leading and trailing horizontal whitespace from a macro's +replacement text before storing it, but preserves the form of internal +whitespace. + +One consequence is that it is legitimate for the replacement text to +contain an unmatched quote (@pxref{Traditional lexical analysis}). An +unclosed string or character constant continues into the text +following the macro call. Similarly, the text at the end of a macro's +expansion can run together with the text after the macro invocation to +produce a single token. + +Normally comments are removed from the replacement text after the +macro is expanded, but if the @option{-CC} option is passed on the +command line comments are preserved. (In fact, the current +implementation removes comments even before saving the macro +replacement text, but it careful to do it in such a way that the +observed effect is identical even in the function-like macro case.) + +The ISO stringification operator @samp{#} and token paste operator +@samp{##} have no special meaning. As explained later, an effect +similar to these operators can be obtained in a different way. Macro +names that are embedded in quotes, either from the main file or after +macro replacement, do not expand. + +CPP replaces an unquoted object-like macro name with its replacement +text, and then rescans it for further macros to replace. Unlike +standard macro expansion, traditional macro expansion has no provision +to prevent recursion. If an object-like macro appears unquoted in its +replacement text, it will be replaced again during the rescan pass, +and so on @emph{ad infinitum}. GCC detects when it is expanding +recursive macros, emits an error message, and continues after the +offending macro invocation. + +@smallexample +#define PLUS + +#define INC(x) PLUS+x +INC(foo); + @expansion{} ++foo; +@end smallexample + +Function-like macros are similar in form but quite different in +behavior to their ISO counterparts. Their arguments are contained +within parentheses, are comma-separated, and can cross physical lines. +Commas within nested parentheses are not treated as argument +separators. Similarly, a quote in an argument cannot be left +unclosed; a following comma or parenthesis that comes before the +closing quote is treated like any other character. There is no +facility for handling variadic macros. + +This implementation removes all comments from macro arguments, unless +the @option{-C} option is given. The form of all other horizontal +whitespace in arguments is preserved, including leading and trailing +whitespace. In particular + +@smallexample +f( ) +@end smallexample + +@noindent +is treated as an invocation of the macro @samp{f} with a single +argument consisting of a single space. If you want to invoke a +function-like macro that takes no arguments, you must not leave any +whitespace between the parentheses. + +If a macro argument crosses a new line, the new line is replaced with +a space when forming the argument. If the previous line contained an +unterminated quote, the following line inherits the quoted state. + +Traditional preprocessors replace parameters in the replacement text +with their arguments regardless of whether the parameters are within +quotes or not. This provides a way to stringize arguments. For +example + +@smallexample +#define str(x) "x" +str(/* A comment */some text ) + @expansion{} "some text " +@end smallexample + +@noindent +Note that the comment is removed, but that the trailing space is +preserved. Here is an example of using a comment to effect token +pasting. + +@smallexample +#define suffix(x) foo_/**/x +suffix(bar) + @expansion{} foo_bar +@end smallexample + +@node Traditional miscellany +@section Traditional miscellany + +Here are some things to be aware of when using the traditional +preprocessor. + +@itemize @bullet @item -In traditional C, the text at the end of a macro expansion can run -together with the text after the macro call, to produce a single token. -This is impossible in ISO C@. +Preprocessing directives are recognized only when their leading +@samp{#} appears in the first column. There can be no whitespace +between the beginning of the line and the @samp{#}, but whitespace can +follow the @samp{#}. @item -None of the GNU extensions to the preprocessor are available in -traditional mode, with the exception of a partial implementation of -assertions, and those may be removed in the future. +A true traditional C preprocessor does not recognize @samp{#error} or +@samp{#pragma}, and may not recognize @samp{#elif}. CPP supports all +the directives in traditional mode that it supports in ISO mode, +including extensions, with the exception that the effects of +@samp{#pragma GCC poison} are undefined. @item -A true traditional C preprocessor does not recognize @samp{#elif}, -@samp{#error}, or @samp{#pragma}. GCC supports @samp{#elif} and -@samp{#error} even in traditional mode, but not @samp{#pragma}. +__STDC__ is not defined. @item -Traditional mode is text-based, not token-based, and comments are -stripped after macro expansion. Therefore, @samp{/**/} can be used to -paste tokens together provided that there is no whitespace between it -and the tokens to be pasted. +If you use digraphs the behavior is undefined. @item -Traditional mode preserves the amount and form of whitespace provided by -the user. Hard tabs remain hard tabs. This can be useful, e.g.@: if you -are preprocessing a Makefile (which we do not encourage). +If a line that looks like a directive appears within macro arguments, +the behavior is undefined. + @end itemize +@node Traditional warnings +@section Traditional warnings You can request warnings about features that did not exist, or worked differently, in traditional C with the @option{-Wtraditional} option. -This works only if you do @emph{not} specify @option{-traditional}. GCC -does not warn about features of ISO C which you must use when you are -using a conforming compiler, such as the @samp{#} and @samp{##} +GCC does not warn about features of ISO C which you must use when you +are using a conforming compiler, such as the @samp{#} and @samp{##} operators. Presently @option{-Wtraditional} warns about: @@ -3428,9 +3638,9 @@ traditional implementations would not recognize @samp{#elif}, so it suggests avoiding it altogether. @item -A function-like macro that appears without an argument list. In -traditional C this was an error. In ISO C it merely means that the -macro is not expanded. +A function-like macro that appears without an argument list. In some +traditional preprocessors this was an error. In ISO C it merely means +that the macro is not expanded. @item The unary plus operator. This did not exist in traditional C@. @@ -3458,7 +3668,7 @@ reliance on behavior described here, as it is possible that it will change subtly in future implementations. Also documented here are obsolete features and changes from previous -versions of GNU CPP@. +versions of CPP@. @menu * Implementation-defined behavior:: @@ -3471,7 +3681,7 @@ versions of GNU CPP@. @section Implementation-defined behavior @cindex implementation-defined behavior -This is how GNU CPP behaves in all the cases which the C standard +This is how CPP behaves in all the cases which the C standard describes as @dfn{implementation-defined}. This term means that the implementation is free to do what it likes, but must document its choice and stick to it. @@ -3494,17 +3704,25 @@ same column as it did in the original source file. @item The numeric value of character constants in preprocessor expressions. -The preprocessor and compiler interpret character constants in the same -way; escape sequences such as @samp{\a} are given the values they would -have on the target machine. - -Multi-character character constants are interpreted a character at a -time, shifting the previous result left by the number of bits per -character on the host, and adding the new character. For example, 'ab' -on an 8-bit host would be interpreted as @w{'a' * 256 + 'b'}. If there -are more characters in the constant than can fit in the widest native -integer type on the host, usually a @code{long}, the excess characters -are ignored and a diagnostic is given. +The preprocessor and compiler interpret character constants in the +same way; i.e.@: escape sequences such as @samp{\a} are given the +values they would have on the target machine. + +The compiler values a multi-character character constant a character +at a time, shifting the previous value left by the number of bits per +target character, and then or-ing in the bit-pattern of the new +character truncated to the width of a target character. The final +bit-pattern is given type @code{int}, and is therefore signed, +regardless of whether single characters are signed or not (a slight +change from versions 3.1 and earlier of GCC). If there are more +characters in the constant than would fit in the target @code{int} the +compiler issues a warning, and the excess leading characters are +ignored. + +For example, 'ab' for a target with an 8-bit @code{char} would be +interpreted as @w{(int) ((unsigned char) 'a' * 256 + (unsigned char) +'b')}, and '\234a' as @w{(int) ((unsigned char) '\234' * 256 + (unsigned +char) 'a')}. @item Source file inclusion. @@ -3531,7 +3749,7 @@ pragmas. @section Implementation limits @cindex implementation limits -GNU CPP has a small number of internal limits. This section lists the +CPP has a small number of internal limits. This section lists the limits which the C standard requires to be no lower than some minimum, and all the others we are aware of. We intend there to be as few limits as possible. If you encounter an undocumented or inconvenient limit, @@ -3554,10 +3772,10 @@ The standard requires at least 15 levels. @item Nesting levels of conditional inclusion. -The C standard mandates this be at least 63. GNU CPP is limited only by +The C standard mandates this be at least 63. CPP is limited only by available memory. -@item Levels of parenthesised expressions within a full expression. +@item Levels of parenthesized expressions within a full expression. The C standard requires this to be at least 63. In preprocessor conditional expressions, it is limited only by available memory. @@ -3569,7 +3787,7 @@ requires only that the first 63 be significant. @item Number of macros simultaneously defined in a single translation unit. -The standard requires at least 4095 be possible. GNU CPP is limited only +The standard requires at least 4095 be possible. CPP is limited only by available memory. @item Number of parameters in a macro definition and arguments in a macro call. @@ -3579,7 +3797,7 @@ required by the standard is 127. @item Number of characters on a logical source line. -The C standard requires a minimum of 4096 be permitted. GNU CPP places +The C standard requires a minimum of 4096 be permitted. CPP places no limits on this, but you may get incorrect column numbers reported in diagnostics for lines longer than 65,535 characters. @@ -3596,14 +3814,13 @@ may not be a limitation. @node Obsolete Features @section Obsolete Features -GNU CPP has a number of features which are present mainly for +CPP has a number of features which are present mainly for compatibility with older programs. We discourage their use in new code. In some cases, we plan to remove the feature in a future version of GCC@. @menu * Assertions:: * Obsolete once-only headers:: -* Miscellaneous obsolete features:: @end menu @node Assertions @@ -3671,9 +3888,9 @@ answers. Subsequent assertions do not override previous ones for the same predicate. All the answers for any given predicate are simultaneously true. -@cindex assertions, cancelling +@cindex assertions, canceling @findex #unassert -Assertions can be cancelled with the @samp{#unassert} directive. It +Assertions can be canceled with the @samp{#unassert} directive. It has the same syntax as @samp{#assert}. In that form it cancels only the answer which was specified on the @samp{#unassert} line; other answers for that predicate remain true. You can cancel an entire predicate by @@ -3693,7 +3910,7 @@ You can also make or cancel assertions using command line options. @node Obsolete once-only headers @subsection Obsolete once-only headers -GNU CPP supports two more ways of indicating that a header file should be +CPP supports two more ways of indicating that a header file should be read only once. Neither one is as portable as a wrapper @samp{#ifndef}, and we recommend you do not use them in new programs. @@ -3726,49 +3943,12 @@ matter what. but it is not recognized by all preprocessors, so you cannot rely on it in a portable program. -@node Miscellaneous obsolete features -@subsection Miscellaneous obsolete features - -Here are a few more obsolete features. - -@itemize @bullet -@cindex invalid token paste -@item Attempting to paste two tokens which together do not form a valid -preprocessing token. - -The preprocessor currently warns about this, and the resulting -preprocessed output is undefined. The tokens remain distinct if the -preprocessor is being used directly by the compiler front end. - -Most of the time, when you get this warning, you will find that @samp{##} -is being used superstitiously, to guard against whitespace appearing -between two tokens. It is almost always safe to delete the @samp{##}. - -@cindex pragma poison -@item @code{#pragma poison} - -This is the same as @code{#pragma GCC poison}. The version without the -@code{GCC} prefix is deprecated. @xref{Pragmas}. - -@cindex multi-line string constants -@item Multi-line string constants - -GCC currently allows a string constant to extend across multiple logical -lines of the source file. This extension is deprecated and will be -removed in a future version of GCC@. Such string constants are already -rejected in all directives apart from @samp{#define}. - -Instead, make use of ISO C concatenation of adjacent string literals, or -use @samp{\n} followed by a backslash-newline. - -@end itemize - @node Differences from previous versions @section Differences from previous versions @cindex differences from previous versions This section details behavior which has changed from previous versions -of GNU CPP@. We do not plan to change it again in the near future, but +of CPP@. We do not plan to change it again in the near future, but we do not promise not to, either. The ``previous versions'' discussed here are 2.95 and before. The @@ -3794,7 +3974,7 @@ GCC 3.0 evaluates @samp{#} and @samp{##} at the same time and strictly left to right. Older versions evaluated all @samp{#} operators first, then all @samp{##} operators, in an unreliable order. -@item The form of whitespace betwen tokens in preprocessor output +@item The form of whitespace between tokens in preprocessor output @xref{Preprocessor Output}, for the current textual format. This is also the format used by stringification. Normally, the preprocessor @@ -3817,7 +3997,7 @@ versions accepted it silently. Formerly, in a macro expansion, if @samp{##} appeared before a variable arguments parameter, and the set of tokens specified for that argument -in the macro invocation was empty, previous versions of GNU CPP would +in the macro invocation was empty, previous versions of CPP would back up and remove the preceding sequence of non-whitespace characters (@strong{not} the preceding token). This extension is in direct conflict with the 1999 C standard and has been drastically pared back. @@ -3828,15 +4008,6 @@ omitted entirely, the comma will be removed from the expansion. If the variable argument is empty, or the token before @samp{##} is not a comma, then @samp{##} behaves as a normal token paste. -@item Traditional mode and GNU extensions - -Traditional mode used to be implemented in the same program as normal -preprocessing. Therefore, all the GNU extensions to the preprocessor -were still available in traditional mode. It is now a separate program -and does not implement any of the GNU extensions, except for a partial -implementation of assertions. Even those may be removed in a future -release. - @item @samp{#line} and @samp{#include} The @samp{#line} directive used to change GCC's notion of the @@ -3934,25 +4105,26 @@ Note that you can also specify places to search using options such as @option{-M} (@pxref{Invocation}). These take precedence over environment variables, which in turn take precedence over the configuration of GCC@. - + @include cppenv.texi @c man end +@page @include fdl.texi @page -@node Option Index -@unnumbered Option Index - -CPP's command line options are indexed here without any initial -@samp{-} or @samp{--}. - -@printindex op - @node Index of Directives @unnumbered Index of Directives @printindex fn +@node Option Index +@unnumbered Option Index +@noindent +CPP's command line options and environment variables are indexed here +without any initial @samp{-} or @samp{--}. +@printindex op + +@page @node Concept Index @unnumbered Concept Index @printindex cp diff --git a/contrib/gcc/doc/cppenv.texi b/contrib/gcc/doc/cppenv.texi index d60f7ee..7a913f1 100644 --- a/contrib/gcc/doc/cppenv.texi +++ b/contrib/gcc/doc/cppenv.texi @@ -10,7 +10,7 @@ @c If this file is included with the flag ``cppmanual'' set, it is @c formatted for inclusion in the CPP manual; otherwise the main GCC manual. -@ftable @env +@vtable @env @item CPATH @itemx C_INCLUDE_PATH @itemx CPLUS_INCLUDE_PATH @@ -25,7 +25,7 @@ semicolon, and for almost all other targets it is a colon. @env{CPATH} specifies a list of directories to be searched as if specified with @option{-I}, but after any paths given with @option{-I} -options on the command line. The environment variable is used +options on the command line. This environment variable is used regardless of which language is being preprocessed. The remaining environment variables apply only when preprocessing the @@ -33,12 +33,19 @@ particular language indicated. Each specifies a list of directories to be searched as if specified with @option{-isystem}, but after any paths given with @option{-isystem} options on the command line. +In all these variables, an empty element instructs the compiler to +search its current working directory. Empty elements can appear at the +beginning or end of a path. For instance, if the value of +@env{CPATH} is @code{:/special/include}, that has the same +effect as @samp{@w{-I. -I/special/include}}. + +@c man end @ifset cppmanual See also @ref{Search Path}. @end ifset +@c man begin ENVIRONMENT @item DEPENDENCIES_OUTPUT -@anchor{DEPENDENCIES_OUTPUT} @cindex dependencies for make as output If this variable is set, its value specifies how to output dependencies for Make based on the non-system header files processed @@ -63,15 +70,14 @@ with an optional @option{-MT} switch too. @item SUNPRO_DEPENDENCIES @cindex dependencies for make as output -This variable is the same as the environment variable -@env{DEPENDENCIES_OUTPUT} (@pxref{DEPENDENCIES_OUTPUT}), except that -system header files are not ignored, so it implies @option{-M} rather -than @option{-MM}. However, the dependence on the main input file is -omitted. +This variable is the same as @env{DEPENDENCIES_OUTPUT} (see above), +except that system header files are not ignored, so it implies +@option{-M} rather than @option{-MM}. However, the dependence on the +main input file is omitted. @ifset cppmanual @xref{Invocation}. @end ifset @ifclear cppmanual @xref{Preprocessor Options}. @end ifclear -@end ftable +@end vtable diff --git a/contrib/gcc/doc/cppopts.texi b/contrib/gcc/doc/cppopts.texi index 308e989..7abb803 100644 --- a/contrib/gcc/doc/cppopts.texi +++ b/contrib/gcc/doc/cppopts.texi @@ -51,16 +51,14 @@ for header files. @xref{Search Path}. @end ifset Directories named by @option{-I} are searched before the standard -system include directories. - -It is dangerous to specify a standard system include directory in an -@option{-I} option. This defeats the special treatment of system -headers +system include directories. If the directory @var{dir} is a standard +system include directory, the option is ignored to ensure that the +default search order for system directories and the special treatment +of system headers are not defeated @ifset cppmanual (@pxref{System Headers}) @end ifset -. It can also defeat the repairs to buggy system headers which GCC -makes when it is installed. +. @item -o @var{file} @opindex o @@ -110,6 +108,44 @@ Warn whenever an identifier which is not a macro is encountered in an @samp{#if} directive, outside of @samp{defined}. Such identifiers are replaced with zero. +@item -Wunused-macros +@opindex Wunused-macros +Warn about macros defined in the main file that are unused. A macro +is @dfn{used} if it is expanded or tested for existence at least once. +The preprocessor will also warn if the macro has not been used at the +time it is redefined or undefined. + +Built-in macros, macros defined on the command line, and macros +defined in include files are not warned about. + +@strong{Note:} If a macro is actually used, but only used in skipped +conditional blocks, then CPP will report it as unused. To avoid the +warning in such a case, you might improve the scope of the macro's +definition by, for example, moving it into the first skipped block. +Alternatively, you could provide a dummy use with something like: + +@smallexample +#if defined the_macro_causing_the_warning +#endif +@end smallexample + +@item -Wendif-labels +@opindex Wendif-labels +Warn whenever an @samp{#else} or an @samp{#endif} are followed by text. +This usually happens in code of the form + +@smallexample +#if FOO +@dots{} +#else FOO +@dots{} +#endif FOO +@end smallexample + +@noindent +The second and third @code{FOO} should be in comments, but often are not +in older programs. This warning is on by default. + @item -Werror @opindex Werror Make all warnings into hard errors. Source code which triggers warnings @@ -158,10 +194,11 @@ This option does not suppress the preprocessor's debug output, such as @option{-dM}. To avoid mixing such debug output with the dependency rules you should explicitly specify the dependency output file with @option{-MF}, or use an environment variable like -@env{DEPENDENCIES_OUTPUT} (@pxref{DEPENDENCIES_OUTPUT}). Debug output +@env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}). Debug output will still be sent to the regular output stream as normal. -Passing @option{-M} to the driver implies @option{-E}. +Passing @option{-M} to the driver implies @option{-E}, and suppresses +warnings with an implicit @option{-w}. @item -MM @opindex MM @@ -187,10 +224,13 @@ When used with the driver options @option{-MD} or @option{-MMD}, @item -MG @opindex MG -When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing -header files as generated files and assume they live in the same -directory as the source file. It suppresses preprocessed output, as a -missing header file is ordinarily an error. +In conjunction with an option such as @option{-M} requesting +dependency generation, @option{-MG} assumes missing header files are +generated files and adds them to the dependency list without raising +an error. The dependency filename is taken directly from the +@code{#include} directive without prepending any path. @option{-MG} +also suppresses preprocessed output, as a missing header file renders +this useless. This feature is used in automatic updating of makefiles. @@ -284,9 +324,8 @@ option. @itemx -ansi @opindex ansi @opindex std= -Specify the standard to which the code should conform. Currently cpp -only knows about the standards for C; other language standards will be -added in the future. +Specify the standard to which the code should conform. Currently CPP +knows about C and C++ standards; others may be added in the future. @var{standard} may be one of: @@ -314,6 +353,13 @@ The 1990 C standard plus GNU extensions. This is the default. @item gnu99 @itemx gnu9x The 1999 C standard plus GNU extensions. + +@item c++98 +The 1998 ISO C++ standard plus amendments. + +@item gnu++98 +The same as @option{-std=c++98} plus GNU extensions. This is the +default for C++ code. @end table @item -I- @@ -441,13 +487,6 @@ it does not use shell special characters. Cancel an assertion with the predicate @var{predicate} and answer @var{answer}. -@item -A- -@opindex A- -Cancel all predefined assertions and all assertions preceding it on -the command line. Also, undefine all predefined macros and all -macros preceding it on the command line. (This is a historical wart and -may change in the future.) - @item -dCHARS @var{CHARS} is a sequence of one or more of the following characters, and must not be preceded by a space. Other characters are interpreted @@ -510,6 +549,19 @@ For example, comments appearing at the start of what would be a directive line have the effect of turning that line into an ordinary source line, since the first token on the line is no longer a @samp{#}. +@item -CC +Do not discard comments, including during macro expansion. This is +like @option{-C}, except that comments contained within macros are +also passed through to the output file where the macro is expanded. + +In addition to the side-effects of the @option{-C} option, the +@option{-CC} option causes all C++-style comments inside a macro +to be converted to C-style comments. This is to prevent later use +of that macro from inadvertently commenting out the remainder of +the source line. + +The @option{-CC} option is generally used to support lint comments. + @item -gcc @opindex gcc Define the macros @sc{__gnuc__}, @sc{__gnuc_minor__} and @@ -517,10 +569,10 @@ Define the macros @sc{__gnuc__}, @sc{__gnuc_minor__} and @command{gcc -E}; you can turn them off in that case with @option{-no-gcc}. -@item -traditional -@opindex traditional -Try to imitate the behavior of old-fashioned C, as opposed to ISO -C@. +@item -traditional-cpp +@opindex traditional-cpp +Try to imitate the behavior of old-fashioned C preprocessors, as +opposed to ISO C preprocessors. @ifset cppmanual @xref{Traditional Mode}. @end ifset @@ -552,16 +604,8 @@ Replacement: [ ] @{ @} # \ ^ | ~ Enable special code to work around file systems which only permit very short file names, such as MS-DOS@. -@item -$ -@opindex $ -Forbid the use of @samp{$} in identifiers. The C standard allows -implementations to define extra characters that can appear in -identifiers. By default GNU CPP permits @samp{$}, a common extension. - -@item -h @itemx --help @itemx --target-help -@opindex h @opindex help @opindex target-help Print text describing all the command line options instead of diff --git a/contrib/gcc/doc/extend.texi b/contrib/gcc/doc/extend.texi index 281e4ac..484a646 100644 --- a/contrib/gcc/doc/extend.texi +++ b/contrib/gcc/doc/extend.texi @@ -1,4 +1,5 @@ -@c Copyright (C) 1988,1989,1992,1993,1994,1996,1998,1999,2000,2001,2002 Free Software Foundation, Inc. +@c Copyright (C) 1988,1989,1992,1993,1994,1996,1998,1999,2000,2001,2002, +@c 2003 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -35,6 +36,8 @@ along with the section number from the ISO/IEC 9899:1999 standard. @item @cite{How a diagnostic is identified (3.10, 5.1.1.3).} +Diagnostics consist of all the output sent to stderr by GCC. + @item @cite{Whether each nonempty sequence of white-space characters other than new-line is retained or replaced by one space character in translation @@ -58,6 +61,11 @@ and their correspondence to universal character names (6.4.2).} @item @cite{The number of significant initial characters in an identifier (5.2.4.1, 6.4.2).} + +For internal names, all characters are significant. For external names, +the number of significant characters are defined by the linker; for +almost all targets, all characters are significant. + @end itemize @node Characters implementation @@ -123,6 +131,9 @@ sequence not represented in the execution character set (6.4.5).} two's complement, or one's complement, and whether the extraordinary value is a trap representation or an ordinary value (6.2.6.2).} +GCC supports only two's complement integer types, and all bit patterns +are ordinary values. + @item @cite{The rank of any extended integer type relative to another extended integer type with the same precision (6.3.1.1).} @@ -238,10 +249,36 @@ of the same array (6.5.6).} @cite{The extent to which suggestions made by using the @code{register} storage-class specifier are effective (6.7.1).} +The @code{register} specifier affects code generation only in these ways: + +@itemize @bullet +@item +When used as part of the register variable extension, see +@ref{Explicit Reg Vars}. + +@item +When @option{-O0} is in use, the compiler allocates distinct stack +memory for all variables that do not have the @code{register} +storage-class specifier; if @code{register} is specified, the variable +may have a shorter lifespan than the code would indicate and may never +be placed in memory. + +@item +On some rare x86 targets, @code{setjmp} doesn't save the registers in +all circumstances. In those cases, GCC doesn't allocate any variables +in registers unless they are marked @code{register}. + +@end itemize + @item @cite{The extent to which suggestions made by using the inline function specifier are effective (6.7.4).} +GCC will not inline any functions if the @option{-fno-inline} option is +used or if @option{-O0} is used. Otherwise, GCC may still be unable to +inline a function for many reasons; the @option{-Winline} option may be +used to determine if a function has not been inlined and why not. + @end itemize @node Structures unions enumerations and bit-fields implementation @@ -315,6 +352,8 @@ name (6.10.2).} @item @cite{The nesting limit for @code{#include} processing (6.10.2).} +GCC imposes a limit of 200 nested @code{#include}s. + @item @cite{Whether the @samp{#} operator inserts a @samp{\} character before the @samp{\} character that begins a universal character name in a @@ -328,6 +367,10 @@ directive (6.10.6).} @cite{The definitions for @code{__DATE__} and @code{__TIME__} when respectively, the date and time of translation are not available (6.10.8).} +If the date and time are not available, @code{__DATE__} expands to +@code{@w{"??? ?? ????"}} and @code{__TIME__} expands to +@code{"??:??:??"}. + @end itemize @node Library functions implementation @@ -393,9 +436,9 @@ extensions, accepted by GCC in C89 mode and in C++. * Hex Floats:: Hexadecimal floating-point constants. * Zero Length:: Zero-length arrays. * Variable Length:: Arrays whose length is computed at run time. +* Empty Structures:: Structures with no members. * Variadic Macros:: Macros with a variable number of arguments. * Escaped Newlines:: Slightly looser rules for escaped newlines. -* Multi-line Strings:: String literals with embedded newlines. * 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. @@ -431,6 +474,7 @@ extensions, accepted by GCC in C89 mode and in C++. * Target Builtins:: Built-in functions specific to particular targets. * Pragmas:: Pragmas accepted by GCC. * Unnamed Fields:: Unnamed struct/union fields within structs/unions. +* Thread-Local:: Per-thread variables. @end menu @node Statement Exprs @@ -442,7 +486,6 @@ extensions, accepted by GCC in C89 mode and in C++. @c the above section title wrapped and causes an underfull hbox.. i @c changed it from "within" to "in". --mew 4feb93 - A compound statement enclosed in parentheses may appear as an expression in GNU C@. This allows you to use loops, switches, and local variables within an expression. @@ -549,7 +592,7 @@ __label__ @var{label}; or @example -__label__ @var{label1}, @var{label2}, @dots{}; +__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; @end example Local label declarations must come at the beginning of the statement @@ -600,7 +643,7 @@ wherever a constant of that type is valid. For example: @example void *ptr; -@dots{} +/* @r{@dots{}} */ ptr = &&foo; @end example @@ -695,9 +738,9 @@ bar (int *array, int offset, int size) int access (int *array, int index) @{ return array[index + offset]; @} int i; - @dots{} + /* @r{@dots{}} */ for (i = 0; i < size; i++) - @dots{} access (array, i) @dots{} + /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ @} @end group @end example @@ -757,10 +800,10 @@ bar (int *array, int offset, int size) return array[index + offset]; @} int i; - @dots{} + /* @r{@dots{}} */ for (i = 0; i < size; i++) - @dots{} access (array, i) @dots{} - @dots{} + /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ + /* @r{@dots{}} */ return 0; /* @r{Control comes here from @code{access} @@ -781,14 +824,14 @@ bar (int *array, int offset, int size) @{ __label__ failure; auto int access (int *, int); - @dots{} + /* @r{@dots{}} */ int access (int *array, int index) @{ if (index > size) goto failure; return array[index + offset]; @} - @dots{} + /* @r{@dots{}} */ @} @end example @@ -843,19 +886,6 @@ the containing function. You should specify, for @var{result}, a value returned by @code{__builtin_apply}. @end deftypefn -@cindex underscores in variables in macros -@cindex @samp{_} in variables in macros -@cindex local variables in macros -@cindex variables, local, in macros -@cindex macros, local variables in - -The reason for using names that start with underscores for the local -variables is to avoid conflicts with variable names that occur within the -expressions that are substituted for @code{a} and @code{b}. Eventually we -hope to design a new form of declaration syntax that allows you to declare -variables whose scopes start only after their initializers; this will be a -more reliable way to prevent such conflicts. - @node Typeof @section Referring to a Type with @code{typeof} @findex typeof @@ -906,6 +936,19 @@ arithmetic type and evaluates each of its arguments exactly once: _a > _b ? _a : _b; @}) @end example +@cindex underscores in variables in macros +@cindex @samp{_} in variables in macros +@cindex local variables in macros +@cindex variables, local, in macros +@cindex macros, local variables in + +The reason for using names that start with underscores for the local +variables is to avoid conflicts with variable names that occur within the +expressions that are substituted for @code{a} and @code{b}. Eventually we +hope to design a new form of declaration syntax that allows you to declare +variables whose scopes start only after their initializers; this will be a +more reliable way to prevent such conflicts. + @noindent Some more examples of the use of @code{typeof}: @@ -989,6 +1032,7 @@ This will work with all versions of GCC@. @cindex lvalues, generalized @cindex extensions, @code{?:} @cindex @code{?:} extensions + Compound expressions, conditional expressions and casts are allowed as lvalues provided their operands are lvalues. This means that you can take their addresses or store values into them. @@ -1181,17 +1225,14 @@ provided as built-in functions by GCC@. GCC can allocate complex automatic variables in a noncontiguous fashion; it's even possible for the real part to be in a register while -the imaginary part is on the stack (or vice-versa). None of the -supported debugging info formats has a way to represent noncontiguous -allocation like this, so GCC describes a noncontiguous complex -variable as if it were two separate variables of noncomplex type. +the imaginary part is on the stack (or vice-versa). Only the DWARF2 +debug info format can represent this, so use of DWARF2 is recommended. +If you are using the stabs debug info format, GCC describes a noncontiguous +complex variable as if it were two separate variables of noncomplex type. If the variable's actual name is @code{foo}, the two fictitious variables are named @code{foo$real} and @code{foo$imag}. You can examine and set these two fictitious variables with your debugger. -A future version of GDB will know how to recognize such pairs and treat -them as a single variable with a complex type. - @node Hex Floats @section Hex Floats @cindex hex floats @@ -1241,7 +1282,7 @@ struct line *thisline = (struct line *) thisline->length = this_length; @end example -In ISO C89, you would have to give @code{contents} a length of 1, which +In ISO C90, you would have to give @code{contents} a length of 1, which means either you waste space or complicate the argument to @code{malloc}. In ISO C99, you would use a @dfn{flexible array member}, which is @@ -1260,6 +1301,12 @@ of zero-length arrays, @code{sizeof} evaluates to zero. @item Flexible array members may only appear as the last member of a @code{struct} that is otherwise non-empty. + +@item +A structure containing a flexible array member, or a union containing +such a structure (possibly recursively), may not be a member of a +structure or an element of an array. (However, these uses are +permitted by GCC as extensions.) @end itemize GCC versions before 3.0 allowed zero-length arrays to be statically @@ -1311,6 +1358,21 @@ struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.} @end example +@node Empty Structures +@section Structures With No Members +@cindex empty structures +@cindex zero-size structures + +GCC permits a C structure to have no members: + +@example +struct empty @{ +@}; +@end example + +The structure will have size zero. In C++, empty structures are part +of the language, and the language standard says they have size 1. + @node Variable Length @section Arrays of Variable Length @cindex variable-length arrays @@ -1363,7 +1425,7 @@ You can also use variable-length arrays as arguments to functions: struct entry tester (int len, char data[len][len]) @{ - @dots{} + /* @r{@dots{}} */ @} @end example @@ -1378,7 +1440,7 @@ use a forward declaration in the parameter list---another GNU extension. struct entry tester (int len; char data[len][len], int len) @{ - @dots{} + /* @r{@dots{}} */ @} @end example @@ -1463,29 +1525,16 @@ argument, these arguments are not macro expanded. @cindex escaped newlines @cindex newlines (escaped) -Recently, the non-traditional preprocessor has relaxed its treatment of -escaped newlines. Previously, the newline had to immediately follow a +Recently, the preprocessor has relaxed its treatment of escaped +newlines. Previously, the newline had to immediately follow a backslash. The current implementation allows whitespace in the form of spaces, horizontal and vertical tabs, and form feeds between the backslash and the subsequent newline. The preprocessor issues a warning, but treats it as a valid escaped newline and combines the two lines to form a single logical line. This works within comments and -tokens, including multi-line strings, as well as between tokens. -Comments are @emph{not} treated as whitespace for the purposes of this -relaxation, since they have not yet been replaced with spaces. - -@node Multi-line Strings -@section String Literals with Embedded Newlines -@cindex multi-line string literals - -As an extension, GNU CPP permits string literals to cross multiple lines -without escaping the embedded newlines. Each embedded newline is -replaced with a single @samp{\n} character in the resulting string -literal, regardless of what form the newline took originally. - -CPP currently allows such strings in directives as well (other than the -@samp{#include} family). This is deprecated and will eventually be -removed. +tokens, as well as between tokens. Comments are @emph{not} treated as +whitespace for the purposes of this relaxation, since they have not +yet been replaced with spaces. @node Subscripting @section Non-Lvalue Arrays May Have Subscripts @@ -1545,7 +1594,7 @@ Here is an example of an initializer with run-time varying elements: foo (float f, float g) @{ float beat_freqs[2] = @{ f-g, f+g @}; - @dots{} + /* @r{@dots{}} */ @} @end example @@ -1834,7 +1883,7 @@ union type is equivalent to storing in a member of the union: @example union foo u; -@dots{} +/* @r{@dots{}} */ u = (union foo) x @equiv{} u.i = x u = (union foo) y @equiv{} u.d = y @end example @@ -1843,7 +1892,7 @@ You can also use the union cast as a function argument: @example void hack (union foo); -@dots{} +/* @r{@dots{}} */ hack ((union foo) x); @end example @@ -1859,7 +1908,7 @@ C89 mode. For example, you could do: @example int i; -@dots{} +/* @r{@dots{}} */ i++; int j = i + 2; @end example @@ -1878,6 +1927,7 @@ the enclosing block. @cindex @code{volatile} applied to function @cindex @code{const} applied to function @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments +@cindex functions with non-null pointer arguments @cindex functions that are passed arguments in registers on the 386 @cindex functions that pop the argument stack on the 386 @cindex functions that do not pop the argument stack on the 386 @@ -1891,14 +1941,14 @@ attributes when making a declaration. This keyword is followed by an attribute specification inside double parentheses. The following attributes are currently defined for functions on all targets: @code{noreturn}, @code{noinline}, @code{always_inline}, -@code{pure}, @code{const}, +@code{pure}, @code{const}, @code{nothrow}, @code{format}, @code{format_arg}, @code{no_instrument_function}, @code{section}, @code{constructor}, @code{destructor}, @code{used}, -@code{unused}, @code{deprecated}, @code{weak}, @code{malloc}, and -@code{alias}. Several other attributes are defined for functions on -particular target systems. Other attributes, including @code{section} -are supported for variables declarations (@pxref{Variable Attributes}) -and for types (@pxref{Type Attributes}). +@code{unused}, @code{deprecated}, @code{weak}, @code{malloc}, +@code{alias}, and @code{nonnull}. Several other attributes are defined +for functions on particular target systems. Other attributes, including +@code{section} are supported for variables declarations +(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}). You may also specify attributes with @samp{__} preceding and following each keyword. This allows you to use them in header files without @@ -1921,9 +1971,9 @@ their own functions that never return. You can declare them void fatal () __attribute__ ((noreturn)); void -fatal (@dots{}) +fatal (/* @r{@dots{}} */) @{ - @dots{} /* @r{Print error message.} */ @dots{} + /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ exit (1); @} @end group @@ -2015,6 +2065,14 @@ extern const intfn square; This approach does not work in GNU C++ from 2.6.0 on, since the language specifies that the @samp{const} must be attached to the return value. +@cindex @code{nothrow} function attribute +@item nothrow +The @code{nothrow} attribute is used to inform the compiler that a +function cannot throw an exception. For example, most functions in +the standard C library can be guaranteed not to throw an exception +with the notable exceptions of @code{qsort} and @code{bsearch} that +take function pointer arguments. The @code{nothrow} attribute is not +implemented in GCC versions earlier than 3.2. @item format (@var{archetype}, @var{string-index}, @var{first-to-check}) @cindex @code{format} function attribute @@ -2110,6 +2168,35 @@ requested by @option{-ansi} or an appropriate @option{-std} option, or @option{-ffreestanding} is used. @xref{C Dialect Options,,Options Controlling C Dialect}. +@item nonnull (@var{arg-index}, @dots{}) +@cindex @code{nonnull} function attribute +The @code{nonnull} attribute specifies that some function parameters should +be non-null pointers. For instance, the declaration: + +@smallexample +extern void * +my_memcpy (void *dest, const void *src, size_t len) + __attribute__((nonnull (1, 2))); +@end smallexample + +@noindent +causes the compiler to check that, in calls to @code{my_memcpy}, +arguments @var{dest} and @var{src} are non-null. If the compiler +determines that a null pointer is passed in an argument slot marked +as non-null, and the @option{-Wnonnull} option is enabled, a warning +is issued. The compiler may also choose to make optimizations based +on the knowledge that certain function arguments will not be null. + +If no argument index list is given to the @code{nonnull} attribute, +all pointer arguments are marked as non-null. To illustrate, the +following declaration is equivalent to the previous example: + +@smallexample +extern void * +my_memcpy (void *dest, const void *src, size_t len) + __attribute__((nonnull)); +@end smallexample + @item no_instrument_function @cindex @code{no_instrument_function} function attribute @opindex finstrument-functions @@ -2208,7 +2295,7 @@ The @code{alias} attribute causes the declaration to be emitted as an alias for another symbol, which must be specified. For instance, @smallexample -void __f () @{ /* do something */; @} +void __f () @{ /* @r{Do something.} */; @} void f () __attribute__ ((weak, alias ("__f"))); @end smallexample @@ -2217,7 +2304,60 @@ mangled name for the target must be used. Not all target machines support this attribute. +@item visibility ("@var{visibility_type}") +@cindex @code{visibility} attribute +The @code{visibility} attribute on ELF targets causes the declaration +to be emitted with default, hidden, protected or internal visibility. + +@smallexample +void __attribute__ ((visibility ("protected"))) +f () @{ /* @r{Do something.} */; @} +int i __attribute__ ((visibility ("hidden"))); +@end smallexample + +See the ELF gABI for complete details, but the short story is: + +@table @dfn +@item default +Default visibility is the normal case for ELF. This value is +available for the visibility attribute to override other options +that may change the assumed visibility of symbols. + +@item hidden +Hidden visibility indicates that the symbol will not be placed into +the dynamic symbol table, so no other @dfn{module} (executable or +shared library) can reference it directly. + +@item protected +Protected visibility indicates that the symbol will be placed in the +dynamic symbol table, but that references within the defining module +will bind to the local symbol. That is, the symbol cannot be overridden +by another module. + +@item internal +Internal visibility is like hidden visibility, but with additional +processor specific semantics. Unless otherwise specified by the psABI, +gcc defines internal visibility to mean that the function is @emph{never} +called from another module. Note that hidden symbols, while then cannot +be referenced directly by other modules, can be referenced indirectly via +function pointers. By indicating that a symbol cannot be called from +outside the module, gcc may for instance omit the load of a PIC register +since it is known that the calling function loaded the correct value. +@end table + +Not all ELF targets support this attribute. + +@item tls_model ("@var{tls_model}") +@cindex @code{tls_model} attribute +The @code{tls_model} attribute sets thread-local storage model +(@pxref{Thread-Local}) of a particular @code{__thread} variable, +overriding @code{-ftls-model=} command line switch on a per-variable +basis. +The @var{tls_model} argument should be one of @code{global-dynamic}, +@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. + @item regparm (@var{number}) +@cindex @code{regparm} attribute @cindex functions that are passed arguments in registers on the 386 On the Intel 386, the @code{regparm} attribute causes the compiler to pass up to @var{number} integer arguments in registers EAX, @@ -2225,6 +2365,16 @@ EDX, and ECX instead of on the stack. Functions that take a variable number of arguments will continue to be passed all of their arguments on the stack. +Beware that on some ELF systems this attribute is unsuitable for +global functions in shared libraries with lazy binding (which is the +default). Lazy binding will send the first call via resolving code in +the loader, which might assume EAX, EDX and ECX can be clobbered, as +per the standard calling conventions. Solaris 8 is affected by this. +GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be +safe since the loaders there save all registers. (Lazy binding can be +disabled with the linker or the loader if desired, to avoid the +problem.) + @item stdcall @cindex functions that pop the argument stack on the 386 On the Intel 386, the @code{stdcall} attribute causes the compiler to @@ -2245,12 +2395,17 @@ useful to override the effects of the @option{-mrtd} switch. The PowerPC compiler for Windows NT currently ignores the @code{cdecl} attribute. -@item longcall +@item longcall/shortcall @cindex functions called via pointer on the RS/6000 and PowerPC On the RS/6000 and PowerPC, the @code{longcall} attribute causes the -compiler to always call the function via a pointer, so that functions -which reside further than 64 megabytes (67,108,864 bytes) from the -current location can be called. +compiler to always call this function via a pointer, just as it would if +the @option{-mlongcall} option had been specified. The @code{shortcall} +attribute causes the compiler not to do this. These attributes override +both the @option{-mlongcall} switch and the @code{#pragma longcall} +setting. + +@xref{RS/6000 and PowerPC Options}, for more information on when long +calls are and are not necessary. @item long_call/short_call @cindex indirect calls on ARM @@ -2372,9 +2527,9 @@ attribute is present. Interrupts will be disabled inside function. @item naked @cindex function without a prologue/epilogue code -Use this attribute on the ARM or AVR ports to indicate that the specified -function do not need prologue/epilogue sequences generated by the -compiler. It is up to the programmer to provide these sequences. +Use this attribute on the ARM, AVR and IP2K ports to indicate that the +specified function do not need prologue/epilogue sequences generated by +the compiler. It is up to the programmer to provide these sequences. @item model (@var{model-name}) @cindex function addressability on the M32R/D @@ -2396,6 +2551,30 @@ compiler will generate @code{seth/add3} instructions to load their addresses), and may not be reachable with the @code{bl} instruction (the compiler will generate the much slower @code{seth/add3/jl} instruction sequence). +@item far +@cindex functions which handle memory bank switching +On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to +use a calling convention that takes care of switching memory banks when +entering and leaving a function. This calling convention is also the +default when using the @option{-mlong-calls} option. + +On 68HC12 the compiler will use the @code{call} and @code{rtc} instructions +to call and return from a function. + +On 68HC11 the compiler will generate a sequence of instructions +to invoke a board-specific routine to switch the memory bank and call the +real function. The board-specific routine simulates a @code{call}. +At the end of a function, it will jump to a board-specific routine +instead of using @code{rts}. The board-specific return routine simulates +the @code{rtc}. + +@item near +@cindex functions which do not handle memory bank switching on 68HC11/68HC12 +On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to +use the normal calling convention based on @code{jsr} and @code{rts}. +This attribute can be used to cancel the effect of the @option{-mlong-calls} +option. + @end table You can specify multiple attributes in a declaration by separating them @@ -2729,11 +2908,10 @@ extension is irrelevant. In GNU C, you may use C++ style comments, which start with @samp{//} and continue until the end of the line. Many other C implementations allow -such comments, and they are likely to be in a future C standard. -However, C++ style comments are not recognized if you specify -@w{@option{-ansi}}, a @option{-std} option specifying a version of ISO C -before C99, or @w{@option{-traditional}}, since they are incompatible -with traditional constructs like @code{dividend//*comment*/divisor}. +such comments, and they are included in the 1999 C standard. However, +C++ style comments are not recognized if you specify an @option{-std} +option specifying a version of ISO C before C99, or @option{-ansi} +(equivalent to @option{-std=c89}). @node Dollar Signs @section Dollar Signs in Identifier Names @@ -2870,6 +3048,22 @@ up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} in an @code{__attribute__} will still only provide you with 8 byte alignment. See your linker documentation for further information. +@item cleanup (@var{cleanup_function}) +@cindex @code{cleanup} attribute +The @code{cleanup} attribute runs a function when the variable goes +out of scope. This attribute can only be applied to auto function +scope variables; it may not be applied to parameters or variables +with static storage duration. The function must take one parameter, +a pointer to a type compatible with the variable. The return value +of the function (if any) is ignored. + +If @option{-fexceptions} is enabled, then @var{cleanup_function} +will be run during the stack unwinding that happens during the +processing of the exception. Note that the @code{cleanup} attribute +does not allow the exception to be caught, only to perform an action. +It is undefined what happens if @var{cleanup_function} does not +return normally. + @item mode (@var{mode}) @cindex @code{mode} attribute This attribute specifies the data type for the declaration---whichever @@ -3078,10 +3272,11 @@ packed))}. The keyword @code{__attribute__} allows you to specify special attributes of @code{struct} and @code{union} types when you define such types. This keyword is followed by an attribute specification inside -double parentheses. Five attributes are currently defined for types: +double parentheses. Six attributes are currently defined for types: @code{aligned}, @code{packed}, @code{transparent_union}, @code{unused}, -and @code{deprecated}. Other attributes are defined for functions -(@pxref{Function Attributes}) and for variables (@pxref{Variable Attributes}). +@code{deprecated} and @code{may_alias}. Other attributes are defined for +functions (@pxref{Function Attributes}) and for variables +(@pxref{Variable Attributes}). You may also specify any one of these attributes with @samp{__} preceding and following its keyword. This allows you to use these @@ -3115,7 +3310,7 @@ typedef int more_aligned_int __attribute__ ((aligned (8))); @noindent force the compiler to insure (as far as it can) that each variable whose type is @code{struct S} or @code{more_aligned_int} will be allocated and -aligned @emph{at least} on a 8-byte boundary. On a Sparc, having all +aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all variables of type @code{struct S} aligned to 8-byte boundaries allows the compiler to use the @code{ldd} and @code{std} (doubleword load and store) instructions when copying one variable of type @code{struct S} to @@ -3292,6 +3487,36 @@ deprecated. Similarly for line 6. The @code{deprecated} attribute can also be used for functions and variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) +@item may_alias +Accesses to objects with types with this attribute are not subjected to +type-based alias analysis, but are instead assumed to be able to alias +any other type of objects, just like the @code{char} type. See +@option{-fstrict-aliasing} for more information on aliasing issues. + +Example of use: + +@smallexample +typedef short __attribute__((__may_alias__)) short_a; + +int +main (void) +@{ + int a = 0x12345678; + short_a *b = (short_a *) &a; + + b[1] = 0; + + if (a == 0x12345678) + abort(); + + exit(0); +@} +@end smallexample + +If you replaced @code{short_a} with @code{short} in the variable +declaration, the above program would abort when compiled with +@option{-fstrict-aliasing}, which is on by default at @option{-O2} or +above in recent GCC versions. @end table To specify multiple attributes, separate them by commas within the @@ -3550,7 +3775,10 @@ asm volatile ("movc3 %0,%1,%2" You may not write a clobber description in a way that overlaps with an input or output operand. For example, you may not have an operand describing a register class with one member if you mention that register -in the clobber list. There is no way for you to specify that an input +in the clobber list. Variables declared to live in specific registers +(@pxref{Explicit Reg Vars}), and used as asm input or output operands must +have no part mentioned in the clobber description. +There is no way for you to specify that an input operand is modified without also specifying it as an output operand. Note that if all the output operands you specify are for this purpose (and hence unused), you will then also need to specify @@ -3854,7 +4082,7 @@ extern func () asm ("FUNC"); func (x, y) int x, y; -@dots{} +/* @r{@dots{}} */ @end example It is up to you to make sure that the assembler names you choose do not @@ -3990,7 +4218,7 @@ being used for other purposes in the preceding functions. Global register variables may not have initial values, because an executable file has no means to supply initial contents for a register. -On the Sparc, there are reports that g3 @dots{} g7 are suitable +On the SPARC, there are reports that g3 @dots{} g7 are suitable registers, but certain library functions, such as @code{getwd}, as well as the subroutines for division and remainder, modify g3 and g4. g1 and g2 are local temporaries. @@ -4047,25 +4275,20 @@ be deleted or moved or simplified. @cindex alternate keywords @cindex keywords, alternate -The option @option{-traditional} disables certain keywords; @option{-ansi} and the various @option{-std} options disable certain -others. This causes trouble when you want to use GNU C extensions, or -ISO C features, in a general-purpose header file that should be usable -by all programs, including ISO 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 @option{-ansi} -(although @code{inline} can be used in a program compiled with -@option{-std=c99}), while the keywords @code{const}, @code{volatile}, -@code{signed}, @code{typeof} and @code{inline} won't work in a program -compiled with @option{-traditional}. The ISO C99 keyword +keywords. This causes trouble when you want to use GNU C extensions, or +a general-purpose header file that should be usable by all programs, +including ISO C programs. The keywords @code{asm}, @code{typeof} and +@code{inline} are not available in programs compiled with +@option{-ansi} or @option{-std} (although @code{inline} can be used in a +program compiled with @option{-std=c99}). The ISO C99 keyword @code{restrict} is only available when @option{-std=gnu99} (which will eventually be the default) or @option{-std=c99} (or the equivalent @option{-std=iso9899:1999}) is used. 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}. +instead of @code{asm}, 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 @@ -4197,7 +4420,10 @@ This function returns the return address of the current function, or of one of its callers. The @var{level} argument is number of frames to scan up the call stack. A value of @code{0} yields the return address of the current function, a value of @code{1} yields the return address -of the caller of the current function, and so forth. +of the caller of the current function, and so forth. When inlining +the expected behavior is that the function will return the address of +the function that will be returned to. To work around this behavior use +the @code{noinline} function attribute. The @var{level} argument must be a constant integer. @@ -4273,28 +4499,49 @@ A floating point value, as wide as a SI mode integer, usually 32 bits. A floating point value, as wide as a DI mode integer, usually 64 bits. @end table -Not all base types or combinations are always valid; which modes can be used -is determined by the target machine. For example, if targetting the i386 MMX -extensions, only @code{V8QI}, @code{V4HI} and @code{V2SI} are allowed modes. +Specifying a combination that is not valid for the current architecture +will cause gcc to synthesize the instructions using a narrower mode. +For example, if you specify a variable of type @code{V4SI} and your +architecture does not allow for this specific SIMD type, gcc will +produce code that uses 4 @code{SIs}. + +The types defined in this manner can be used with a subset of normal C +operations. Currently, gcc will allow using the following operators on +these types: @code{+, -, *, /, unary minus}@. + +The operations behave like C++ @code{valarrays}. Addition is defined as +the addition of the corresponding elements of the operands. For +example, in the code below, each of the 4 elements in @var{a} will be +added to the corresponding 4 elements in @var{b} and the resulting +vector will be stored in @var{c}. + +@example +typedef int v4si __attribute__ ((mode(V4SI))); + +v4si a, b, c; + +c = a + b; +@end example -There are no @code{V1xx} vector modes - they would be identical to the -corresponding base mode. +Subtraction, multiplication, and division operate in a similar manner. +Likewise, the result of using the unary minus operator on a vector type +is a vector whose elements are the negative value of the corresponding +elements in the operand. -There is no distinction between signed and unsigned vector modes. This -distinction is made by the operations that perform on the vectors, not -by the data type. +You can declare variables and use them in function calls and returns, as +well as in assignments and some casts. You can specify a vector type as +a return type for a function. Vector types can also be used as function +arguments. It is possible to cast from one vector type to another, +provided they are of the same size (in fact, you can also cast vectors +to and from other datatypes of the same size). -The types defined in this manner are somewhat special, they cannot be -used with most normal C operations (i.e., a vector addition can @emph{not} -be represented by a normal addition of two vector type variables). You -can declare only variables and use them in function calls and returns, as -well as in assignments and some casts. It is possible to cast from one -vector type to another, provided they are of the same size (in fact, you -can also cast vectors to and from other datatypes of the same size). +You cannot operate between vectors of different lengths or different +signedness without a cast. -A port that supports vector operations provides a set of built-in functions -that can be used to operate on vectors. For example, a function to add two -vectors and multiply the result by a third could look like this: +A port that supports hardware vector operations, usually provides a set +of built-in functions that can be used to operate on vectors. For +example, a function to add two vectors and multiply the result by a +third could look like this: @example v4si f (v4si a, v4si b, v4si c) @@ -4334,6 +4581,9 @@ v4si f (v4si a, v4si b, v4si c) @findex exit @findex _exit @findex _Exit +@findex exp +@findex expf +@findex expl @findex fabs @findex fabsf @findex fabsl @@ -4346,18 +4596,27 @@ v4si f (v4si a, v4si b, v4si c) @findex index @findex labs @findex llabs +@findex log +@findex logf +@findex logl @findex memcmp @findex memcpy @findex memset @findex printf @findex printf_unlocked +@findex putchar +@findex puts @findex rindex +@findex scanf @findex sin @findex sinf @findex sinl +@findex snprintf +@findex sprintf @findex sqrt @findex sqrtf @findex sqrtl +@findex sscanf @findex strcat @findex strchr @findex strcmp @@ -4371,6 +4630,11 @@ v4si f (v4si a, v4si b, v4si c) @findex strrchr @findex strspn @findex strstr +@findex vprintf +@findex vscanf +@findex vsnprintf +@findex vsprintf +@findex vsscanf GCC provides a large number of built-in functions other than the ones mentioned above. Some of these are for internal use in the processing @@ -4395,7 +4659,9 @@ The functions @code{abort}, @code{exit}, @code{_Exit} and @code{_exit} are recognized and presumed not to return, but otherwise are not built in. @code{_exit} is not recognized in strict ISO C mode (@option{-ansi}, @option{-std=c89} or @option{-std=c99}). @code{_Exit} is not recognized in -strict C89 mode (@option{-ansi} or @option{-std=c89}). +strict C89 mode (@option{-ansi} or @option{-std=c89}). All these functions +have corresponding versions prefixed with @code{__builtin_}, which may be +used even in strict C89 mode. Outside strict ISO C mode, the functions @code{alloca}, @code{bcmp}, @code{bzero}, @code{index}, @code{rindex}, @code{ffs}, @code{fputs_unlocked}, @@ -4406,20 +4672,26 @@ mode. The ISO C99 functions @code{conj}, @code{conjf}, @code{conjl}, @code{creal}, @code{crealf}, @code{creall}, @code{cimag}, @code{cimagf}, -@code{cimagl}, @code{llabs} and @code{imaxabs} are handled as built-in -functions except in strict ISO C89 mode. There are also built-in +@code{cimagl}, @code{imaxabs}, @code{llabs}, @code{snprintf}, +@code{vscanf}, @code{vsnprintf} and @code{vsscanf} are handled as built-in +functions except in strict ISO C90 mode. There are also built-in versions of the ISO C99 functions @code{cosf}, @code{cosl}, -@code{fabsf}, @code{fabsl}, @code{sinf}, @code{sinl}, @code{sqrtf}, and -@code{sqrtl}, that are recognized in any mode since ISO C89 reserves +@code{expf}, @code{expl}, @code{fabsf}, @code{fabsl}, +@code{logf}, @code{logl}, @code{sinf}, @code{sinl}, @code{sqrtf}, and +@code{sqrtl}, that are recognized in any mode since ISO C90 reserves these names for the purpose to which ISO C99 puts them. All these functions have corresponding versions prefixed with @code{__builtin_}. -The ISO C89 functions @code{abs}, @code{cos}, @code{fabs}, -@code{fprintf}, @code{fputs}, @code{labs}, @code{memcmp}, @code{memcpy}, -@code{memset}, @code{printf}, @code{sin}, @code{sqrt}, @code{strcat}, +The ISO C90 functions @code{abs}, @code{cos}, @code{exp}, @code{fabs}, +@code{fprintf}, @code{fputs}, @code{labs}, @code{log}, +@code{memcmp}, @code{memcpy}, +@code{memset}, @code{printf}, @code{putchar}, @code{puts}, @code{scanf}, +@code{sin}, @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, +@code{strcat}, @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, -@code{strpbrk}, @code{strrchr}, @code{strspn}, and @code{strstr} are all +@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, +@code{vprintf} and @code{vsprintf} are all recognized as built-in functions unless @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} is specified for an individual function). All of these functions have corresponding @@ -4506,13 +4778,15 @@ as @var{exp2}. Example: @smallexample -#define foo(x) \ - __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), double), \ - foo_double (x), \ - __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), float), \ - foo_float (x), \ - /* @r{The void expression results in a compile-time error} \ - @r{when assigning the result to something.} */ \ +#define foo(x) \ + __builtin_choose_expr ( \ + __builtin_types_compatible_p (typeof (x), double), \ + foo_double (x), \ + __builtin_choose_expr ( \ + __builtin_types_compatible_p (typeof (x), float), \ + foo_float (x), \ + /* @r{The void expression results in a compile-time error} \ + @r{when assigning the result to something.} */ \ (void)0)) @end smallexample @@ -4559,7 +4833,7 @@ data. For instance, you can write @smallexample static const int table[] = @{ __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, - /* ... */ + /* @r{@dots{}} */ @}; @end smallexample @@ -4635,7 +4909,7 @@ for (i = 0; i < n; i++) a[i] = a[i] + b[i]; __builtin_prefetch (&a[i+j], 1, 1); __builtin_prefetch (&b[i+j], 0, 1); - /* ... */ + /* @r{@dots{}} */ @} @end smallexample @@ -4649,6 +4923,74 @@ is evaluated if it includes side effects but no other code is generated and GCC does not issue a warning. @end deftypefn +@deftypefn {Built-in Function} double __builtin_huge_val (void) +Returns a positive infinity, if supported by the floating-point format, +else @code{DBL_MAX}. This function is suitable for implementing the +ISO C macro @code{HUGE_VAL}. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_huge_valf (void) +Similar to @code{__builtin_huge_val}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) +Similar to @code{__builtin_huge_val}, except the return +type is @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_inf (void) +Similar to @code{__builtin_huge_val}, except a warning is generated +if the target floating-point format does not support infinities. +This function is suitable for implementing the ISO C99 macro @code{INFINITY}. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_inff (void) +Similar to @code{__builtin_inf}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} {long double} __builtin_infl (void) +Similar to @code{__builtin_inf}, except the return +type is @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_nan (const char *str) +This is an implementation of the ISO C99 function @code{nan}. + +Since ISO C99 defines this function in terms of @code{strtod}, which we +do not implement, a description of the parsing is in order. The string +is parsed as by @code{strtol}; that is, the base is recognized by +leading @samp{0} or @samp{0x} prefixes. The number parsed is placed +in the significand such that the least significant bit of the number +is at the least significant bit of the significand. The number is +truncated to fit the significand field provided. The significand is +forced to be a quiet NaN. + +This function, if given a string literal, is evaluated early enough +that it is considered a compile-time constant. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_nanf (const char *str) +Similar to @code{__builtin_nan}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) +Similar to @code{__builtin_nan}, except the return type is @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_nans (const char *str) +Similar to @code{__builtin_nan}, except the significand is forced +to be a signaling NaN. The @code{nans} function is proposed by +@uref{http://std.dkuug.dk/JTC1/SC22/WG14/www/docs/n965.htm,,WG14 N965}. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_nansf (const char *str) +Similar to @code{__builtin_nans}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) +Similar to @code{__builtin_nans}, except the return type is @code{long double}. +@end deftypefn + @node Target Builtins @section Built-in Functions Specific to Particular Target Machines @@ -4657,10 +4999,93 @@ to those machines. Generally these generate calls to specific machine instructions, but allow the compiler to schedule those calls. @menu +* Alpha Built-in Functions:: * X86 Built-in Functions:: * PowerPC AltiVec Built-in Functions:: @end menu +@node Alpha Built-in Functions +@subsection Alpha Built-in Functions + +These built-in functions are available for the Alpha family of +processors, depending on the command-line switches used. + +The following built-in functions are always available. They +all generate the machine instruction that is part of the name. + +@example +long __builtin_alpha_implver (void) +long __builtin_alpha_rpcc (void) +long __builtin_alpha_amask (long) +long __builtin_alpha_cmpbge (long, long) +long __builtin_alpha_extbl (long, long) +long __builtin_alpha_extwl (long, long) +long __builtin_alpha_extll (long, long) +long __builtin_alpha_extql (long, long) +long __builtin_alpha_extwh (long, long) +long __builtin_alpha_extlh (long, long) +long __builtin_alpha_extqh (long, long) +long __builtin_alpha_insbl (long, long) +long __builtin_alpha_inswl (long, long) +long __builtin_alpha_insll (long, long) +long __builtin_alpha_insql (long, long) +long __builtin_alpha_inswh (long, long) +long __builtin_alpha_inslh (long, long) +long __builtin_alpha_insqh (long, long) +long __builtin_alpha_mskbl (long, long) +long __builtin_alpha_mskwl (long, long) +long __builtin_alpha_mskll (long, long) +long __builtin_alpha_mskql (long, long) +long __builtin_alpha_mskwh (long, long) +long __builtin_alpha_msklh (long, long) +long __builtin_alpha_mskqh (long, long) +long __builtin_alpha_umulh (long, long) +long __builtin_alpha_zap (long, long) +long __builtin_alpha_zapnot (long, long) +@end example + +The following built-in functions are always with @option{-mmax} +or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or +later. They all generate the machine instruction that is part +of the name. + +@example +long __builtin_alpha_pklb (long) +long __builtin_alpha_pkwb (long) +long __builtin_alpha_unpkbl (long) +long __builtin_alpha_unpkbw (long) +long __builtin_alpha_minub8 (long, long) +long __builtin_alpha_minsb8 (long, long) +long __builtin_alpha_minuw4 (long, long) +long __builtin_alpha_minsw4 (long, long) +long __builtin_alpha_maxub8 (long, long) +long __builtin_alpha_maxsb8 (long, long) +long __builtin_alpha_maxuw4 (long, long) +long __builtin_alpha_maxsw4 (long, long) +long __builtin_alpha_perr (long, long) +@end example + +The following built-in functions are always with @option{-mcix} +or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or +later. They all generate the machine instruction that is part +of the name. + +@example +long __builtin_alpha_cttz (long) +long __builtin_alpha_ctlz (long) +long __builtin_alpha_ctpop (long) +@end example + +The following builtins are available on systems that use the OSF/1 +PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} +PAL calls, but when invoked with @option{-mtls-kernel}, they invoke +@code{rdval} and @code{wrval}. + +@example +void *__builtin_thread_pointer (void) +void __builtin_set_thread_pointer (void *) +@end example + @node X86 Built-in Functions @subsection X86 Built-in Functions @@ -4784,14 +5209,10 @@ v4si __builtin_ia32_cmpordps (v4sf, v4sf) v4si __builtin_ia32_cmpeqss (v4sf, v4sf) v4si __builtin_ia32_cmpltss (v4sf, v4sf) v4si __builtin_ia32_cmpless (v4sf, v4sf) -v4si __builtin_ia32_cmpgtss (v4sf, v4sf) -v4si __builtin_ia32_cmpgess (v4sf, v4sf) v4si __builtin_ia32_cmpunordss (v4sf, v4sf) v4si __builtin_ia32_cmpneqss (v4sf, v4sf) v4si __builtin_ia32_cmpnlts (v4sf, v4sf) v4si __builtin_ia32_cmpnless (v4sf, v4sf) -v4si __builtin_ia32_cmpngtss (v4sf, v4sf) -v4si __builtin_ia32_cmpngess (v4sf, v4sf) v4si __builtin_ia32_cmpordss (v4sf, v4sf) v4sf __builtin_ia32_maxps (v4sf, v4sf) v4sf __builtin_ia32_maxss (v4sf, v4sf) @@ -4904,6 +5325,25 @@ The following functions are made available by including @option{-mabi=altivec}. The functions implement the functionality described in Motorola's AltiVec Programming Interface Manual. +There are a few differences from Motorola's documentation and GCC's +implementation. Vector constants are done with curly braces (not +parentheses). Vector initializers require no casts if the vector +constant is of the same type as the variable it is initializing. The +@code{vector bool} type is deprecated and will be discontinued in +further revisions. Use @code{vector signed} instead. If @code{signed} +or @code{unsigned} is omitted, the vector type will default to +@code{signed}. Lastly, all overloaded functions are implemented with macros +for the C implementation. So code the following example will not work: + +@smallexample + vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); +@end smallexample + +Since vec_add is a macro, the vector constant in the above example will +be treated as four different arguments. Wrap the entire argument in +parentheses for this to work. The C++ implementation does not use +macros. + @emph{Note:} Only the @code{<altivec.h>} interface is supported. Internally, GCC uses built-in functions to achieve the functionality in the aforementioned header file, but they are not supported and are @@ -5249,7 +5689,9 @@ vector unsigned int vec_mulo (vector unsigned short, vector signed int vec_mulo (vector signed short, vector signed short); vector float vec_nmsub (vector float, vector float, vector float); +@end smallexample +@smallexample vector float vec_nor (vector float, vector float); vector signed int vec_nor (vector signed int, vector signed int); vector unsigned int vec_nor (vector unsigned int, vector unsigned int); @@ -5815,7 +6257,9 @@ vector signed int vec_any_eq (vector signed char, vector unsigned char); vector signed int vec_any_eq (vector signed char, vector signed char); vector signed int vec_any_eq (vector unsigned char, vector signed char); +@end smallexample +@smallexample vector signed int vec_any_eq (vector unsigned char, vector unsigned char); vector signed int vec_any_eq (vector signed short, @@ -5970,6 +6414,7 @@ for further explanation. @menu * ARM Pragmas:: +* RS/6000 and PowerPC Pragmas:: * Darwin Pragmas:: * Solaris Pragmas:: * Tru64 Pragmas:: @@ -5998,6 +6443,27 @@ Do not affect the @code{long_call} or @code{short_call} attributes of subsequent functions. @end table +@node RS/6000 and PowerPC Pragmas +@subsection RS/6000 and PowerPC Pragmas + +The RS/6000 and PowerPC targets define one pragma for controlling +whether or not the @code{longcall} attribute is added to function +declarations by default. This pragma overrides the @option{-mlongcall} +option, but not the @code{longcall} and @code{shortcall} attributes. +@xref{RS/6000 and PowerPC Options}, for more information about when long +calls are and are not necessary. + +@table @code +@item longcall (1) +@cindex pragma, longcall +Apply the @code{longcall} attribute to all subsequent function +declarations. + +@item longcall (0) +Do not apply the @code{longcall} attribute to subsequent function +declarations. +@end table + @c Describe c4x pragmas here. @c Describe h8300 pragmas here. @c Describe i370 pragmas here. @@ -6010,7 +6476,7 @@ subsequent functions. The following pragmas are available for all architectures running the Darwin operating system. These are useful for compatibility with other -MacOS compilers. +Mac OS compilers. @table @code @item mark @var{tokens}@dots{} @@ -6066,13 +6532,14 @@ is supported. This pragma renames all subsequent function and variable declarations such that @var{string} is prepended to the name. This effect may be -terminated by using another @code{extern_prefix} pragma with the +terminated by using another @code{extern_prefix} pragma with the empty string. This pragma is similar in intent to to the asm labels extension (@pxref{Asm Labels}) in that the system programmer wants to change the assembly-level ABI without changing the source-level API. The -preprocessor defines @code{__EXTERN_PREFIX} if the pragma is available. +preprocessor defines @code{__PRAGMA_EXTERN_PREFIX} if the pragma is +available. @end table @node Unnamed Fields @@ -6116,6 +6583,265 @@ It is ambiguous which @code{a} is being referred to with @samp{foo.a}. Such constructs are not supported and must be avoided. In the future, such constructs may be detected and treated as compilation errors. +@node Thread-Local +@section Thread-Local Storage +@cindex Thread-Local Storage +@cindex @acronym{TLS} +@cindex __thread + +Thread-local storage (@acronym{TLS}) is a mechanism by which variables +are allocated such that there is one instance of the variable per extant +thread. The run-time model GCC uses to implement this originates +in the IA-64 processor-specific ABI, but has since been migrated +to other processors as well. It requires significant support from +the linker (@command{ld}), dynamic linker (@command{ld.so}), and +system libraries (@file{libc.so} and @file{libpthread.so}), so it +is not available everywhere. + +At the user level, the extension is visible with a new storage +class keyword: @code{__thread}. For example: + +@example +__thread int i; +extern __thread struct state s; +static __thread char *p; +@end example + +The @code{__thread} specifier may be used alone, with the @code{extern} +or @code{static} specifiers, but with no other storage class specifier. +When used with @code{extern} or @code{static}, @code{__thread} must appear +immediately after the other storage class specifier. + +The @code{__thread} specifier may be applied to any global, file-scoped +static, function-scoped static, or static data member of a class. It may +not be applied to block-scoped automatic or non-static data member. + +When the address-of operator is applied to a thread-local variable, it is +evaluated at run-time and returns the address of the current thread's +instance of that variable. An address so obtained may be used by any +thread. When a thread terminates, any pointers to thread-local variables +in that thread become invalid. + +No static initialization may refer to the address of a thread-local variable. + +In C++, if an initializer is present for a thread-local variable, it must +be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ +standard. + +See @uref{http://people.redhat.com/drepper/tls.pdf, +ELF Handling For Thread-Local Storage} for a detailed explanation of +the four thread-local storage addressing models, and how the run-time +is expected to function. + +@menu +* C99 Thread-Local Edits:: +* C++98 Thread-Local Edits:: +@end menu + +@node C99 Thread-Local Edits +@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage + +The following are a set of changes to ISO/IEC 9899:1999 (aka C99) +that document the exact semantics of the language extension. + +@itemize @bullet +@item +@cite{5.1.2 Execution environments} + +Add new text after paragraph 1 + +@quotation +Within either execution environment, a @dfn{thread} is a flow of +control within a program. It is implementation defined whether +or not there may be more than one thread associated with a program. +It is implementation defined how threads beyond the first are +created, the name and type of the function called at thread +startup, and how threads may be terminated. However, objects +with thread storage duration shall be initialized before thread +startup. +@end quotation + +@item +@cite{6.2.4 Storage durations of objects} + +Add new text before paragraph 3 + +@quotation +An object whose identifier is declared with the storage-class +specifier @w{@code{__thread}} has @dfn{thread storage duration}. +Its lifetime is the entire execution of the thread, and its +stored value is initialized only once, prior to thread startup. +@end quotation + +@item +@cite{6.4.1 Keywords} + +Add @code{__thread}. + +@item +@cite{6.7.1 Storage-class specifiers} + +Add @code{__thread} to the list of storage class specifiers in +paragraph 1. + +Change paragraph 2 to + +@quotation +With the exception of @code{__thread}, at most one storage-class +specifier may be given [@dots{}]. The @code{__thread} specifier may +be used alone, or immediately following @code{extern} or +@code{static}. +@end quotation + +Add new text after paragraph 6 + +@quotation +The declaration of an identifier for a variable that has +block scope that specifies @code{__thread} shall also +specify either @code{extern} or @code{static}. + +The @code{__thread} specifier shall be used only with +variables. +@end quotation +@end itemize + +@node C++98 Thread-Local Edits +@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage + +The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) +that document the exact semantics of the language extension. + +@itemize @bullet +@b{[intro.execution]} + +New text after paragraph 4 + +@quotation +A @dfn{thread} is a flow of control within the abstract machine. +It is implementation defined whether or not there may be more than +one thread. +@end quotation + +New text after paragraph 7 + +@quotation +It is unspecified whether additional action must be taken to +ensure when and whether side effects are visible to other threads. +@end quotation + +@item +@b{[lex.key]} + +Add @code{__thread}. + +@item +@b{[basic.start.main]} + +Add after paragraph 5 + +@quotation +The thread that begins execution at the @code{main} function is called +the @dfn{main thread}. It is implementation defined how functions +beginning threads other than the main thread are designated or typed. +A function so designated, as well as the @code{main} function, is called +a @dfn{thread startup function}. It is implementation defined what +happens if a thread startup function returns. It is implementation +defined what happens to other threads when any thread calls @code{exit}. +@end quotation + +@item +@b{[basic.start.init]} + +Add after paragraph 4 + +@quotation +The storage for an object of thread storage duration shall be +statically initialized before the first statement of the thread startup +function. An object of thread storage duration shall not require +dynamic initialization. +@end quotation + +@item +@b{[basic.start.term]} + +Add after paragraph 3 + +@quotation +The type of an object with thread storage duration shall not have a +non-trivial destructor, nor shall it be an array type whose elements +(directly or indirectly) have non-trivial destructors. +@end quotation + +@item +@b{[basic.stc]} + +Add ``thread storage duration'' to the list in paragraph 1. + +Change paragraph 2 + +@quotation +Thread, static, and automatic storage durations are associated with +objects introduced by declarations [@dots{}]. +@end quotation + +Add @code{__thread} to the list of specifiers in paragraph 3. + +@item +@b{[basic.stc.thread]} + +New section before @b{[basic.stc.static]} + +@quotation +The keyword @code{__thread} applied to a non-local object gives the +object thread storage duration. + +A local variable or class data member declared both @code{static} +and @code{__thread} gives the variable or member thread storage +duration. +@end quotation + +@item +@b{[basic.stc.static]} + +Change paragraph 1 + +@quotation +All objects which have neither thread storage duration, dynamic +storage duration nor are local [@dots{}]. +@end quotation + +@item +@b{[dcl.stc]} + +Add @code{__thread} to the list in paragraph 1. + +Change paragraph 1 + +@quotation +With the exception of @code{__thread}, at most one +@var{storage-class-specifier} shall appear in a given +@var{decl-specifier-seq}. The @code{__thread} specifier may +be used alone, or immediately following the @code{extern} or +@code{static} specifiers. [@dots{}] +@end quotation + +Add after paragraph 5 + +@quotation +The @code{__thread} specifier can be applied only to the names of objects +and to anonymous unions. +@end quotation + +@item +@b{[class.mem]} + +Add after paragraph 6 + +@quotation +Non-@code{static} members shall not be @code{__thread}. +@end quotation +@end itemize + @node C++ Extensions @chapter Extensions to the C++ Language @cindex extensions, C++ language @@ -6290,7 +7016,7 @@ context. @example void fn (int *__restrict__ rptr, int &__restrict__ rref) @{ - @dots{} + /* @r{@dots{}} */ @} @end example @@ -6304,7 +7030,7 @@ unaliased by using @code{__restrict__} as a member function qualifier. @example void T::fn () __restrict__ @{ - @dots{} + /* @r{@dots{}} */ @} @end example @@ -6515,7 +7241,6 @@ If any calls were not inlined, you will get linker errors. @node Template Instantiation @section Where's the Template? - @cindex template instantiation C++ templates are the first language feature to require more @@ -6634,8 +7359,8 @@ compile it without @option{-fno-implicit-templates} so you get all of the instances required by your explicit instantiations (but not by any other files) without having to specify them as well. -g++ has extended the template instantiation syntax outlined in the -Working Paper to allow forward declaration of explicit instantiations +g++ has extended the template instantiation syntax given in the ISO +standard to allow forward declaration of explicit instantiations (with @code{extern}), instantiation of the compiler support data for a template class (i.e.@: the vtable) without instantiating any of its members (with @code{inline}), and instantiation of only the static data @@ -6655,48 +7380,12 @@ each translation unit will contain instances of each of the templates it uses. In a large program, this can lead to an unacceptable amount of code duplication. -@item -@opindex fexternal-templates -Add @samp{#pragma interface} to all files containing template -definitions. For each of these files, add @samp{#pragma implementation -"@var{filename}"} to the top of some @samp{.C} file which -@samp{#include}s it. Then compile everything with -@option{-fexternal-templates}. The templates will then only be expanded -in the translation unit which implements them (i.e.@: has a @samp{#pragma -implementation} line for the file where they live); all other files will -use external references. If you're lucky, everything should work -properly. If you get undefined symbol errors, you need to make sure -that each template instance which is used in the program is used in the -file which implements that template. If you don't have any use for a -particular instance in that file, you can just instantiate it -explicitly, using the syntax from the latest C++ working paper: - -@example -template class A<int>; -template ostream& operator << (ostream&, const A<int>&); -@end example - -This strategy will work with code written for either model. If you are -using code written for the Cfront model, the file containing a class -template and the file containing its member templates should be -implemented in the same translation unit. - -@item -@opindex falt-external-templates -A slight variation on this approach is to use the flag -@option{-falt-external-templates} instead. This flag causes template -instances to be emitted in the translation unit that implements the -header where they are first instantiated, rather than the one which -implements the file where the templates are defined. This header must -be the same in all translation units, or things are likely to break. - @xref{C++ Interface,,Declarations and Definitions in One Header}, for more discussion of these pragmas. @end enumerate @node Bound member functions @section Extracting the function pointer from a bound pointer to member function - @cindex pmf @cindex pointer to member function @cindex bound pointer to member function @@ -6853,7 +7542,7 @@ Floating and complex non-type template parameters have been deprecated, and are now removed from g++. The implicit typename extension has been deprecated and will be removed -from g++ at some point. In some cases g++ determines that a dependant +from g++ at some point. In some cases g++ determines that a dependent type such as @code{TPL<T>::X} is a type without needing a @code{typename} keyword, contrary to the standard. diff --git a/contrib/gcc/doc/frontends.texi b/contrib/gcc/doc/frontends.texi index a5efb63..1ee5685 100644 --- a/contrib/gcc/doc/frontends.texi +++ b/contrib/gcc/doc/frontends.texi @@ -4,16 +4,17 @@ @c For copying conditions, see the file gcc.texi. @node G++ and GCC -@chapter Compile C, C++, Objective-C, Ada, Fortran, or Java +@chapter Compile C, C++, Objective-C, Ada, Fortran, Java, or treelang @cindex Objective-C @cindex Fortran @cindex Java @cindex Ada +@cindex treelang Several versions of the compiler (C, C++, Objective-C, Ada, -Fortran, and Java) are integrated; this is why we use the name +Fortran, Java and treelang) are integrated; this is why we use the name ``GNU Compiler Collection''. GCC can compile programs written in any of these -languages. The Ada, Fortran, and Java compilers are described in +languages. The Ada, Fortran, Java and treelang compilers are described in separate manuals. @cindex GCC diff --git a/contrib/gcc/doc/gcc.texi b/contrib/gcc/doc/gcc.texi index 631d56c..721150a 100644 --- a/contrib/gcc/doc/gcc.texi +++ b/contrib/gcc/doc/gcc.texi @@ -60,25 +60,12 @@ \global\setfont\defbf\ttbshape{10}{\magstep1} @end tex -@macro copyrightnotice +@copying Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002 Free Software Foundation, Inc. -@end macro -@ifnottex -@dircategory Programming -@direntry -* gcc: (gcc). The GNU Compiler Collection. -@end direntry -This file documents the use of the GNU compilers. -@sp 1 -Published by the Free Software Foundation@* -59 Temple Place - Suite 330@* -Boston, MA 02111-1307 USA -@sp 1 -@copyrightnotice{} -@sp 1 +1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. + Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License'' and ``Funding Free Software'', the Front-Cover texts being (a) (see below), and with @@ -94,6 +81,20 @@ included in the section entitled ``GNU Free Documentation License''. You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development. +@end copying +@ifnottex +@dircategory Programming +@direntry +* gcc: (gcc). The GNU Compiler Collection. +@end direntry +This file documents the use of the GNU compilers. +@sp 1 +Published by the Free Software Foundation@* +59 Temple Place - Suite 330@* +Boston, MA 02111-1307 USA +@sp 1 +@insertcopying +@sp 1 @end ifnottex @setchapternewpage odd @@ -102,14 +103,12 @@ included in the section entitled ``GNU Free Documentation License''. @sp 2 @center Richard M. Stallman @sp 3 -@center Last updated 20 April 2002 +@center Last updated 30 December 2002 @sp 1 @center for GCC @value{version-GCC} @page @vskip 0pt plus 1filll -@copyrightnotice{} -@sp 2 For GCC Version @value{version-GCC}@* @sp 1 Published by the Free Software Foundation @* @@ -122,23 +121,7 @@ Printed copies are available for $50 each.@* ISBN 1-882114-37-X @end ifset @sp 1 -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License'', the Front-Cover -texts being (a) (see below), and with the Back-Cover Texts being (b) -(see below). A copy of the license is included in the section entitled -``GNU Free Documentation License''. - -(a) The FSF's Front-Cover Text is: - - A GNU Manual - -(b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU - software. Copies published by the Free Software Foundation raise - funds for GNU development. +@insertcopying @end titlepage @summarycontents @contents @@ -170,7 +153,6 @@ Introduction, gccint, GNU Compiler Collection (GCC) Internals}. * Bugs:: How, why and where to report bugs. * Service:: How to find suppliers of support for GCC. * Contributing:: How to contribute to testing and developing GCC. -* VMS:: Using GCC on VMS. * Funding:: How to help assure funding for free software. * GNU Project:: The GNU Project and GNU/Linux. @@ -181,7 +163,7 @@ Introduction, gccint, GNU Compiler Collection (GCC) Internals}. * Contributors:: People who have contributed to GCC. * Option Index:: Index to command line options. -* Index:: Index of concepts and symbol names. +* Keyword Index:: Index of concepts and symbol names. @end menu @include frontends.texi @@ -195,7 +177,6 @@ Introduction, gccint, GNU Compiler Collection (GCC) Internals}. @include bugreport.texi @include service.texi @include contribute.texi -@include vms.texi @include funding.texi @include gnu.texi @@ -224,8 +205,8 @@ form; it may sometimes be useful to look up both forms. @printindex op -@node Index -@unnumbered Index +@node Keyword Index +@unnumbered Keyword Index @printindex cp diff --git a/contrib/gcc/doc/gccint.texi b/contrib/gcc/doc/gccint.texi index 82a7d31..b6bec09 100644 --- a/contrib/gcc/doc/gccint.texi +++ b/contrib/gcc/doc/gccint.texi @@ -46,25 +46,12 @@ \global\setfont\defbf\ttbshape{10}{\magstep1} @end tex -@macro copyrightnotice +@copying Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002 Free Software Foundation, Inc. -@end macro -@ifnottex -@dircategory Programming -@direntry -* gccint: (gccint). Internals of the GNU Compiler Collection. -@end direntry -This file documents the internals of the GNU compilers. -@sp 1 -Published by the Free Software Foundation@* -59 Temple Place - Suite 330@* -Boston, MA 02111-1307 USA -@sp 1 -@copyrightnotice{} -@sp 1 +1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. + Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License'' and ``Funding Free Software'', the Front-Cover texts being (a) (see below), and with @@ -80,6 +67,19 @@ included in the section entitled ``GNU Free Documentation License''. You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development. +@end copying +@ifnottex +@dircategory Programming +@direntry +* gccint: (gccint). Internals of the GNU Compiler Collection. +@end direntry +This file documents the internals of the GNU compilers. +@sp 1 +Published by the Free Software Foundation@* +59 Temple Place - Suite 330@* +Boston, MA 02111-1307 USA +@sp 1 +@insertcopying @end ifnottex @setchapternewpage odd @@ -88,14 +88,12 @@ included in the section entitled ``GNU Free Documentation License''. @sp 2 @center Richard M. Stallman @sp 3 -@center Last updated 10 January 2002 +@center Last updated 28 December 2002 @sp 1 @center for GCC @value{version-GCC} @page @vskip 0pt plus 1filll -@copyrightnotice{} -@sp 2 For GCC Version @value{version-GCC}@* @sp 1 Published by the Free Software Foundation @* @@ -108,23 +106,7 @@ Printed copies are available for $50 each.@* ISBN 1-882114-37-X @end ifset @sp 1 -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License'', the Front-Cover -texts being (a) (see below), and with the Back-Cover Texts being (b) -(see below). A copy of the license is included in the section entitled -``GNU Free Documentation License''. - -(a) The FSF's Front-Cover Text is: - - A GNU Manual - -(b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU - software. Copies published by the Free Software Foundation raise - funds for GNU development. +@insertcopying @end titlepage @summarycontents @contents @@ -169,6 +151,7 @@ Additional tutorial information is linked to from * Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files. * Collect2:: How @code{collect2} works; how it finds @code{ld}. * Header Dirs:: Understanding the standard header file directories. +* Type Information:: GCC's memory management; generating type information. * Funding:: How to help assure funding for free software. * GNU Project:: The GNU Project and GNU/Linux. @@ -196,6 +179,7 @@ Additional tutorial information is linked to from @include fragments.texi @include collect2.texi @include headerdirs.texi +@include gty.texi @include funding.texi @include gnu.texi diff --git a/contrib/gcc/doc/gcov.texi b/contrib/gcc/doc/gcov.texi index 78e6667..85d5289 100644 --- a/contrib/gcc/doc/gcov.texi +++ b/contrib/gcc/doc/gcov.texi @@ -1,13 +1,15 @@ -@c Copyright (C) 1996, 1997, 1999, 2000, 2001 Free Software Foundation, Inc. +@c Copyright (C) 1996, 1997, 1999, 2000, 2001, +@c 2002, 2003 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @ignore @c man begin COPYRIGHT -Copyright @copyright{} 1996, 1997, 1999, 2000, 2001 Free Software Foundation, Inc. +Copyright @copyright{} 1996, 1997, 1999, 2000, 2001, 2002, 2003 +Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License'' and ``Funding Free Software'', the Front-Cover texts being (a) (see below), and with @@ -47,12 +49,13 @@ test code coverage in your programs. @c man begin DESCRIPTION @command{gcov} is a test coverage program. Use it in concert with GCC -to analyze your programs to help create more efficient, faster -running code. You can use @command{gcov} as a profiling tool to help -discover where your optimization efforts will best affect your code. You -can also use @command{gcov} along with the other profiling tool, -@command{gprof}, to assess which parts of your code use the greatest amount -of computing time. +to analyze your programs to help create more efficient, faster running +code and to discover untested parts of your program. You can use +@command{gcov} as a profiling tool to help discover where your +optimization efforts will best affect your code. You can also use +@command{gcov} along with the other profiling tool, @command{gprof}, to +assess which parts of your code use the greatest amount of computing +time. Profiling tools help you analyze your code's performance. Using a profiler such as @command{gcov} or @command{gprof}, you can find out some @@ -117,10 +120,13 @@ gcov @r{[}@var{options}@r{]} @var{sourcefile} @ignore @c man begin SYNOPSIS gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] - [@option{-b}|@option{--branch-probabilities}] [@option{-c}|@option{--branch-counts}] - [@option{-n}|@option{--no-output}] [@option{-l}|@option{--long-file-names}] + [@option{-b}|@option{--branch-probabilities}] + [@option{-c}|@option{--branch-counts}] + [@option{-n}|@option{--no-output}] + [@option{-l}|@option{--long-file-names}] + [@option{-p}|@option{--preserve-paths}] [@option{-f}|@option{--function-summaries}] - [@option{-o}|@option{--object-directory} @var{directory}] @var{sourcefile} + [@option{-o}|@option{--object-directory} @var{directory|file}] @var{sourcefile} @c man end @c man begin SEEALSO gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}. @@ -159,31 +165,71 @@ Do not create the @command{gcov} output file. Create long file names for included source files. For example, if the header file @file{x.h} contains code, and was included in the file @file{a.c}, then running @command{gcov} on the file @file{a.c} will produce -an output file called @file{a.c.x.h.gcov} instead of @file{x.h.gcov}. +an output file called @file{a.c##x.h.gcov} instead of @file{x.h.gcov}. This can be useful if @file{x.h} is included in multiple source files. +@item -p +@itemx --preserve-paths +Preserve complete path information in the names of generated +@file{.gcov} files. Without this option, just the filename component is +used. With this option, all directories are used, with '/' characters +translated to '#' characters, '.' directory components removed and '..' +components renamed to '^'. This is useful if sourcefiles are in several +different directories. It also affects the @samp{-l} option. + @item -f @itemx --function-summaries Output summaries for each function in addition to the file level summary. -@item -o @var{directory} +@item -o @var{directory|file} @itemx --object-directory @var{directory} -The directory where the object files live. Gcov will search for @file{.bb}, -@file{.bbg}, and @file{.da} files in this directory. +@itemx --object-file @var{file} +Specify either the directory containing the gcov data files, or the +object path name. The @file{.bb}, @file{.bbg}, and +@file{.da} data files are searched for using this option. If a directory +is specified, the data files are in that directory and named after the +source file name, without its extension. If a file is specified here, +the data files are named after that file, without its extension. If this +option is not supplied, it defaults to the current directory. + @end table -@need 3000 +@command{gcov} should be run with the current directory the same as that +when you invoked the compiler. Otherwise it will not be able to locate +the source files. @command{gcov} produces files called +@file{@var{mangledname}.gcov} in the current directory. These contain +the coverage information of the source file they correspond to. +One @file{.gcov} file is produced for each source file containing code, +which was compiled to produce the data files. The @file{.gcov} files +contain the ':' separated fields along with program source code. The +format is + +@smallexample +@var{execution_count}:@var{line_number}:@var{source line text} +@end smallexample + +Additional block information may succeed each line, when requested by +command line option. The @var{execution_count} is @samp{-} for lines +containing no code and @samp{#####} for lines which were never +executed. Some lines of information at the start have @var{line_number} +of zero. + +When printing percentages, 0% and 100% are only printed when the values +are @emph{exactly} 0% and 100% respectively. Other values which would +conventionally be rounded to 0% or 100% are instead printed as the +nearest non-boundary value. + When using @command{gcov}, you must first compile your program with two special GCC options: @samp{-fprofile-arcs -ftest-coverage}. This tells the compiler to generate additional information needed by gcov (basically a flow graph of the program) and also includes additional code in the object files for generating the extra profiling information needed by gcov. These additional files are placed in the -directory where the source code is located. +directory where the object file is located. Running the program will cause profile output to be generated. For each source file compiled with @option{-fprofile-arcs}, an accompanying @file{.da} -file will be placed in the source directory. +file will be placed in the object file directory. Running @command{gcov} with your program's source file names as arguments will now produce a listing of the code along with frequency of execution @@ -194,7 +240,7 @@ is what you see when you use the basic @command{gcov} facility: $ gcc -fprofile-arcs -ftest-coverage tmp.c $ a.out $ gcov tmp.c - 87.50% of 8 source lines executed in file tmp.c +90.00% of 10 source lines executed in file tmp.c Creating tmp.c.gcov. @end smallexample @@ -202,20 +248,25 @@ The file @file{tmp.c.gcov} contains output from @command{gcov}. Here is a sample: @smallexample - main() - @{ - 1 int i, total; - - 1 total = 0; - - 11 for (i = 0; i < 10; i++) - 10 total += i; - - 1 if (total != 45) - ###### printf ("Failure\n"); - else - 1 printf ("Success\n"); - 1 @} + -: 0:Source:tmp.c + -: 0:Object:tmp.bb + -: 1:#include <stdio.h> + -: 2: + -: 3:int main (void) + 1: 4:@{ + 1: 5: int i, total; + -: 6: + 1: 7: total = 0; + -: 8: + 11: 9: for (i = 0; i < 10; i++) + 10: 10: total += i; + -: 11: + 1: 12: if (total != 45) + #####: 13: printf ("Failure\n"); + -: 14: else + 1: 15: printf ("Success\n"); + 1: 16: return 0; + 1: 17:@} @end smallexample @need 450 @@ -223,37 +274,42 @@ When you use the @option{-b} option, your output looks like this: @smallexample $ gcov -b tmp.c - 87.50% of 8 source lines executed in file tmp.c - 80.00% of 5 branches executed in file tmp.c - 80.00% of 5 branches taken at least once in file tmp.c - 50.00% of 2 calls executed in file tmp.c +90.00% of 10 source lines executed in file tmp.c +80.00% of 5 branches executed in file tmp.c +80.00% of 5 branches taken at least once in file tmp.c +50.00% of 2 calls executed in file tmp.c Creating tmp.c.gcov. @end smallexample Here is a sample of a resulting @file{tmp.c.gcov} file: @smallexample - main() - @{ - 1 int i, total; - - 1 total = 0; - - 11 for (i = 0; i < 10; i++) -branch 0 taken = 91% -branch 1 taken = 100% -branch 2 taken = 100% - 10 total += i; - - 1 if (total != 45) -branch 0 taken = 100% - ###### printf ("Failure\n"); -call 0 never executed -branch 1 never executed - else - 1 printf ("Success\n"); -call 0 returns = 100% - 1 @} + -: 0:Source:tmp.c + -: 0:Object:tmp.bb + -: 1:#include <stdio.h> + -: 2: + -: 3:int main (void) + 1: 4:@{ + 1: 5: int i, total; + -: 6: + 1: 7: total = 0; + -: 8: + 11: 9: for (i = 0; i < 10; i++) +branch 0: taken 90% +branch 1: taken 100% +branch 2: taken 100% + 10: 10: total += i; + -: 11: + 1: 12: if (total != 45) +branch 0: taken 100% + #####: 13: printf ("Failure\n"); +call 0: never executed +branch 1: never executed + -: 14: else + 1: 15: printf ("Success\n"); +call 0: returns 100% + 1: 16: return 0; + 1: 17:@} @end smallexample For each basic block, a line is printed after the last line of the basic @@ -286,11 +342,11 @@ provide more accurate long-term information over a large number of program runs. The data in the @file{.da} files is saved immediately before the program -exits. For each source file compiled with @option{-fprofile-arcs}, the profiling -code first attempts to read in an existing @file{.da} file; if the file -doesn't match the executable (differing number of basic block counts) it -will ignore the contents of the file. It then adds in the new execution -counts and finally writes the data to the file. +exits. For each source file compiled with @option{-fprofile-arcs}, the +profiling code first attempts to read in an existing @file{.da} file; if +the file doesn't match the executable (differing number of basic block +counts) it will ignore the contents of the file. It then adds in the +new execution counts and finally writes the data to the file. @node Gcov and Optimization @section Using @command{gcov} with GCC Optimization @@ -319,10 +375,10 @@ the @command{gcov} output looks like this if you compiled the program with optimization: @smallexample - 100 if (a != b) - 100 c = 1; - 100 else - 100 c = 0; + 100: 12:if (a != b) + 100: 13: c = 1; + 100: 14:else + 100: 15: c = 0; @end smallexample The output shows that this block of code, combined by optimization, @@ -348,12 +404,13 @@ functions within those files, and line numbers corresponding to each basic block in the source file. The @file{.bb} file format consists of several lists of 4-byte integers -which correspond to the line numbers of each basic block in the -file. Each list is terminated by a line number of 0. A line number of @minus{}1 -is used to designate that the source file name (padded to a 4-byte -boundary and followed by another @minus{}1) follows. In addition, a line number -of @minus{}2 is used to designate that the name of a function (also padded to a -4-byte boundary and followed by a @minus{}2) follows. +which correspond to the line numbers of each basic block in the file. +Each list is terminated by a line number of 0. A line number of +@minus{}1 is used to designate that the source file name (padded to a +4-byte boundary and followed by another @minus{}1) follows. In +addition, a line number of @minus{}2 is used to designate that the name +of a function (also padded to a 4-byte boundary and followed by a +@minus{}2) follows. The @file{.bbg} file is used to reconstruct the program flow graph for the source file. It contains a list of the program flow arcs (possible @@ -363,6 +420,8 @@ program flow. In the @file{.bbg} file, the format is: @smallexample + name of function #0 + checksum of function #0 number of basic blocks for function #0 (4-byte number) total number of arcs for function #0 (4-byte number) count of arcs in basic block #0 (4-byte number) @@ -383,22 +442,61 @@ A @minus{}1 (stored as a 4-byte number) is used to separate each function's list of basic blocks, and to verify that the file has been read correctly. +The function name is stored as a @minus{}1 (4 bytes), the length (4 bytes), +the name itself (padded to 4-byte boundary) followed by a @minus{}1 (4 bytes). + +The flags are defined as follows: +@itemize +@item bit0 +On function spanning tree + +@item bit1 +Is a fake edge + +@item bit2 +Is the fall through edge from one block to its immediate successor. + +@item bit3-bit31 +For future expansion + +@end itemize + The @file{.da} file is generated when a program containing object files built with the GCC @option{-fprofile-arcs} option is executed. A separate @file{.da} file is created for each source file compiled with this option, and the name of the @file{.da} file is stored as an absolute pathname in the resulting object file. This path name is -derived from the source file name by substituting a @file{.da} suffix. - -The format of the @file{.da} file is fairly simple. The first 8-byte -number is the number of counts in the file, followed by the counts -(stored as 8-byte numbers). Each count corresponds to the number of -times each arc in the program is executed. The counts are cumulative; -each time the program is executed, it attempts to combine the existing -@file{.da} files with the new counts for this invocation of the -program. It ignores the contents of any @file{.da} files whose number of -arcs doesn't correspond to the current program, and merely overwrites -them instead. +derived from the object file name by substituting a @file{.da} suffix. + +The @file{.da} consists of one or more blocks with the following +structure: +@smallexample + "magic" number @minus{}123 (4-byte number) + number of functions (4-byte number) + length of the "extension block" in bytes + extension block (variable length) + name of function #0 (the same format as in .bbg file) + checksum of function #0 + number of instrumented arcs (4-byte number) + count of arc #0 (8-byte number) + count of arc #1 (8-byte number) + @dots{} + count of arc #M_0 (8-byte number) + name of function #1 (the same format as in .bbg file) + checksum of function #1 + @dots{} +@end smallexample +Multiple program runs might merge data into a single block, or might +append a new block. The current structure of the extension block is as +follows: +@smallexample + number of instrumented arcs in whole program (4-byte number) + sum all of instrumented arcs in whole program (8-byte number) + maximal value of counter in whole program (8-byte number) + number of instrumented arcs in the object file (4-byte number) + sum all of instrumented arcs in the object file (8-byte number) + maximal value of counter in the object file (8-byte number) +@end smallexample All three of these files use the functions in @file{gcov-io.h} to store integers; the functions in this header provide a machine-independent diff --git a/contrib/gcc/doc/gty.texi b/contrib/gcc/doc/gty.texi new file mode 100644 index 0000000..31d5252 --- /dev/null +++ b/contrib/gcc/doc/gty.texi @@ -0,0 +1,328 @@ +@c Copyright (C) 2002, 2003 +@c Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Type Information +@chapter Memory Management and Type Information +@cindex GGC +@findex GTY + +GCC uses some fairly sophisticated memory management techniques, which +involve determining information about GCC's data structures from GCC's +source code and using this information to perform garbage collection. + +A full C parser would be too overcomplicated for this task, so a limited +subset of C is interpreted and special markers are used to determine +what parts of the source to look at. The parser can also detect +simple typedefs of the form @code{typedef struct ID1 *ID2;} and +@code{typedef int ID3;}, and these don't need to be specially marked. + +The two forms that do need to be marked are: +@verbatim +struct ID1 GTY(([options])) +{ + [fields] +}; + +typedef struct ID2 GTY(([options])) +{ + [fields] +} ID3; +@end verbatim + +@menu +* GTY Options:: What goes inside a @code{GTY(())}. +* GGC Roots:: Making global variables GGC roots. +* Files:: How the generated files work. +@end menu + +@node GTY Options +@section The Inside of a @code{GTY(())} + +Sometimes the C code is not enough to fully describe the type structure. +Extra information can be provided by using more @code{GTY} markers. +These markers can be placed: +@itemize @bullet +@item +In a structure definition, before the open brace; +@item +In a global variable declaration, after the keyword @code{static} or +@code{extern}; and +@item +In a structure field definition, before the name of the field. +@end itemize + +The format of a marker is +@verbatim +GTY (([name] ([param]), [name] ([param]) ...)) +@end verbatim +The parameter is either a string or a type name. + +When the parameter is a string, often it is a fragment of C code. Three +special escapes may be available: + +@cindex % in GTY option +@table @code +@item %h +This expands to an expression that evaluates to the current structure. +@item %1 +This expands to an expression that evaluates to the structure that +immediately contains the current structure. +@item %0 +This expands to an expression that evaluates to the outermost structure +that contains the current structure. +@item %a +This expands to the string of the form @code{[i1][i2]...} that indexes +the array item currently being marked. For instance, if the field +being marked is @code{foo}, then @code{%1.foo%a} is the same as @code{%h}. +@end table + +The available options are: + +@table @code +@findex length +@item length + +There are two places the type machinery will need to be explicitly told +the length of an array. The first case is when a structure ends in a +variable-length array, like this: +@verbatim +struct rtvec_def GTY(()) { + int num_elem; /* number of elements */ + rtx GTY ((length ("%h.num_elem"))) elem[1]; +}; +@end verbatim +In this case, the @code{length} option is used to override the specified +array length (which should usually be @code{1}). The parameter of the +option is a fragment of C code that calculates the length. + +The second case is when a structure or a global variable contains a +pointer to an array, like this: +@smallexample +tree * + GTY ((length ("%h.regno_pointer_align_length"))) regno_decl; +@end smallexample +In this case, @code{regno_decl} has been allocated by writing something like +@smallexample + x->regno_decl = + ggc_alloc (x->regno_pointer_align_length * sizeof (tree)); +@end smallexample +and the @code{length} provides the length of the field. + +This second use of @code{length} also works on global variables, like: +@verbatim + static GTY((length ("reg_base_value_size"))) + rtx *reg_base_value; +@end verbatim + +@findex skip +@item skip + +If @code{skip} is applied to a field, the type machinery will ignore it. +This is somewhat dangerous; the only safe use is in a union when one +field really isn't ever used. + +@findex desc +@findex tag +@findex default +@item desc +@itemx tag +@itemx default + +The type machinery needs to be told which field of a @code{union} is +currently active. This is done by giving each field a constant @code{tag} +value, and then specifying a discriminator using @code{desc}. For example, +@smallexample +struct tree_binding GTY(()) +@{ + struct tree_common common; + union tree_binding_u @{ + tree GTY ((tag ("0"))) scope; + struct cp_binding_level * GTY ((tag ("1"))) level; + @} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) scope; + tree value; +@}; +@end smallexample + +In the @code{desc} option, the ``current structure'' is the union that +it discriminates. Use @code{%1} to mean the structure containing it. +(There are no escapes available to the @code{tag} option, since it's +supposed to be a constant.) + +Each @code{tag} should be different. If no @code{tag} is matched, +the field marked with @code{default} is used if there is one, otherwise +no field in the union will be marked. + +@findex param_is +@findex use_param +@item param_is +@itemx use_param + +Sometimes it's convenient to define some data structure to work on +generic pointers (that is, @code{PTR}) and then use it with a specific +type. @code{param_is} specifies the real type pointed to, and +@code{use_param} says where in the generic data structure that type +should be put. + +For instance, to have a @code{htab_t} that points to trees, one should write +@verbatim + htab_t GTY ((param_is (union tree_node))) ict; +@end verbatim + +@findex param@var{n}_is +@findex use_param@var{n} +@item param@var{n}_is +@itemx use_param@var{n} + +In more complicated cases, the data structure might need to work on +several different types, which might not necessarily all be pointers. +For this, @code{param1_is} through @code{param9_is} may be used to +specify the real type of a field identified by @code{use_param1} through +@code{use_param9}. + +@findex use_params +@item use_params + +When a structure contains another structure that is parameterized, +there's no need to do anything special, the inner structure inherits the +parameters of the outer one. When a structure contains a pointer to a +parameterized structure, the type machinery won't automatically detect +this (it could, it just doesn't yet), so it's necessary to tell it that +the pointed-to structure should use the same parameters as the outer +structure. This is done by marking the pointer with the +@code{use_params} option. + +@findex deletable +@item deletable + +@code{deletable}, when applied to a global variable, indicates that when +garbage collection runs, there's no need to mark anything pointed to +by this variable, it can just be set to @code{NULL} instead. This is used +to keep a list of free structures around for re-use. + +@findex if_marked +@item if_marked + +Suppose you want some kinds of object to be unique, and so you put them +in a hash table. If garbage collection marks the hash table, these +objects will never be freed, even if the last other reference to them +goes away. GGC has special handling to deal with this: if you use the +@code{if_marked} option on a global hash table, GGC will call the +routine whose name is the parameter to the option on each hash table +entry. If the routine returns nonzero, the hash table entry will +be marked as usual. If the routine returns zero, the hash table entry +will be deleted. + +The routine @code{ggc_marked_p} can be used to determine if an element +has been marked already; in fact, the usual case is to use +@code{if_marked ("ggc_marked_p")}. + +@findex maybe_undef +@item maybe_undef + +When applied to a field, @code{maybe_undef} indicates that it's OK if +the structure that this fields points to is never defined, so long as +this field is always @code{NULL}. This is used to avoid requiring +backends to define certain optional structures. It doesn't work with +language frontends. + +@findex special +@item special + +The @code{special} option is used for those bizarre cases that are just +too hard to deal with otherwise. Don't use it for new code. + +@end table + +@node GGC Roots +@section Marking Roots for the Garbage Collector +@cindex roots, marking +@cindex marking roots + +In addition to keeping track of types, the type machinery also locates +the global variables that the garbage collector starts at. There are +two syntaxes it accepts to indicate a root: + +@enumerate +@item +@verb{|extern GTY (([options])) [type] ID;|} +@item +@verb{|static GTY (([options])) [type] ID;|} +@end enumerate + +These are the only syntaxes that are accepted. In particular, if you +want to mark a variable that is only declared as +@verbatim +int ID; +@end verbatim +or similar, you should either make it @code{static} or you should create +a @code{extern} declaration in a header file somewhere. + +@node Files +@section Source Files Containing Type Information +@cindex generated files +@cindex files, generated + +Whenever you add @code{GTY} markers to a new source file, there are three +things you need to do: + +@enumerate +@item +You need to add the file to the list of source files the type +machinery scans. There are three cases: + +@enumerate a +@item +For a back-end file, this is usually done +automatically; if not, you should add it to @code{target_gtfiles} in +the appropriate port's entries in @file{config.gcc}. + +@item +For files shared by all front ends, this is done by adding the +filename to the @code{GTFILES} variable in @file{Makefile.in}. + +@item +For any other file used by a front end, this is done by adding the +filename to the @code{gtfiles} variable defined in +@file{config-lang.in}. For C, the file is @file{c-config-lang.in}. +This list should include all files that have GTY macros in them that +are used in that front end, other than those defined in the previous +list items. For example, it is common for front end writers to use +@file{c-common.c} and other files from the C front end, and these +should be included in the @file{gtfiles} variable for such front ends. + +@end enumerate + +@item +If the file was a header file, you'll need to check that it's included +in the right place to be visible to the generated files. For a back-end +header file, this should be done automatically. For a front-end header +file, it needs to be included by the same file that includes +@file{gtype-@var{lang}.h}. For other header files, it needs to be +included in @file{gtype-desc.c}, which is a generated file, so add it to +@code{ifiles} in @code{open_base_file} in @file{gengtype.c}. + +For source files that aren't header files, the machinery will generate a +header file that should be included in the source file you just changed. +The file will be called @file{gt-@var{path}.h} where @var{path} is the +pathname relative to the @file{gcc} directory with slashes replaced by +@verb{|-|}, so for example the header file to be included in +@file{objc/objc-parse.c} is called @file{gt-objc-objc-parse.c}. The +generated header file should be included after everything else in the +source file. Don't forget to mention this file as a dependency in the +@file{Makefile}! + +@item +If a new @file{gt-@var{path}.h} file is needed, you need to arrange to +add a @file{Makefile} rule that will ensure this file can be built. +This is done by making it a dependency of @code{s-gtype}, like this: +@verbatim +gt-path.h : s-gtype ; @true +@end verbatim +@end enumerate + +For language frontends, there is another file that needs to be included +somewhere. It will be called @file{gtype-@var{lang}.h}, where +@var{lang} is the name of the subdirectory the language is contained in. +It will need @file{Makefile} rules just like the other generated files. diff --git a/contrib/gcc/doc/headerdirs.texi b/contrib/gcc/doc/headerdirs.texi index 17db57f..beac0dd 100644 --- a/contrib/gcc/doc/headerdirs.texi +++ b/contrib/gcc/doc/headerdirs.texi @@ -15,7 +15,7 @@ are already suitable for ISO C and GNU CC, nothing special need be done). @code{GPLUSPLUS_INCLUDE_DIR} means the same thing for native and cross. It -is where @code{g++} looks first for header files. The C++ library +is where @command{g++} looks first for header files. The C++ library installs only target independent header files in that directory. @code{LOCAL_INCLUDE_DIR} is used only by native compilers. GNU CC diff --git a/contrib/gcc/doc/include/fdl.texi b/contrib/gcc/doc/include/fdl.texi index 1f3d8b652..2a4da78 100644 --- a/contrib/gcc/doc/include/fdl.texi +++ b/contrib/gcc/doc/include/fdl.texi @@ -33,10 +33,10 @@ of this license document, but changing it is not allowed. @end ifclear @cindex FDL, GNU Free Documentation License -@center Version 1.1, March 2000 +@center Version 1.2, November 2002 @display -Copyright @copyright{} 2000 Free Software Foundation, Inc. +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies @@ -48,12 +48,12 @@ of this license document, but changing it is not allowed. PREAMBLE The purpose of this License is to make a manual, textbook, or other -written document @dfn{free} in the sense of freedom: to assure everyone -the effective freedom to copy and redistribute it, with or without -modifying it, either commercially or noncommercially. Secondarily, -this License preserves for the author and publisher a way to get -credit for their work, while not being considered responsible for -modifications made by others. +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. This License is a kind of ``copyleft'', which means that derivative works of the document must themselves be free in the same sense. It @@ -71,57 +71,69 @@ principally for works whose purpose is instruction or reference. @item APPLICABILITY AND DEFINITIONS -This License applies to any manual or other work that contains a -notice placed by the copyright holder saying it can be distributed -under the terms of this License. The ``Document'', below, refers to any -such manual or work. Any member of the public is a licensee, and is -addressed as ``you''. +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. A ``Modified Version'' of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The ``Invariant Sections'' are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. The ``Cover Texts'' are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. A ``Transparent'' copy of the Document means a machine-readable copy, represented in a format whose specification is available to the -general public, whose contents can be viewed and edited directly and +general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file -format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not ``Transparent'' is called ``Opaque''. +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input format, -@acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed -for human modification. Opaque formats include PostScript, -@acronym{PDF}, proprietary formats that can be read and edited only by -proprietary word processors, @acronym{SGML} or @acronym{XML} for which -the @acronym{DTD} and/or processing tools are not generally available, -and the machine-generated @acronym{HTML} produced by some word -processors for output purposes only. +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. The ``Title Page'' means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material @@ -130,6 +142,21 @@ formats which do not have any title page as such, ``Title Page'' means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + @item VERBATIM COPYING @@ -149,9 +176,10 @@ you may publicly display copies. @item COPYING IN QUANTITY -If you publish printed copies of the Document numbering more than 100, -and the Document's license notice requires Cover Texts, you must enclose -the copies in covers that carry, clearly and legibly, all these Cover +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present @@ -169,16 +197,15 @@ pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy -a publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give @@ -206,7 +233,8 @@ if the original publisher of that version gives permission. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has less than five). +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. @item State on the Title page the name of the publisher of the @@ -232,10 +260,10 @@ and required Cover Texts given in the Document's license notice. Include an unaltered copy of this License. @item -Preserve the section entitled ``History'', and its title, and add to -it an item stating at least the title, year, new authors, and +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If -there is no section entitled ``History'' in the Document, create one +there is no section Entitled ``History'' in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. @@ -250,10 +278,10 @@ least four years before the Document itself, or if the original publisher of the version it refers to gives permission. @item -In any section entitled ``Acknowledgments'' or ``Dedications'', -preserve the section's title, and preserve in the section all the -substance and tone of each of the contributor acknowledgments -and/or dedications given therein. +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. @item Preserve all the Invariant Sections of the Document, @@ -261,12 +289,15 @@ unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. @item -Delete any section entitled ``Endorsements''. Such a section +Delete any section Entitled ``Endorsements''. Such a section may not be included in the Modified Version. @item -Do not retitle any existing section as ``Endorsements'' -or to conflict in title with any Invariant Section. +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. @end enumerate If the Modified Version includes new front-matter sections or @@ -276,7 +307,7 @@ of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. -You may add a section entitled ``Endorsements'', provided it contains +You may add a section Entitled ``Endorsements'', provided it contains nothing but endorsements of your Modified Version by various parties---for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a @@ -304,7 +335,7 @@ License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its -license notice. +license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single @@ -315,11 +346,11 @@ author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. -In the combination, you must combine any sections entitled ``History'' -in the various original documents, forming one section entitled -``History''; likewise combine any sections entitled ``Acknowledgments'', -and any sections entitled ``Dedications''. You must delete all sections -entitled ``Endorsements.'' +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' @item COLLECTIONS OF DOCUMENTS @@ -340,18 +371,20 @@ AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or -distribution medium, does not as a whole count as a Modified Version -of the Document, provided no compilation copyright is claimed for the -compilation. Such a compilation is called an ``aggregate'', and this -License does not apply to the other self-contained works thus compiled -with the Document, on account of their being thus compiled, if they -are not themselves derivative works of the Document. +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one quarter -of the entire aggregate, the Document's Cover Texts may be placed on -covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. @item TRANSLATION @@ -362,10 +395,17 @@ Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the -original English version of this License. In case of a disagreement -between the translation and the original English version of this -License, the original English version will prevail. +translation of this License, and all the license notices in the +Document, and any Warrany Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. @item TERMINATION @@ -408,19 +448,28 @@ license notices just after the title page: @group Copyright (C) @var{year} @var{your name}. Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 + under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; - with the Invariant Sections being @var{list their titles}, with the - Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. @end group @end smallexample -If you have no Invariant Sections, write ``with no Invariant Sections'' -instead of saying which ones are invariant. If you have no -Front-Cover Texts, write ``no Front-Cover Texts'' instead of -``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of diff --git a/contrib/gcc/doc/include/gcc-common.texi b/contrib/gcc/doc/include/gcc-common.texi index f489693..0a51d93 100644 --- a/contrib/gcc/doc/include/gcc-common.texi +++ b/contrib/gcc/doc/include/gcc-common.texi @@ -4,7 +4,12 @@ @c Common values used in the GCC manuals: -@set version-GCC 3.2.2 +@set version-GCC 3.3.1 + +@c DEVELOPMENT is set to indicate an in-development version, +@c as compared to a release version. When making a release +@c branch, clear this. +@clear DEVELOPMENT @c Common macros to support generating man pages: diff --git a/contrib/gcc/doc/include/gpl.texi b/contrib/gcc/doc/include/gpl.texi index 4304b72..eaff30c 100644 --- a/contrib/gcc/doc/include/gpl.texi +++ b/contrib/gcc/doc/include/gpl.texi @@ -7,7 +7,7 @@ gfdl(7), fsf-funding(7). @c man end @c man begin COPYRIGHT Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @@ -20,7 +20,7 @@ of this license document, but changing it is not allowed. @display Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @@ -365,9 +365,8 @@ 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., 59 Temple Place - Suite 330, -Boston, MA 02111-1307, USA. +along with this program; if not, write to the Free Software Foundation, +Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. @end smallexample Also add information on how to contact you by electronic and paper mail. diff --git a/contrib/gcc/doc/include/texinfo.tex b/contrib/gcc/doc/include/texinfo.tex index 99113dd..a8541dc 100644 --- a/contrib/gcc/doc/include/texinfo.tex +++ b/contrib/gcc/doc/include/texinfo.tex @@ -3,10 +3,10 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2002-03-01.06} +\def\texinfoversion{2002-12-26.16} % -% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, -% 2000, 01, 02 Free Software Foundation, Inc. +% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, +% 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. % % This texinfo.tex file is free software; you can redistribute it and/or % modify it under the terms of the GNU General Public License as @@ -29,19 +29,17 @@ % % Please try the latest version of texinfo.tex before submitting bug % reports; you can get the latest version from: -% ftp://ftp.gnu.org/gnu/texinfo.tex +% ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex % (and all GNU mirrors, see http://www.gnu.org/order/ftp.html) -% ftp://texinfo.org/texinfo/texinfo.tex % ftp://tug.org/tex/texinfo.tex % (and all CTAN mirrors, see http://www.ctan.org), % and /home/gd/gnu/doc/texinfo.tex on the GNU machines. % +% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. +% % The texinfo.tex in any given Texinfo distribution could well be out % of date, so if that's what you're using, please check. % -% Texinfo has a small home page at http://texinfo.org/ and also -% http://www.gnu.org/software/texinfo. -% % Send bug reports to bug-texinfo@gnu.org. Please include including a % complete document in each bug report with which we can reproduce the % problem. Patches are, of course, greatly appreciated. @@ -53,7 +51,7 @@ % texindex foo.?? % tex foo.texi % tex foo.texi -% dvips foo.dvi -o # or whatever, to process the dvi file; this makes foo.ps. +% dvips foo.dvi -o # or whatever; this makes foo.ps. % The extra TeX runs get the cross-reference information correct. % Sometimes one run after texindex suffices, and sometimes you need more % than two; texi2dvi does it as many times as necessary. @@ -69,6 +67,13 @@ \everyjob{\message{[Texinfo version \texinfoversion]}% \catcode`+=\active \catcode`\_=\active} +\message{Basics,} +\chardef\other=12 + +% We never want plain's outer \+ definition in Texinfo. +% For @tex, we can use \tabalign. +\let\+ = \relax + % Save some parts of plain tex whose names we will redefine. \let\ptexb=\b \let\ptexbullet=\bullet @@ -79,19 +84,16 @@ \let\ptexend=\end \let\ptexequiv=\equiv \let\ptexexclam=\! +\let\ptexgtr=> +\let\ptexhat=^ \let\ptexi=\i \let\ptexlbrace=\{ +\let\ptexless=< +\let\ptexplus=+ \let\ptexrbrace=\} \let\ptexstar=\* \let\ptext=\t -% We never want plain's outer \+ definition in Texinfo. -% For @tex, we can use \tabalign. -\let\+ = \relax - -\message{Basics,} -\chardef\other=12 - % If this character appears in an error message or help string, it % starts a new line in the output. \newlinechar = `^^J @@ -142,36 +144,48 @@ % \def\gobble#1{} +% True if #1 is the empty string, i.e., called like `\ifempty{}'. +% +\def\ifempty#1{\ifemptyx #1\emptymarkA\emptymarkB}% +\def\ifemptyx#1#2\emptymarkB{\ifx #1\emptymarkA}% + +% Hyphenation fixes. \hyphenation{ap-pen-dix} \hyphenation{mini-buf-fer mini-buf-fers} \hyphenation{eshell} \hyphenation{white-space} % Margin to add to right of even pages, to left of odd pages. -\newdimen \bindingoffset -\newdimen \normaloffset +\newdimen\bindingoffset +\newdimen\normaloffset \newdimen\pagewidth \newdimen\pageheight % Sometimes it is convenient to have everything in the transcript file % and nothing on the terminal. We don't just call \tracingall here, -% since that produces some useless output on the terminal. +% since that produces some useless output on the terminal. We also make +% some effort to order the tracing commands to reduce output in the log +% file; cf. trace.sty in LaTeX. % \def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% -\ifx\eTeXversion\undefined -\def\loggingall{\tracingcommands2 \tracingstats2 - \tracingpages1 \tracingoutput1 \tracinglostchars1 - \tracingmacros2 \tracingparagraphs1 \tracingrestores1 - \showboxbreadth\maxdimen\showboxdepth\maxdimen -}% -\else -\def\loggingall{\tracingcommands3 \tracingstats2 - \tracingpages1 \tracingoutput1 \tracinglostchars1 - \tracingmacros2 \tracingparagraphs1 \tracingrestores1 - \tracingscantokens1 \tracingassigns1 \tracingifs1 - \tracinggroups1 \tracingnesting2 - \showboxbreadth\maxdimen\showboxdepth\maxdimen +\def\loggingall{% + \tracingstats2 + \tracingpages1 + \tracinglostchars2 % 2 gives us more in etex + \tracingparagraphs1 + \tracingoutput1 + \tracingmacros2 + \tracingrestores1 + \showboxbreadth\maxdimen \showboxdepth\maxdimen + \ifx\eTeXversion\undefined\else % etex gives us more logging + \tracingscantokens1 + \tracingifs1 + \tracinggroups1 + \tracingnesting2 + \tracingassigns1 + \fi + \tracingcommands3 % 3 gives us more in etex + \errorcontextlines\maxdimen }% -\fi % add check for \lastpenalty to plain's definitions. If the last thing % we did was a \nobreak, we don't want to insert more space. @@ -436,17 +450,6 @@ } -% Single-spacing is done by various environments (specifically, in -% \nonfillstart and \quotations). -\newskip\singlespaceskip \singlespaceskip = 12.5pt -\def\singlespace{% - % Why was this kern here? It messes up equalizing space above and below - % environments. --karl, 6may93 - %{\advance \baselineskip by -\singlespaceskip - %\kern \baselineskip}% - \setleading\singlespaceskip -} - %% Simple single-character @ commands % @@ prints an @ @@ -841,12 +844,6 @@ where each line of input produces a line of output.} % to set catcodes according to plain TeX first, to allow for subscripts, % superscripts, special math chars, etc. % -% @math does not do math typesetting in section titles, index -% entries, and other such contexts where the catcodes are set before -% @math gets a chance to work. This could perhaps be fixed, but for now -% at least we can have real math in the main text, where it's needed most. -% -% \let\implicitmath = $%$ font-lock fix % % One complication: _ usually means subscripts, but it could also mean @@ -857,12 +854,42 @@ where each line of input produces a line of output.} {\catcode95 = \active % 95 = _ \gdef\mathunderscore{% \catcode95=\active - \def_{\ifnum\fam=\slfam\_\else\sb\fi}% + \def_{\ifnum\fam=\slfam \_\else\sb\fi}% }} % -\def\math{\tex\mathcode`\_="8000\mathunderscore \implicitmath\finishmath} +% Another complication: we want \\ (and @\) to output a \ character. +% FYI, plain.tex uses \\ as a temporary control sequence (why?), but +% this is not advertised and we don't care. Texinfo does not +% otherwise define @\. +% +% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\. +\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi} +% +\def\math{% + \tex + \mathcode`\_="8000 \mathunderscore + \let\\ = \mathbackslash + \mathactive + \implicitmath\finishmath} \def\finishmath#1{#1\implicitmath\Etex} +% Some active characters (such as <) are spaced differently in math. +% We have to reset their definitions in case the @math was an +% argument to a command which set the catcodes (such as @item or @section). +% +{ + \catcode`^ = \active + \catcode`< = \active + \catcode`> = \active + \catcode`+ = \active + \gdef\mathactive{% + \let^ = \ptexhat + \let< = \ptexless + \let> = \ptexgtr + \let+ = \ptexplus + } +} + % @bullet and @minus need the same treatment as @math, just above. \def\bullet{\implicitmath\ptexbullet\implicitmath} \def\minus{\implicitmath-\implicitmath} @@ -954,7 +981,7 @@ where each line of input produces a line of output.} \ifx\empty\imagewidth\else width \imagewidth \fi \ifx\empty\imageheight\else height \imageheight \fi \ifnum\pdftexversion<13 - #1.pdf% + #1.pdf% \else {#1.pdf}% \fi @@ -976,40 +1003,39 @@ where each line of input produces a line of output.} \openin 1 \jobname.toc \ifeof 1\else\begingroup \closein 1 - \indexnofonts - \def\tt{} - \let\_ = \normalunderscore % Thanh's hack / proper braces in bookmarks \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace % \def\chapentry ##1##2##3{} - \let\appendixentry = \chapentry - \def\unnumbchapentry ##1##2{} \def\secentry ##1##2##3##4{\advancenumber{chap##2}} - \def\unnumbsecentry ##1##2{} \def\subsecentry ##1##2##3##4##5{\advancenumber{sec##2.##3}} - \def\unnumbsubsecentry ##1##2{} \def\subsubsecentry ##1##2##3##4##5##6{\advancenumber{subsec##2.##3.##4}} - \def\unnumbsubsubsecentry ##1##2{} + \let\appendixentry = \chapentry + \let\unnumbchapentry = \chapentry + \let\unnumbsecentry = \secentry + \let\unnumbsubsecentry = \subsecentry + \let\unnumbsubsubsecentry = \subsubsecentry \input \jobname.toc \def\chapentry ##1##2##3{% \pdfoutline goto name{\pdfmkpgn{##3}}count-\expnumber{chap##2}{##1}} - \let\appendixentry = \chapentry - \def\unnumbchapentry ##1##2{% - \pdfoutline goto name{\pdfmkpgn{##2}}{##1}} \def\secentry ##1##2##3##4{% \pdfoutline goto name{\pdfmkpgn{##4}}count-\expnumber{sec##2.##3}{##1}} - \def\unnumbsecentry ##1##2{% - \pdfoutline goto name{\pdfmkpgn{##2}}{##1}} \def\subsecentry ##1##2##3##4##5{% \pdfoutline goto name{\pdfmkpgn{##5}}count-\expnumber{subsec##2.##3.##4}{##1}} - \def\unnumbsubsecentry ##1##2{% - \pdfoutline goto name{\pdfmkpgn{##2}}{##1}} \def\subsubsecentry ##1##2##3##4##5##6{% \pdfoutline goto name{\pdfmkpgn{##6}}{##1}} - \def\unnumbsubsubsecentry ##1##2{% - \pdfoutline goto name{\pdfmkpgn{##2}}{##1}} + \let\appendixentry = \chapentry + \let\unnumbchapentry = \chapentry + \let\unnumbsecentry = \secentry + \let\unnumbsubsecentry = \subsecentry + \let\unnumbsubsubsecentry = \subsubsecentry + % + % Make special characters normal for writing to the pdf file. + % + \indexnofonts + \let\tt=\relax + \turnoffactive \input \jobname.toc \endgroup\fi }} @@ -1159,7 +1185,7 @@ where each line of input produces a line of output.} \newcount\mainmagstep \ifx\bigger\relax % not really supported. - \let\mainmagstep=\magstep1 + \mainmagstep=\magstep1 \setfont\textrm\rmshape{12}{1000} \setfont\texttt\ttshape{12}{1000} \else @@ -1220,6 +1246,7 @@ where each line of input produces a line of output.} \font\titlei=cmmi12 scaled \magstep3 \font\titlesy=cmsy10 scaled \magstep4 \def\authorrm{\secrm} +\def\authortt{\sectt} % Chapter (and unnumbered) fonts (17.28pt). \setfont\chaprm\rmbshape{12}{\magstep2} @@ -1334,6 +1361,7 @@ where each line of input produces a line of output.} \setfont\shortcontrm\rmshape{12}{1000} \setfont\shortcontbf\bxshape{12}{1000} \setfont\shortcontsl\slshape{12}{1000} +\setfont\shortconttt\ttshape{12}{1000} %% Add scribe-like font environments, plus @l for inline lisp (usually sans %% serif) and @ii for TeX italic @@ -1341,8 +1369,8 @@ where each line of input produces a line of output.} % \smartitalic{ARG} outputs arg in italics, followed by an italic correction % unless the following character is such as not to need one. \def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else\/\fi\fi\fi} -\def\smartslanted#1{{\sl #1}\futurelet\next\smartitalicx} -\def\smartitalic#1{{\it #1}\futurelet\next\smartitalicx} +\def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx} +\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx} \let\i=\smartitalic \let\var=\smartslanted @@ -1431,11 +1459,19 @@ where each line of input produces a line of output.} \def\realdash{-} \def\codedash{-\discretionary{}{}{}} -\def\codeunder{\ifusingtt{\normalunderscore\discretionary{}{}{}}{\_}} +\def\codeunder{% + % this is all so @math{@code{var_name}+1} can work. In math mode, _ + % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.) + % will therefore expand the active definition of _, which is us + % (inside @code that is), therefore an endless loop. + \ifusingtt{\ifmmode + \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_. + \else\normalunderscore \fi + \discretionary{}{}{}}% + {\_}% +} \def\codex #1{\tclose{#1}\endgroup} -%\let\exp=\tclose %Was temporary - % @kbd is like @code, except that if the argument is just one @key command, % then @kbd has no effect. @@ -1573,7 +1609,8 @@ where each line of input produces a line of output.} \let\subtitlerm=\tenrm \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}% % - \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines}% + \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines + \let\tt=\authortt}% % % Leave some space at the very top of the page. \vglue\titlepagetopglue @@ -1637,8 +1674,6 @@ where each line of input produces a line of output.} \global\let\contents = \relax \global\let\shortcontents = \relax \fi - % - \ifpdf \pdfmakepagedesttrue \fi } \def\finishtitlepage{% @@ -1856,10 +1891,18 @@ where each line of input produces a line of output.} % \parskip glue -- logically it's part of the @item we just started. \nobreak \vskip-\parskip % - % Stop a page break at the \parskip glue coming up. Unfortunately + % Stop a page break at the \parskip glue coming up. (Unfortunately % we can't prevent a possible page break at the following - % \baselineskip glue. - \nobreak + % \baselineskip glue.) However, if what follows is an environment + % such as @example, there will be no \parskip glue; then + % the negative vskip we just would cause the example and the item to + % crash together. So we use this bizarre value of 10001 as a signal + % to \aboveenvbreak to insert \parskip glue after all. + % (Possibly there are other commands that could be followed by + % @example which need the same treatment, but not section titles; or + % maybe section titles are the only special case and they should be + % penalty 10001...) + \penalty 10001 \endgroup \itemxneedsnegativevskipfalse \else @@ -2396,20 +2439,20 @@ width0pt\relax} \fi \let\item = \relax } -% Ignore @ignore ... @end ignore. -% -\def\ignore{\doignore{ignore}} - -% Also ignore @ifinfo, @ifhtml, @ifnottex, @html, @menu, -% @documentdescription, and @direntry text. +% Ignore @ignore, @ifhtml, @ifinfo, and the like. % -\def\ifinfo{\doignore{ifinfo}} +\def\direntry{\doignore{direntry}} +\def\documentdescriptionword{documentdescription} +\def\documentdescription{\doignore{documentdescription}} +\def\html{\doignore{html}} \def\ifhtml{\doignore{ifhtml}} +\def\ifinfo{\doignore{ifinfo}} \def\ifnottex{\doignore{ifnottex}} -\def\html{\doignore{html}} +\def\ifplaintext{\doignore{ifplaintext}} +\def\ifxml{\doignore{ifxml}} +\def\ignore{\doignore{ignore}} \def\menu{\doignore{menu}} -\def\documentdescription{\doignore{documentdescription}} -\def\direntry{\doignore{direntry}} +\def\xml{\doignore{xml}} % @dircategory CATEGORY -- specify a category of the dir file % which this file should belong to. Ignore this in TeX. @@ -2436,14 +2479,21 @@ width0pt\relax} \fi % We must not have @c interpreted as a control sequence. \catcode`\@ = 12 % - % Make the letter c a comment character so that the rest of the line - % will be ignored. This way, the document can have (for example) - % @c @end ifinfo - % and the @end ifinfo will be properly ignored. - % (We've just changed @ to catcode 12.) - \catcode`\c = 14 + \def\ignoreword{#1}% + \ifx\ignoreword\documentdescriptionword + % The c kludge breaks documentdescription, since + % `documentdescription' contains a `c'. Means not everything will + % be ignored inside @documentdescription, but oh well... + \else + % Make the letter c a comment character so that the rest of the line + % will be ignored. This way, the document can have (for example) + % @c @end ifinfo + % and the @end ifinfo will be properly ignored. + % (We've just changed @ to catcode 12.) + \catcode`\c = 14 + \fi % - % And now expand that command. + % And now expand the command defined above. \doignoretext } @@ -2462,7 +2512,7 @@ width0pt\relax} \fi \immediate\write16{If you are running another version of TeX, relax.} \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.} \immediate\write16{ Then upgrade your TeX installation if you can.} - \immediate\write16{ (See ftp://ftp.gnu.org/pub/gnu/TeX.README.)} + \immediate\write16{ (See ftp://ftp.gnu.org/non-gnu/TeX.README.)} \immediate\write16{If you are stuck with version 3.0, run the} \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} \immediate\write16{ to use a workaround.} @@ -2484,7 +2534,7 @@ width0pt\relax} \fi % We must actually expand the ignored text to look for the @end % command, so that nested ignore constructs work. Thus, we put the % text into a \vbox and then do nothing with the result. To minimize - % the change of memory overflow, we follow the approach outlined on + % the chance of memory overflow, we follow the approach outlined on % page 401 of the TeXbook: make the current font be a dummy font. % \setbox0 = \vbox\bgroup @@ -2536,7 +2586,7 @@ width0pt\relax} \fi % Do minimal line-breaking. \pretolerance = 10000 % - % Do not execute instructions in @tex + % Do not execute instructions in @tex. \def\tex{\doignore{tex}}% % Do not execute macro definitions. % `c' is a comment character, so the word `macro' will get cut off. @@ -2634,19 +2684,21 @@ width0pt\relax} \fi \def\ifclearfail{\nestedignore{ifclear}} \defineunmatchedend{ifclear} -% @iftex, @ifnothtml, @ifnotinfo always succeed; we read the text -% following, through the first @end iftex (etc.). Make `@end iftex' -% (etc.) valid only after an @iftex. +% @iftex, @ifnothtml, @ifnotinfo, @ifnotplaintext always succeed; we +% read the text following, through the first @end iftex (etc.). Make +% `@end iftex' (etc.) valid only after an @iftex. % \def\iftex{\conditionalsucceed{iftex}} \def\ifnothtml{\conditionalsucceed{ifnothtml}} \def\ifnotinfo{\conditionalsucceed{ifnotinfo}} +\def\ifnotplaintext{\conditionalsucceed{ifnotplaintext}} \defineunmatchedend{iftex} \defineunmatchedend{ifnothtml} \defineunmatchedend{ifnotinfo} +\defineunmatchedend{ifnotplaintext} -% We can't just want to start a group at @iftex (for example) and end it -% at @end iftex, since then @set commands inside the conditional have no +% We can't just want to start a group at @iftex (etc.) and end it at +% @end iftex, since then @set commands inside the conditional have no % effect (they'd get reverted at the end of the group). So we must % define \Eiftex to redefine itself to be its previous value. (We can't % just define it to fail again with an ``unmatched end'' error, since @@ -2861,7 +2913,7 @@ width0pt\relax} \fi % If an index command is used in an @example environment, any spaces % therein should become regular spaces in the raw index file, not the -% expansion of \tie (\\leavevmode \penalty \@M \ ). +% expansion of \tie (\leavevmode \penalty \@M \ ). {\obeyspaces \gdef\unsepspaces{\obeyspaces\let =\space}} @@ -3524,13 +3576,18 @@ width0pt\relax} \fi \global\let\subsubsection = \numberedsubsubsec } +% we use \chapno to avoid indenting back +\def\appendixbox#1{% + \setbox0 = \hbox{\putwordAppendix{} \the\chapno}% + \hbox to \wd0{#1\hss}} + \outer\def\appendix{\parsearg\appendixyyy} \def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz \def\appendixzzz #1{% \secno=0 \subsecno=0 \subsubsecno=0 \global\advance \appendixno by 1 \message{\putwordAppendix\space \appendixletter}% -\chapmacro {#1}{\putwordAppendix{} \appendixletter}% +\chapmacro {#1}{\appendixbox{\putwordAppendix{} \appendixletter}}% \gdef\thissection{#1}% \gdef\thischaptername{#1}% \xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% @@ -3572,7 +3629,7 @@ width0pt\relax} \fi \unnumbchapmacro {#1}% \gdef\thischapter{#1}\gdef\thissection{#1}% \toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash unnumbchapentry{\the\toks0}}}% +\edef\temp{\noexpand\writetocentry{\realbackslash unnumbchapentry{\the\toks0}{\the\chapno}}}% \temp \unnumbnoderef \global\let\section = \unnumberedsec @@ -3613,7 +3670,8 @@ width0pt\relax} \fi \def\unnumberedseczzz #1{% \plainsecheading {#1}\gdef\thissection{#1}% \toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsecentry{\the\toks0}}}% +\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsecentry% + {\the\toks0}{\the\chapno}{\the\secno}}}% \temp \unnumbnoderef \nobreak @@ -3652,7 +3710,7 @@ width0pt\relax} \fi \plainsubsecheading {#1}\gdef\thissection{#1}% \toks0 = {#1}% \edef\temp{\noexpand\writetocentry{\realbackslash unnumbsubsecentry% - {\the\toks0}}}% + {\the\toks0}{\the\chapno}{\the\secno}{\the\subsecno}}}% \temp \unnumbnoderef \nobreak @@ -3693,7 +3751,7 @@ width0pt\relax} \fi \plainsubsubsecheading {#1}\gdef\thissection{#1}% \toks0 = {#1}% \edef\temp{\noexpand\writetocentry{\realbackslash unnumbsubsubsecentry% - {\the\toks0}}}% + {\the\toks0}{\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}}}% \temp \unnumbnoderef \nobreak @@ -3892,7 +3950,16 @@ width0pt\relax} \fi \hangindent = \wd0 % zero if no section number \unhbox0 #3}% }% - \ifdim\parskip<10pt \nobreak\kern10pt\nobreak\kern-\parskip\fi \nobreak + % Add extra space after the heading -- either a line space or a + % paragraph space, whichever is more. (Some people like to set + % \parskip to large values for some reason.) + \nobreak + \ifdim\parskip>\normalbaselineskip + \kern\parskip + \else + \kern\normalbaselineskip + \fi + \nobreak } @@ -3905,7 +3972,7 @@ width0pt\relax} \fi % argument, which will end up as the last argument to the \...entry macro. % % We open the .toc file here instead of at @setfilename or any other -% given time so that @contents can be put in the document anywhere. +% fixed time so that @contents can be put in the document anywhere. % \newif\iftocfileopened \def\writetocentry#1{% @@ -3914,6 +3981,14 @@ width0pt\relax} \fi \global\tocfileopenedtrue \fi \iflinks \write\tocfile{#1{\folio}}\fi + % + % Tell \shipout to create a page destination if we're doing pdf, which + % will be the target of the links in the table of contents. We can't + % just do it on every page because the title pages are numbered 1 and + % 2 (the page numbers aren't printed), and so are the first two pages + % of the document. Thus, we'd have two destinations named `1', and + % two named `2'. + \ifpdf \pdfmakepagedesttrue \fi } \newskip\contentsrightmargin \contentsrightmargin=1in @@ -3973,16 +4048,17 @@ width0pt\relax} \fi \let\unnumbchapentry = \shortunnumberedentry % We want a true roman here for the page numbers. \secfonts - \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl + \let\rm=\shortcontrm \let\bf=\shortcontbf + \let\sl=\shortcontsl \let\tt=\shortconttt \rm \hyphenpenalty = 10000 \advance\baselineskip by 1pt % Open it up a little. \def\secentry ##1##2##3##4{} - \def\unnumbsecentry ##1##2{} \def\subsecentry ##1##2##3##4##5{} - \def\unnumbsubsecentry ##1##2{} \def\subsubsecentry ##1##2##3##4##5##6{} - \def\unnumbsubsubsecentry ##1##2{} + \let\unnumbsecentry = \secentry + \let\unnumbsubsecentry = \subsecentry + \let\unnumbsubsubsecentry = \subsubsecentry \openin 1 \jobname.toc \ifeof 1 \else \closein 1 @@ -4015,7 +4091,8 @@ width0pt\relax} \fi } % Appendices, in the main contents. -\def\appendixentry#1#2#3{\dochapentry{\putwordAppendix{} #2\labelspace#1}{#3}} +\def\appendixentry#1#2#3{% + \dochapentry{\appendixbox{\putwordAppendix{} #2}\labelspace#1}{#3}} % % Appendices, in the short toc. \let\shortappendixentry = \shortchapentry @@ -4039,21 +4116,21 @@ width0pt\relax} \fi } % Unnumbered chapters. -\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}} -\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno\bgroup#2\egroup}} +\def\unnumbchapentry#1#2#3{\dochapentry{#1}{#3}} +\def\shortunnumberedentry#1#2#3{\tocentry{#1}{\doshortpageno\bgroup#3\egroup}} % Sections. \def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}} -\def\unnumbsecentry#1#2{\dosecentry{#1}{#2}} +\def\unnumbsecentry#1#2#3#4{\dosecentry{#1}{#4}} % Subsections. \def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}} -\def\unnumbsubsecentry#1#2{\dosubsecentry{#1}{#2}} +\def\unnumbsubsecentry#1#2#3#4#5{\dosubsecentry{#1}{#5}} % And subsubsections. \def\subsubsecentry#1#2#3#4#5#6{% \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} -\def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}} +\def\unnumbsubsubsecentry#1#2#3#4#5#6{\dosubsubsecentry{#1}{#6}} % This parameter controls the indentation of the various levels. \newdimen\tocindent \tocindent = 3pc @@ -4114,36 +4191,27 @@ width0pt\relax} \fi \message{environments,} % @foo ... @end foo. +% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. +% % Since these characters are used in examples, it should be an even number of % \tt widths. Each \tt character is 1en, so two makes it 1em. -% Furthermore, these definitions must come after we define our fonts. -\newbox\dblarrowbox \newbox\longdblarrowbox -\newbox\pushcharbox \newbox\bullbox -\newbox\equivbox \newbox\errorbox - -%{\tentt -%\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil} -%\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil} -%\global\setbox\pushcharbox = \hbox to 1em{\hfil$\dashv$\hfil} -%\global\setbox\equivbox = \hbox to 1em{\hfil$\ptexequiv$\hfil} -% Adapted from the manmac format (p.420 of TeXbook) -%\global\setbox\bullbox = \hbox to 1em{\kern.15em\vrule height .75ex width .85ex -% depth .1ex\hfil} -%} - -% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. +% \def\point{$\star$} \def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} \def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} \def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} \def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} +% The @error{} command. % Adapted from the TeXbook's \boxit. +% +\newbox\errorbox +% {\tentt \global\dimen0 = 3em}% Width of the box. \dimen2 = .55pt % Thickness of rules % The text. (`r' is open on the right, `e' somewhat less so on the left.) \setbox0 = \hbox{\kern-.75pt \tensf error\kern-1.5pt} - +% \global\setbox\errorbox=\hbox to \dimen0{\hfil \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. \advance\hsize by -2\dimen2 % Rules. @@ -4154,8 +4222,7 @@ width0pt\relax} \fi \kern3pt\vrule width\dimen2}% Space to right. \hrule height\dimen2} \hfil} - -% The @error{} command. +% \def\error{\leavevmode\lower.7ex\copy\errorbox} % @tex ... @end tex escapes into raw Tex temporarily. @@ -4195,9 +4262,9 @@ width0pt\relax} \fi \def\@{@}% \let\Etex=\endgroup} -% Define @lisp ... @endlisp. +% Define @lisp ... @end lisp. % @lisp does a \begingroup so it can rebind things, -% including the definition of @endlisp (which normally is erroneous). +% including the definition of @end lisp (which normally is erroneous). % Amount to narrow the margins by for @lisp. \newskip\lispnarrowing \lispnarrowing=0.4in @@ -4226,15 +4293,18 @@ width0pt\relax} \fi % Make spacing and below environment symmetrical. We use \parskip here % to help in doing that, since in @example-like environments \parskip % is reset to zero; thus the \afterenvbreak inserts no space -- but the -% start of the next paragraph will insert \parskip +% start of the next paragraph will insert \parskip. % \def\aboveenvbreak{{% - \ifnum\lastpenalty < 10000 + % =10000 instead of <10000 because of a special case in \itemzzz, q.v. + \ifnum \lastpenalty=10000 \else \advance\envskipamount by \parskip \endgraf \ifdim\lastskip<\envskipamount \removelastskip - \penalty-50 + % it's not a good place to break if the last penalty was \nobreak + % or better ... + \ifnum\lastpenalty>10000 \else \penalty-50 \fi \vskip\envskipamount \fi \fi @@ -4313,7 +4383,6 @@ width0pt\relax} \fi \inENV % This group ends at the end of the body \hfuzz = 12pt % Don't be fussy \sepspaces % Make spaces be word-separators rather than space tokens. - \singlespace \let\par = \lisppar % don't ignore blank lines \obeylines % each line of input is a line of output \parskip = 0pt @@ -4428,7 +4497,6 @@ width0pt\relax} \fi \def\quotation{% \begingroup\inENV %This group ends at the end of the @quotation body {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip - \singlespace \parindent=0pt % We have retained a nonzero parskip for the environment, since we're % doing normal filling. So to avoid extra space below the environment... @@ -4451,10 +4519,14 @@ width0pt\relax} \fi % % [Knuth]: Donald Ervin Knuth, 1996. The TeXbook. % -% [Knuth] p. 344; only we need to do '@' too +% [Knuth] p.344; only we need to do the other characters Texinfo sets +% active too. Otherwise, they get lost as the first character on a +% verbatim line. \def\dospecials{% - \do\ \do\\\do\@\do\{\do\}\do\$\do\&% - \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~} + \do\ \do\\\do\{\do\}\do\$\do\&% + \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~% + \do\<\do\>\do\|\do\@\do+\do\"% +} % % [Knuth] p. 380 \def\uncatcodespecials{% @@ -4541,7 +4613,7 @@ width0pt\relax} \fi % % For Texinfo it's a lot easier than for LaTeX, % because texinfo's \verbatim doesn't stop at '\end{verbatim}': -% we need not redefine '\', '{' and '}' +% we need not redefine '\', '{' and '}'. % % Inspired by LaTeX's verbatim command set [latex.ltx] %% Include LaTeX hack for completeness -- never know @@ -4551,9 +4623,14 @@ width0pt\relax} \fi %% \catcode`\\=12|gdef|doverbatim#1@end verbatim[ %% #1|endgroup|def|Everbatim[]|end[verbatim]] %% |endgroup +% \begingroup \catcode`\ =\active - \gdef\doverbatim#1@end verbatim{#1\end{verbatim}} + \obeylines % + % ignore everything up to the first ^^M, that's the newline at the end + % of the @verbatim input line itself. Otherwise we get an extra blank + % line in the output. + \gdef\doverbatim#1^^M#2@end verbatim{#2\end{verbatim}}% \endgroup % \def\verbatim{% @@ -4595,24 +4672,94 @@ width0pt\relax} \fi \endgroup\nonfillfinish\endgroup } +% @copying ... @end copying. +% Save the text away for @insertcopying later. Many commands won't be +% allowed in this context, but that's ok. +% +% We save the uninterpreted tokens, rather than creating a box. +% Saving the text in a box would be much easier, but then all the +% typesetting commands (@smallbook, font changes, etc.) have to be done +% beforehand -- and a) we want @copying to be done first in the source +% file; b) letting users define the frontmatter in as flexible order as +% possible is very desirable. +% +\def\copying{\begingroup + % Define a command to swallow text until we reach `@end copying'. + % \ is the escape char in this texinfo.tex file, so it is the + % delimiter for the command; @ will be the escape char when we read + % it, but that doesn't matter. + \long\def\docopying##1\end copying{\gdef\copyingtext{##1}\enddocopying}% + % + % We must preserve ^^M's in the input file; see \insertcopying below. + \catcode`\^^M = \active + \docopying +} + +% What we do to finish off the copying text. +% +\def\enddocopying{\endgroup\ignorespaces} + +% @insertcopying. Here we must play games with ^^M's. On the one hand, +% we need them to delimit commands such as `@end quotation', so they +% must be active. On the other hand, we certainly don't want every +% end-of-line to be a \par, as would happen with the normal active +% definition of ^^M. On the third hand, two ^^M's in a row should still +% generate a \par. +% +% Our approach is to make ^^M insert a space and a penalty1 normally; +% then it can also check if \lastpenalty=1. If it does, then manually +% do \par. +% +% This messes up the normal definitions of @c[omment], so we redefine +% it. Similarly for @ignore. (These commands are used in the gcc +% manual for man page generation.) +% +% Seems pretty fragile, most line-oriented commands will presumably +% fail, but for the limited use of getting the copying text (which +% should be quite simple) inserted, we can hope it's ok. +% +{\catcode`\^^M=\active % +\gdef\insertcopying{\begingroup % + \parindent = 0pt % looks wrong on title page + \def^^M{% + \ifnum \lastpenalty=1 % + \par % + \else % + \space \penalty 1 % + \fi % + }% + % + % Fix @c[omment] for catcode 13 ^^M's. + \def\c##1^^M{\ignorespaces}% + \let\comment = \c % + % + % Don't bother jumping through all the hoops that \doignore does, it + % would be very hard since the catcodes are already set. + \long\def\ignore##1\end ignore{\ignorespaces}% + % + \copyingtext % +\endgroup}% +} \message{defuns,} % @defun etc. % Allow user to change definition object font (\df) internally -\def\setdeffont #1 {\csname DEF#1\endcsname} +\def\setdeffont#1 {\csname DEF#1\endcsname} \newskip\defbodyindent \defbodyindent=.4in \newskip\defargsindent \defargsindent=50pt -\newskip\deftypemargin \deftypemargin=12pt \newskip\deflastargmargin \deflastargmargin=18pt \newcount\parencount -% define \functionparens, which makes ( and ) and & do special things. -% \functionparens affects the group it is contained in. + +% We want ()&[] to print specially on the defun line. +% \def\activeparens{% -\catcode`\(=\active \catcode`\)=\active \catcode`\&=\active -\catcode`\[=\active \catcode`\]=\active} + \catcode`\(=\active \catcode`\)=\active + \catcode`\&=\active + \catcode`\[=\active \catcode`\]=\active +} % Make control sequences which act like normal parenthesis chars. \let\lparen = ( \let\rparen = ) @@ -4663,84 +4810,117 @@ width0pt\relax} \fi \global\let& = \ampnr } -% First, defname, which formats the header line itself. -% #1 should be the function name. -% #2 should be the type of definition, such as "Function". - -\def\defname #1#2{% -% Get the values of \leftskip and \rightskip as they were -% outside the @def... -\dimen2=\leftskip -\advance\dimen2 by -\defbodyindent -\noindent -\setbox0=\hbox{\hskip \deflastargmargin{\rm #2}\hskip \deftypemargin}% -\dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line -\dimen1=\hsize \advance \dimen1 by -\defargsindent %size for continuations -\parshape 2 0in \dimen0 \defargsindent \dimen1 -% Now output arg 2 ("Function" or some such) -% ending at \deftypemargin from the right margin, -% but stuck inside a box of width 0 so it does not interfere with linebreaking -{% Adjust \hsize to exclude the ambient margins, -% so that \rightline will obey them. -\advance \hsize by -\dimen2 -\rlap{\rightline{{\rm #2}\hskip -1.25pc }}}% -% Make all lines underfull and no complaints: -\tolerance=10000 \hbadness=10000 -\advance\leftskip by -\defbodyindent -\exdentamount=\defbodyindent -{\df #1}\enskip % Generate function name -} - -% Actually process the body of a definition -% #1 should be the terminating control sequence, such as \Edefun. -% #2 should be the "another name" control sequence, such as \defunx. -% #3 should be the control sequence that actually processes the header, -% such as \defunheader. - -\def\defparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2{\begingroup\obeylines\activeparens\spacesplit#3}% -\parindent=0in -\advance\leftskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup % -\catcode 61=\active % 61 is `=' -\obeylines\activeparens\spacesplit#3} +% \defname, which formats the name of the @def (not the args). +% #1 is the function name. +% #2 is the type of definition, such as "Function". +% +\def\defname#1#2{% + % How we'll output the type name. Putting it in brackets helps + % distinguish it from the body text that may end up on the next line + % just below it. + \ifempty{#2}% + \def\defnametype{}% + \else + \def\defnametype{[\rm #2]}% + \fi + % + % Get the values of \leftskip and \rightskip as they were outside the @def... + \dimen2=\leftskip + \advance\dimen2 by -\defbodyindent + % + % Figure out values for the paragraph shape. + \setbox0=\hbox{\hskip \deflastargmargin{\defnametype}}% + \dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line + \dimen1=\hsize \advance \dimen1 by -\defargsindent % size for continuations + \parshape 2 0in \dimen0 \defargsindent \dimen1 + % + % Output arg 2 ("Function" or some such) but stuck inside a box of + % width 0 so it does not interfere with linebreaking. + \noindent + % + {% Adjust \hsize to exclude the ambient margins, + % so that \rightline will obey them. + \advance \hsize by -\dimen2 + \dimen3 = 0pt % was -1.25pc + \rlap{\rightline{\defnametype\kern\dimen3}}% + }% + % + % Allow all lines to be underfull without complaint: + \tolerance=10000 \hbadness=10000 + \advance\leftskip by -\defbodyindent + \exdentamount=\defbodyindent + {\df #1}\enskip % output function name + % \defunargs will be called next to output the arguments, if any. +} +% Common pieces to start any @def... % #1 is the \E... control sequence to end the definition (which we define). -% #2 is the \...x control sequence for consecutive fns (which we define). -% #3 is the control sequence to call to resume processing. +% #2 is the \...x control sequence (which our caller defines). +% #3 is the control sequence to process the header, such as \defunheader. +% +\def\parsebodycommon#1#2#3{% + \begingroup\inENV + % If there are two @def commands in a row, we'll have a \nobreak, + % which is there to keep the function description together with its + % header. But if there's nothing but headers, we want to allow a + % break after all. + \ifnum\lastpenalty=10000 \penalty0 \fi + \medbreak + % + % Define the \E... end token that this defining construct specifies + % so that it will exit this group. + \def#1{\endgraf\endgroup\medbreak}% + % + \parindent=0in + \advance\leftskip by \defbodyindent + \exdentamount=\defbodyindent +} + +% Common part of the \...x definitions. +% +\def\defxbodycommon{% + % As with \parsebodycommon above, allow line break if we have multiple + % x headers in a row. It's not a great place, though. + \ifnum\lastpenalty=10000 \penalty1000 \fi + % + \begingroup\obeylines +} + +% Process body of @defun, @deffn, @defmac, etc. +% +\def\defparsebody#1#2#3{% + \parsebodycommon{#1}{#2}{#3}% + \def#2{\defxbodycommon \activeparens \spacesplit#3}% + \catcode61=\active % 61 is `=' + \begingroup\obeylines\activeparens + \spacesplit#3% +} + +% #1, #2, #3 are the common arguments (see \parsebodycommon above). % #4, delimited by the space, is the class name. % -\def\defmethparsebody#1#2#3#4 {\begingroup\inENV % -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2##1 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}}}% -\parindent=0in -\advance\leftskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup\obeylines\activeparens\spacesplit{#3{#4}}} +\def\defmethparsebody#1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 {\defxbodycommon \activeparens \spacesplit{#3{##1}}}% + \begingroup\obeylines\activeparens + % The \empty here prevents misinterpretation of a construct such as + % @deffn {whatever} {Enharmonic comma} + % See comments at \deftpparsebody, although in our case we don't have + % to remove the \empty afterwards, since it is empty. + \spacesplit{#3{#4}}\empty +} % Used for @deftypemethod and @deftypeivar. -% #1 is the \E... control sequence to end the definition (which we define). -% #2 is the \...x control sequence for consecutive fns (which we define). -% #3 is the control sequence to call to resume processing. +% #1, #2, #3 are the common arguments (see \defparsebody). % #4, delimited by a space, is the class name. % #5 is the method's return type. % -\def\deftypemethparsebody#1#2#3#4 #5 {\begingroup\inENV - \medbreak - \def#1{\endgraf\endgroup\medbreak}% - \def#2##1 ##2 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}{##2}}}% - \parindent=0in - \advance\leftskip by \defbodyindent - \exdentamount=\defbodyindent - \begingroup\obeylines\activeparens\spacesplit{#3{#4}{#5}}} +\def\deftypemethparsebody#1#2#3#4 #5 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 {\defxbodycommon \activeparens \spacesplit{#3{##1}{##2}}}% + \begingroup\obeylines\activeparens + \spacesplit{#3{#4}{#5}}% +} % Used for @deftypeop. The change from \deftypemethparsebody is an % extra argument at the beginning which is the `category', instead of it @@ -4749,64 +4929,48 @@ width0pt\relax} \fi % input at hand. Thus also need a control sequence (passed as #5) for % the \E... definition to assign the category name to. % -\def\deftypeopparsebody#1#2#3#4#5 #6 {\begingroup\inENV - \medbreak - \def#1{\endgraf\endgroup\medbreak}% - \def#2##1 ##2 ##3 {% - \def#4{##1}% - \begingroup\obeylines\activeparens\spacesplit{#3{##2}{##3}}}% - \parindent=0in - \advance\leftskip by \defbodyindent - \exdentamount=\defbodyindent - \begingroup\obeylines\activeparens\spacesplit{#3{#5}{#6}}} - -\def\defopparsebody #1#2#3#4#5 {\begingroup\inENV % -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2##1 ##2 {\def#4{##1}% -\begingroup\obeylines\activeparens\spacesplit{#3{##2}}}% -\parindent=0in -\advance\leftskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup\obeylines\activeparens\spacesplit{#3{#5}}} +\def\deftypeopparsebody#1#2#3#4#5 #6 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 ##3 {\def#4{##1}% + \defxbodycommon \activeparens \spacesplit{#3{##2}{##3}}}% + \begingroup\obeylines\activeparens + \spacesplit{#3{#5}{#6}}% +} + +% For @defop. +\def\defopparsebody #1#2#3#4#5 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 {\def#4{##1}% + \defxbodycommon \activeparens \spacesplit{#3{##2}}}% + \begingroup\obeylines\activeparens + \spacesplit{#3{#5}}% +} % These parsing functions are similar to the preceding ones % except that they do not make parens into active characters. % These are used for "variables" since they have no arguments. - -\def\defvarparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2{\begingroup\obeylines\spacesplit#3}% -\parindent=0in -\advance\leftskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup % -\catcode 61=\active % -\obeylines\spacesplit#3} - -% This is used for \def{tp,vr}parsebody. It could probably be used for -% some of the others, too, with some judicious conditionals. % -\def\parsebodycommon#1#2#3{% - \begingroup\inENV % - \medbreak % - % Define the end token that this defining construct specifies - % so that it will exit this group. - \def#1{\endgraf\endgroup\medbreak}% - \def#2##1 {\begingroup\obeylines\spacesplit{#3{##1}}}% - \parindent=0in - \advance\leftskip by \defbodyindent - \exdentamount=\defbodyindent +\def\defvarparsebody #1#2#3{% + \parsebodycommon{#1}{#2}{#3}% + \def#2{\defxbodycommon \spacesplit#3}% + \catcode61=\active % + \begingroup\obeylines + \spacesplit#3% +} + +% @defopvar. +\def\defopvarparsebody #1#2#3#4#5 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 {\def#4{##1}% + \defxbodycommon \spacesplit{#3{##2}}}% \begingroup\obeylines + \spacesplit{#3{#5}}% } \def\defvrparsebody#1#2#3#4 {% \parsebodycommon{#1}{#2}{#3}% + \def#2##1 {\defxbodycommon \spacesplit{#3{##1}}}% + \begingroup\obeylines \spacesplit{#3{#4}}% } @@ -4821,6 +4985,8 @@ width0pt\relax} \fi % \def\deftpparsebody #1#2#3#4 {% \parsebodycommon{#1}{#2}{#3}% + \def#2##1 {\defxbodycommon \spacesplit{#3{##1}}}% + \begingroup\obeylines \spacesplit{\parsetpheaderline{#3{#4}}}\empty } @@ -4837,32 +5003,22 @@ width0pt\relax} \fi #1{\removeemptybraces#2\relax}{#3}% }% -\def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV % -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2##1 ##2 {\def#4{##1}% -\begingroup\obeylines\spacesplit{#3{##2}}}% -\parindent=0in -\advance\leftskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup\obeylines\spacesplit{#3{#5}}} - -% Split up #2 at the first space token. +% Split up #2 (the rest of the input line) at the first space token. % call #1 with two arguments: % the first is all of #2 before the space token, % the second is all of #2 after that space token. % If #2 contains no space token, all of it is passed as the first arg % and the second is passed as empty. - -{\obeylines -\gdef\spacesplit#1#2^^M{\endgroup\spacesplitfoo{#1}#2 \relax\spacesplitfoo}% -\long\gdef\spacesplitfoo#1#2 #3#4\spacesplitfoo{% -\ifx\relax #3% -#1{#2}{}\else #1{#2}{#3#4}\fi}} - -% So much for the things common to all kinds of definitions. +% +{\obeylines % + \gdef\spacesplit#1#2^^M{\endgroup\spacesplitx{#1}#2 \relax\spacesplitx}% + \long\gdef\spacesplitx#1#2 #3#4\spacesplitx{% + \ifx\relax #3% + #1{#2}{}% + \else % + #1{#2}{#3#4}% + \fi}% +} % Define @defun. @@ -5273,7 +5429,7 @@ width0pt\relax} \fi \message{Warning: redefining \the\macname}% \else \expandafter\ifx\csname \the\macname\endcsname \relax - \else \errmessage{The name \the\macname\space is reserved}\fi + \else \errmessage{Macro name \the\macname\space already defined}\fi \global\cslet{macsave.\the\macname}{\the\macname}% \global\expandafter\let\csname ismacro.\the\macname\endcsname=1% % Add the macroname to \macrolist @@ -6019,11 +6175,13 @@ should work if nowhere else does.} } % Parameters in order: 1) textheight; 2) textwidth; 3) voffset; -% 4) hoffset; 5) binding offset; 6) topskip. We also call -% \setleading{\textleading}, so the caller should define \textleading. -% The caller should also set \parskip. +% 4) hoffset; 5) binding offset; 6) topskip; 7) physical page height; 8) +% physical page width. +% +% We also call \setleading{\textleading}, so the caller should define +% \textleading. The caller should also set \parskip. % -\def\internalpagesizes#1#2#3#4#5#6{% +\def\internalpagesizes#1#2#3#4#5#6#7#8{% \voffset = #3\relax \topskip = #6\relax \splittopskip = \topskip @@ -6042,6 +6200,11 @@ should work if nowhere else does.} \normaloffset = #4\relax \bindingoffset = #5\relax % + \ifpdf + \pdfpageheight #7\relax + \pdfpagewidth #8\relax + \fi + % \setleading{\textleading} % \parindent = \defaultparindent @@ -6063,7 +6226,10 @@ should work if nowhere else does.} \textleading = 13.2pt % % If page is nothing but text, make it come out even. - \internalpagesizes{46\baselineskip}{6in}{\voffset}{.25in}{\bindingoffset}{36pt}% + \internalpagesizes{46\baselineskip}{6in}% + {\voffset}{.25in}% + {\bindingoffset}{36pt}% + {11in}{8.5in}% }} % Use @smallbook to reset parameters for 7x9.5 (or so) format. @@ -6071,13 +6237,15 @@ should work if nowhere else does.} \parskip = 2pt plus 1pt \textleading = 12pt % - \internalpagesizes{7.5in}{5.in}{\voffset}{.25in}{\bindingoffset}{16pt}% + \internalpagesizes{7.5in}{5in}% + {\voffset}{.25in}% + {\bindingoffset}{16pt}% + {9.25in}{7in}% % \lispnarrowing = 0.3in \tolerance = 700 \hfuzz = 1pt \contentsrightmargin = 0pt - \deftypemargin = 0pt \defbodyindent = .5cm \smallenvironments }} @@ -6085,12 +6253,27 @@ should work if nowhere else does.} % Use @afourpaper to print on European A4 paper. \def\afourpaper{{\globaldefs = 1 \parskip = 3pt plus 2pt minus 1pt - \textleading = 12pt + \textleading = 13.2pt % - \internalpagesizes{53\baselineskip}{160mm}{\voffset}{4mm}{\bindingoffset}{44pt}% + % Double-side printing via postscript on Laserjet 4050 + % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm. + % To change the settings for a different printer or situation, adjust + % \normaloffset until the front-side and back-side texts align. Then + % do the same for \bindingoffset. You can set these for testing in + % your texinfo source file like this: + % @tex + % \global\normaloffset = -6mm + % \global\bindingoffset = 10mm + % @end tex + \internalpagesizes{51\baselineskip}{160mm} + {\voffset}{\hoffset}% + {\bindingoffset}{44pt}% + {297mm}{210mm}% % \tolerance = 700 \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = 5mm }} % Use @afivepaper to print on European A5 paper. @@ -6100,37 +6283,42 @@ should work if nowhere else does.} \parskip = 2pt plus 1pt minus 0.1pt \textleading = 12.5pt % - \internalpagesizes{166mm}{120mm}{\voffset}{-8mm}{\bindingoffset}{8pt}% + \internalpagesizes{160mm}{120mm}% + {\voffset}{\hoffset}% + {\bindingoffset}{8pt}% + {210mm}{148mm}% % \lispnarrowing = 0.2in \tolerance = 800 \hfuzz = 1.2pt - \contentsrightmargin = 0mm - \deftypemargin = 0pt + \contentsrightmargin = 0pt \defbodyindent = 2mm \tableindent = 12mm % \smallenvironments }} -% A specific text layout, 24x15cm overall, intended for A4 paper. Top margin -% 29mm, hence bottom margin 28mm, nominal side margin 3cm. +% A specific text layout, 24x15cm overall, intended for A4 paper. \def\afourlatex{{\globaldefs = 1 - \textleading = 13.6pt - % \afourpaper - \internalpagesizes{237mm}{150mm}{3.6mm}{3.6mm}{3mm}{7mm}% + \internalpagesizes{237mm}{150mm}% + {\voffset}{4.6mm}% + {\bindingoffset}{7mm}% + {297mm}{210mm}% % - % Must explicitly reset to 0 because we call \afourpaper, apparently, - % although this does not entirely make sense. + % Must explicitly reset to 0 because we call \afourpaper. \globaldefs = 0 }} -% Use @afourwide to print on European A4 paper in wide format. -\def\afourwide{% +% Use @afourwide to print on A4 paper in landscape format. +\def\afourwide{{\globaldefs = 1 \afourpaper - \internalpagesizes{6.5in}{9.5in}{\hoffset}{\normaloffset}{\bindingoffset}{7mm}% -} + \internalpagesizes{241mm}{165mm}% + {\voffset}{-2.95mm}% + {\bindingoffset}{7mm}% + {297mm}{210mm}% + \globaldefs = 0 +}} % @pagesizes TEXTHEIGHT[,TEXTWIDTH] % Perhaps we should allow setting the margins, \topskip, \parskip, @@ -6145,7 +6333,16 @@ should work if nowhere else does.} \parskip = 3pt plus 2pt minus 1pt \setleading{\textleading}% % - \internalpagesizes{#1}{\hsize}{\voffset}{\normaloffset}{\bindingoffset}{44pt}% + \dimen0 = #1 + \advance\dimen0 by \voffset + % + \dimen2 = \hsize + \advance\dimen2 by \normaloffset + % + \internalpagesizes{#1}{\hsize}% + {\voffset}{\normaloffset}% + {\bindingoffset}{44pt}% + {\dimen0}{\dimen2}% }} % Set default to letter. @@ -6269,16 +6466,8 @@ should work if nowhere else does.} @let+=@normalplus @let$=@normaldollar}%$ font-lock fix -@def@normalturnoffactive{@let"=@normaldoublequote -@let\=@normalbackslash -@let~=@normaltilde -@let^=@normalcaret -@let_=@normalunderscore -@let|=@normalverticalbar -@let<=@normalless -@let>=@normalgreater -@let+=@normalplus -@let$=@normaldollar}%$ font-lock fix +% Same as @turnoffactive except for \. +@def@normalturnoffactive{@turnoffactive @let\=@normalbackslash} % Make _ and + \other characters, temporarily. % This is canceled by @fixbackslash. diff --git a/contrib/gcc/doc/interface.texi b/contrib/gcc/doc/interface.texi index 846de56..c554434 100644 --- a/contrib/gcc/doc/interface.texi +++ b/contrib/gcc/doc/interface.texi @@ -57,7 +57,7 @@ compiler for the system. We may implement register argument passing on certain machines once we have a complete GNU system so that we can compile the libraries with GCC@. -On some machines (particularly the Sparc), certain types of arguments +On some machines (particularly the SPARC), certain types of arguments are passed ``by invisible reference''. This means that the value is stored in memory, and the address of the memory location is passed to the subroutine. diff --git a/contrib/gcc/doc/invoke.texi b/contrib/gcc/doc/invoke.texi index 62785ff..d69d896 100644 --- a/contrib/gcc/doc/invoke.texi +++ b/contrib/gcc/doc/invoke.texi @@ -9,7 +9,7 @@ Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License'' and ``Funding Free Software'', the Front-Cover texts being (a) (see below), and with @@ -66,7 +66,6 @@ for contributors to GCC@. @cindex options, GCC command @c man begin DESCRIPTION - When you invoke GCC, it normally does preprocessing, compilation, assembly and linking. The ``overall options'' allow you to stop this process at an intermediate stage. For example, the @option{-c} option @@ -155,16 +154,14 @@ in the following sections. @table @emph @item Overall Options @xref{Overall Options,,Options Controlling the Kind of Output}. -@gccoptlist{ --c -S -E -o @var{file} -pipe -pass-exit-codes -x @var{language} @gol --v -### --help --target-help --version} +@gccoptlist{-c -S -E -o @var{file} -pipe -pass-exit-codes @gol +-x @var{language} -v -### --help --target-help --version} @item C Language Options @xref{C Dialect Options,,Options Controlling C Dialect}. -@gccoptlist{ --ansi -std=@var{standard} -aux-info @var{filename} @gol --fno-asm -fno-builtin -fno-builtin-@var{function} @gol --fhosted -ffreestanding @gol +@gccoptlist{-ansi -std=@var{standard} -aux-info @var{filename} @gol +-fno-asm -fno-builtin -fno-builtin-@var{function} @gol +-fhosted -ffreestanding -fms-extensions @gol -trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol -fallow-single-precision -fcond-mismatch @gol -fsigned-bitfields -fsigned-char @gol @@ -173,9 +170,8 @@ in the following sections. @item C++ Language Options @xref{C++ Dialect Options,,Options Controlling C++ Dialect}. -@gccoptlist{ --fno-access-control -fcheck-new -fconserve-space @gol --fno-const-strings -fdollars-in-identifiers @gol +@gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol +-fconserve-space -fno-const-strings -fdollars-in-identifiers @gol -fno-elide-constructors @gol -fno-enforce-eh-specs -fexternal-templates @gol -falt-external-templates @gol @@ -187,7 +183,7 @@ in the following sections. -fno-optional-diags -fpermissive @gol -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol -fuse-cxa-atexit -fvtable-gc -fno-weak -nostdinc++ @gol --fno-default-inline -Wabi -Wctor-dtor-privacy @gol +-fno-default-inline -Wabi -Wctor-dtor-privacy @gol -Wnon-virtual-dtor -Wreorder @gol -Weffc++ -Wno-deprecated @gol -Wno-non-template-friend -Wold-style-cast @gol @@ -196,61 +192,58 @@ in the following sections. @item Objective-C Language Options @xref{Objective-C Dialect Options,,Options Controlling Objective-C Dialect}. -@gccoptlist{ --fconstant-string-class=@var{class-name} @gol +@gccoptlist{-fconstant-string-class=@var{class-name} @gol -fgnu-runtime -fnext-runtime -gen-decls @gol --Wno-protocol -Wselector} +-Wno-protocol -Wselector -Wundeclared-selector} @item Language Independent Options @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}. -@gccoptlist{ --fmessage-length=@var{n} @gol +@gccoptlist{-fmessage-length=@var{n} @gol -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}} @item Warning Options @xref{Warning Options,,Options to Request or Suppress Warnings}. -@gccoptlist{ --fsyntax-only -pedantic -pedantic-errors @gol --w -W -Wall -Waggregate-return @gol +@gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol +-w -W -Wall -Waggregate-return @gol -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol -Wconversion -Wno-deprecated-declarations @gol --Wdisabled-optimization -Wdiv-by-zero -Werror @gol +-Wdisabled-optimization -Wno-div-by-zero -Werror @gol -Wfloat-equal -Wformat -Wformat=2 @gol -Wformat-nonliteral -Wformat-security @gol -Wimplicit -Wimplicit-int @gol -Wimplicit-function-declaration @gol -Werror-implicit-function-declaration @gol --Wimport -Winline @gol +-Wimport -Winline -Wno-endif-labels @gol -Wlarger-than-@var{len} -Wlong-long @gol -Wmain -Wmissing-braces @gol -Wmissing-format-attribute -Wmissing-noreturn @gol --Wmultichar -Wno-format-extra-args -Wno-format-y2k @gol --Wno-import -Wpacked -Wpadded @gol +-Wno-multichar -Wno-format-extra-args -Wno-format-y2k @gol +-Wno-import -Wnonnull -Wpacked -Wpadded @gol -Wparentheses -Wpointer-arith -Wredundant-decls @gol -Wreturn-type -Wsequence-point -Wshadow @gol --Wsign-compare -Wswitch -Wsystem-headers @gol --Wtrigraphs -Wundef -Wuninitialized @gol +-Wsign-compare -Wstrict-aliasing @gol +-Wswitch -Wswitch-default -Wswitch-enum @gol +-Wsystem-headers -Wtrigraphs -Wundef -Wuninitialized @gol -Wunknown-pragmas -Wunreachable-code @gol -Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol -Wunused-value -Wunused-variable -Wwrite-strings} @item C-only Warning Options -@gccoptlist{ --Wbad-function-cast -Wmissing-declarations @gol +@gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol -Wmissing-prototypes -Wnested-externs @gol -Wstrict-prototypes -Wtraditional} @item Debugging Options @xref{Debugging Options,,Options for Debugging Your Program or GCC}. -@gccoptlist{ --d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol --fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol +@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol +-fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol --fdump-tree-original@r{[}-@var{n}@r{]} -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol +-fdump-tree-original@r{[}-@var{n}@r{]} @gol +-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol --fmem-report -fpretend-float @gol --fprofile-arcs -fsched-verbose=@var{n} @gol --ftest-coverage -ftime-report @gol +-feliminate-dwarf2-dups -fmem-report @gol +-fprofile-arcs -frandom-seed=@var{n} @gol +-fsched-verbose=@var{n} -ftest-coverage -ftime-report @gol -g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2 @gol -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol @@ -260,40 +253,41 @@ in the following sections. @item Optimization Options @xref{Optimize Options,,Options that Control Optimization}. -@gccoptlist{ --falign-functions=@var{n} -falign-jumps=@var{n} @gol +@gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol -falign-labels=@var{n} -falign-loops=@var{n} @gol --fbounds-check @gol --fbranch-probabilities -fcaller-saves -fcprop-registers @gol +-fbranch-probabilities -fcaller-saves -fcprop-registers @gol -fcse-follow-jumps -fcse-skip-blocks -fdata-sections @gol -fdelayed-branch -fdelete-null-pointer-checks @gol -fexpensive-optimizations -ffast-math -ffloat-store @gol -fforce-addr -fforce-mem -ffunction-sections @gol --fgcse -fgcse-lm -fgcse-sm @gol +-fgcse -fgcse-lm -fgcse-sm -floop-optimize -fcrossjumping @gol +-fif-conversion -fif-conversion2 @gol -finline-functions -finline-limit=@var{n} -fkeep-inline-functions @gol -fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol --fmove-all-movables -fno-branch-count-reg @gol +-fmove-all-movables -fnew-ra -fno-branch-count-reg @gol -fno-default-inline -fno-defer-pop @gol -fno-function-cse -fno-guess-branch-probability @gol -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol --funsafe-math-optimizations -fno-trapping-math @gol +-funsafe-math-optimizations -ffinite-math-only @gol +-fno-trapping-math -fno-zero-initialized-in-bss @gol -fomit-frame-pointer -foptimize-register-move @gol -foptimize-sibling-calls -fprefetch-loop-arrays @gol --freduce-all-givs -fregmove -frename-registers @gol +-freduce-all-givs -fregmove -frename-registers @gol +-freorder-blocks -freorder-functions @gol -frerun-cse-after-loop -frerun-loop-opt @gol -fschedule-insns -fschedule-insns2 @gol --fno-sched-interblock -fno-sched-spec @gol --fsched-spec-load -fsched-spec-load-dangerous @gol --fsingle-precision-constant -fssa -fssa-ccp -fssa-dce @gol --fstrength-reduce -fstrict-aliasing -fthread-jumps @gol --ftrapv -funroll-all-loops -funroll-loops @gol ---param @var{name}=@var{value} +-fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol +-fsched-spec-load-dangerous -fsignaling-nans @gol +-fsingle-precision-constant -fssa -fssa-ccp -fssa-dce @gol +-fstrength-reduce -fstrict-aliasing -ftracer -fthread-jumps @gol +-funroll-all-loops -funroll-loops @gol +--param @var{name}=@var{value} @gol -O -O0 -O1 -O2 -O3 -Os} @item Preprocessor Options @xref{Preprocessor Options,,Options Controlling the Preprocessor}. -@gccoptlist{ --$ -A@var{question}=@var{answer} -A-@var{question}@r{[}=@var{answer}@r{]} @gol +@gccoptlist{-$ -A@var{question}=@var{answer} @gol +-A-@var{question}@r{[}=@var{answer}@r{]} @gol -C -dD -dI -dM -dN @gol -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol -idirafter @var{dir} @gol @@ -305,13 +299,11 @@ in the following sections. @item Assembler Option @xref{Assembler Options,,Passing Options to the Assembler}. -@gccoptlist{ --Wa,@var{option}} +@gccoptlist{-Wa,@var{option}} @item Linker Options @xref{Link Options,,Options for Linking}. -@gccoptlist{ -@var{object-file-name} -l@var{library} @gol +@gccoptlist{@var{object-file-name} -l@var{library} @gol -nostartfiles -nodefaultlibs -nostdlib @gol -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol -Wl,@var{option} -Xlinker @var{option} @gol @@ -319,37 +311,32 @@ in the following sections. @item Directory Options @xref{Directory Options,,Options for Directory Search}. -@gccoptlist{ --B@var{prefix} -I@var{dir} -I- -L@var{dir} -specs=@var{file}} +@gccoptlist{-B@var{prefix} -I@var{dir} -I- -L@var{dir} -specs=@var{file}} @item Target Options @c I wrote this xref this way to avoid overfull hbox. -- rms @xref{Target Options}. -@gccoptlist{ --b @var{machine} -V @var{version}} +@gccoptlist{-V @var{version} -b @var{machine}} @item Machine Dependent Options @xref{Submodel Options,,Hardware Models and Configurations}. @emph{M680x0 Options} -@gccoptlist{ --m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol +@gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol -m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020 @gol -mfpa -mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol -malign-int -mstrict-align} @emph{M68hc1x Options} -@gccoptlist{ --m6811 -m6812 -m68hc11 -m68hc12 @gol --mauto-incdec -mshort -msoft-reg-count=@var{count}} +@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol +-mauto-incdec -minmax -mlong-calls -mshort @gol +-msoft-reg-count=@var{count}} @emph{VAX Options} -@gccoptlist{ --mg -mgnu -munix} +@gccoptlist{-mg -mgnu -munix} @emph{SPARC Options} -@gccoptlist{ --mcpu=@var{cpu-type} @gol +@gccoptlist{-mcpu=@var{cpu-type} @gol -mtune=@var{cpu-type} @gol -mcmodel=@var{code-model} @gol -m32 -m64 @gol @@ -362,25 +349,8 @@ in the following sections. -msoft-float -msoft-quad-float -msparclite -mstack-bias @gol -msupersparc -munaligned-doubles -mv8} -@emph{Convex Options} -@gccoptlist{ --mc1 -mc2 -mc32 -mc34 -mc38 @gol --margcount -mnoargcount @gol --mlong32 -mlong64 @gol --mvolatile-cache -mvolatile-nocache} - -@emph{AMD29K Options} -@gccoptlist{ --m29000 -m29050 -mbw -mnbw -mdw -mndw @gol --mlarge -mnormal -msmall @gol --mkernel-registers -mno-reuse-arg-regs @gol --mno-stack-check -mno-storem-bug @gol --mreuse-arg-regs -msoft-float -mstack-check @gol --mstorem-bug -muser-registers} - @emph{ARM Options} -@gccoptlist{ --mapcs-frame -mno-apcs-frame @gol +@gccoptlist{-mapcs-frame -mno-apcs-frame @gol -mapcs-26 -mapcs-32 @gol -mapcs-stack-check -mno-apcs-stack-check @gol -mapcs-float -mno-apcs-float @gol @@ -392,7 +362,6 @@ in the following sections. -mthumb-interwork -mno-thumb-interwork @gol -mcpu=@var{name} -march=@var{name} -mfpe=@var{name} @gol -mstructure-size-boundary=@var{n} @gol --mbsd -mxopen -mno-symrename @gol -mabort-on-noreturn @gol -mlong-calls -mno-long-calls @gol -msingle-pic-base -mno-single-pic-base @gol @@ -401,26 +370,22 @@ in the following sections. -mpoke-function-name @gol -mthumb -marm @gol -mtpcs-frame -mtpcs-leaf-frame @gol --mcaller-super-interworking -mcallee-super-interworking } +-mcaller-super-interworking -mcallee-super-interworking} @emph{MN10200 Options} -@gccoptlist{ --mrelax} +@gccoptlist{-mrelax} @emph{MN10300 Options} -@gccoptlist{ --mmult-bug -mno-mult-bug @gol +@gccoptlist{-mmult-bug -mno-mult-bug @gol -mam33 -mno-am33 @gol -mno-crt0 -mrelax} @emph{M32R/D Options} -@gccoptlist{ --m32rx -m32r -mcode-model=@var{model-type} -msdata=@var{sdata-type} @gol --G @var{num}} +@gccoptlist{-m32rx -m32r -mcode-model=@var{model-type} @gol +-msdata=@var{sdata-type} -G @var{num}} @emph{M88K Options} -@gccoptlist{ --m88000 -m88100 -m88110 -mbig-pic @gol +@gccoptlist{-m88000 -m88100 -m88110 -mbig-pic @gol -mcheck-zero-division -mhandle-large-shift @gol -midentify-revision -mno-check-zero-division @gol -mno-ocs-debug-info -mno-ocs-frame-position @gol @@ -432,12 +397,11 @@ in the following sections. -mversion-03.00 -mwarn-passed-structs} @emph{RS/6000 and PowerPC Options} -@gccoptlist{ --mcpu=@var{cpu-type} @gol +@gccoptlist{-mcpu=@var{cpu-type} @gol -mtune=@var{cpu-type} @gol -mpower -mno-power -mpower2 -mno-power2 @gol -mpowerpc -mpowerpc64 -mno-powerpc @gol --maltivec -mno-altivec @gol +-maltivec -mno-altivec @gol -mpowerpc-gpopt -mno-powerpc-gpopt @gol -mpowerpc-gfxopt -mno-powerpc-gfxopt @gol -mnew-mnemonics -mold-mnemonics @gol @@ -448,24 +412,46 @@ in the following sections. -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol -mstrict-align -mno-strict-align -mrelocatable @gol -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol --mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol --mcall-aix -mcall-sysv -mcall-netbsd @gol --maix-struct-return -msvr4-struct-return @gol --mabi=altivec -mabi=no-altivec @gol +-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol +-mcall-aix -mcall-sysv -mcall-netbsd @gol +-maix-struct-return -msvr4-struct-return @gol +-mabi=altivec -mabi=no-altivec @gol +-mabi=spe -mabi=no-spe @gol +-misel=yes -misel=no @gol -mprototype -mno-prototype @gol --msim -mmvme -mads -myellowknife -memb -msdata @gol --msdata=@var{opt} -mvxworks -G @var{num} -pthread} +-msim -mmvme -mads -myellowknife -memb -msdata @gol +-msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread} -@emph{RT Options} +@emph{Darwin Options} @gccoptlist{ --mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs @gol +-all_load -allowable_client -arch -arch_errors_fatal @gol +-arch_only -bind_at_load -bundle -bundle_loader @gol +-client_name -compatibility_version -current_version @gol +-dependency-file -dylib_file -dylinker_install_name @gol +-dynamic -dynamiclib -exported_symbols_list @gol +-filelist -flat_namespace -force_cpusubtype_ALL @gol +-force_flat_namespace -headerpad_max_install_names @gol +-image_base -init -install_name -keep_private_externs @gol +-multi_module -multiply_defined -multiply_defined_unused @gol +-noall_load -nomultidefs -noprebind -noseglinkedit @gol +-pagezero_size -prebind -prebind_all_twolevel_modules @gol +-private_bundle -read_only_relocs -sectalign @gol +-sectobjectsymbols -whyload -seg1addr @gol +-sectcreate -sectobjectsymbols -sectorder @gol +-seg_addr_table -seg_addr_table_filename -seglinkedit @gol +-segprot -segs_read_only_addr -segs_read_write_addr @gol +-single_module -static -sub_library -sub_umbrella @gol +-twolevel_namespace -umbrella -undefined @gol +-unexported_symbols_list -weak_reference_mismatches -whatsloaded} + +@emph{RT Options} +@gccoptlist{-mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs @gol -mfull-fp-blocks -mhc-struct-return -min-line-mul @gol -mminimum-fp-blocks -mnohc-struct-return} @emph{MIPS Options} -@gccoptlist{ --mabicalls -march=@var{cpu-type} -mtune=@var{cpu=type} @gol --mcpu=@var{cpu-type} -membedded-data -muninit-const-in-rodata @gol +@gccoptlist{-mabicalls -march=@var{cpu-type} -mtune=@var{cpu=type} @gol +-mcpu=@var{cpu-type} -membedded-data -muninit-const-in-rodata @gol -membedded-pic -mfp32 -mfp64 -mfused-madd -mno-fused-madd @gol -mgas -mgp32 -mgp64 @gol -mgpopt -mhalf-pic -mhard-float -mint64 -mips1 @gol @@ -478,39 +464,39 @@ in the following sections. -m4650 -msingle-float -mmad @gol -mstats -EL -EB -G @var{num} -nocpp @gol -mabi=32 -mabi=n32 -mabi=64 -mabi=eabi @gol --mfix7000 -mno-crt0 -mflush-func=@var{func} -mno-flush-func} +-mfix7000 -mno-crt0 -mflush-func=@var{func} -mno-flush-func @gol +-mbranch-likely -mno-branch-likely} @emph{i386 and x86-64 Options} -@gccoptlist{ --mcpu=@var{cpu-type} -march=@var{cpu-type} -mfpmath=@var{unit} @gol --masm=@var{dialect} -mno-fancy-math-387 @gol +@gccoptlist{-mcpu=@var{cpu-type} -march=@var{cpu-type} @gol +-mfpmath=@var{unit} -masm=@var{dialect} -mno-fancy-math-387 @gol -mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol -mno-wide-multiply -mrtd -malign-double @gol -mpreferred-stack-boundary=@var{num} @gol --mmmx -msse -msse2 -m3dnow @gol +-mmmx -msse -msse2 -m3dnow @gol -mthreads -mno-align-stringops -minline-all-stringops @gol -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol -m96bit-long-double -mregparm=@var{num} -momit-leaf-frame-pointer @gol -mno-red-zone@gol -mcmodel=@var{code-model} @gol --m32 -m64} +-m32 -m64} @emph{HPPA Options} -@gccoptlist{ --march=@var{architecture-type} @gol +@gccoptlist{-march=@var{architecture-type} @gol -mbig-switch -mdisable-fpregs -mdisable-indexing @gol --mfast-indirect-calls -mgas -mjump-in-delay @gol +-mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol +-mjump-in-delay -mlinker-opt -mlong-calls @gol -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol -mno-jump-in-delay -mno-long-load-store @gol -mno-portable-runtime -mno-soft-float @gol -mno-space-regs -msoft-float -mpa-risc-1-0 @gol -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol --mschedule=@var{cpu-type} -mspace-regs} +-mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol +-nolibdld -static -threads} @emph{Intel 960 Options} -@gccoptlist{ --m@var{cpu-type} -masm-compat -mclean-linkage @gol +@gccoptlist{-m@var{cpu-type} -masm-compat -mclean-linkage @gol -mcode-align -mcomplex-addr -mleaf-procedures @gol -mic-compat -mic2.0-compat -mic3.0-compat @gol -mintel-asm -mno-clean-linkage -mno-code-align @gol @@ -520,8 +506,7 @@ in the following sections. -mtail-call} @emph{DEC Alpha Options} -@gccoptlist{ --mno-fp-regs -msoft-float -malpha-as -mgas @gol +@gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol -mieee -mieee-with-inexact -mieee-conformant @gol -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol -mtrap-precision=@var{mode} -mbuild-constants @gol @@ -532,111 +517,96 @@ in the following sections. -mmemory-latency=@var{time}} @emph{DEC Alpha/VMS Options} -@gccoptlist{ --mvms-return-codes} - -@emph{Clipper Options} -@gccoptlist{ --mc300 -mc400} +@gccoptlist{-mvms-return-codes} @emph{H8/300 Options} -@gccoptlist{ --mrelax -mh -ms -mint32 -malign-300} +@gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300} @emph{SH Options} -@gccoptlist{ --m1 -m2 -m3 -m3e @gol +@gccoptlist{-m1 -m2 -m3 -m3e @gol -m4-nofpu -m4-single-only -m4-single -m4 @gol --m5-64media -m5-64media-nofpu @gol --m5-32media -m5-32media-nofpu @gol --m5-compact -m5-compact-nofpu @gol +-m5-64media -m5-64media-nofpu @gol +-m5-32media -m5-32media-nofpu @gol +-m5-compact -m5-compact-nofpu @gol -mb -ml -mdalign -mrelax @gol -mbigtable -mfmovd -mhitachi -mnomacsave @gol -mieee -misize -mpadstruct -mspace @gol -mprefergot -musermode} @emph{System V Options} -@gccoptlist{ --Qy -Qn -YP,@var{paths} -Ym,@var{dir}} +@gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}} @emph{ARC Options} -@gccoptlist{ --EB -EL @gol +@gccoptlist{-EB -EL @gol -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol -mdata=@var{data-section} -mrodata=@var{readonly-data-section}} @emph{TMS320C3x/C4x Options} -@gccoptlist{ --mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol +@gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol -mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol -mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol -mparallel-insns -mparallel-mpy -mpreserve-float} @emph{V850 Options} -@gccoptlist{ --mlong-calls -mno-long-calls -mep -mno-ep @gol +@gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol -mprolog-function -mno-prolog-function -mspace @gol -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol +-mapp-regs -mno-app-regs @gol +-mdisable-callt -mno-disable-callt @gol +-mv850e @gol -mv850 -mbig-switch} @emph{NS32K Options} -@gccoptlist{ --m32032 -m32332 -m32532 -m32081 -m32381 @gol +@gccoptlist{-m32032 -m32332 -m32532 -m32081 -m32381 @gol -mmult-add -mnomult-add -msoft-float -mrtd -mnortd @gol -mregparam -mnoregparam -msb -mnosb @gol -mbitfield -mnobitfield -mhimem -mnohimem} @emph{AVR Options} -@gccoptlist{ --mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol +@gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol -mcall-prologues -mno-tablejump -mtiny-stack} @emph{MCore Options} -@gccoptlist{ --mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol +@gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol -m4byte-functions -mno-4byte-functions -mcallgraph-data @gol -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment} @emph{MMIX Options} -@gccoptlist{ --mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol --mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol --melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol --mno-base-addresses} +@gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol +-mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol +-melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol +-mno-base-addresses -msingle-exit -mno-single-exit} @emph{IA-64 Options} -@gccoptlist{ --mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol +@gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol -mvolatile-asm-stop -mb-step -mregister-names -mno-sdata @gol --mconstant-gp -mauto-pic -minline-divide-min-latency @gol --minline-divide-max-throughput -mno-dwarf2-asm @gol +-mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol +-minline-float-divide-max-throughput @gol +-minline-int-divide-min-latency @gol +-minline-int-divide-max-throughput -mno-dwarf2-asm @gol -mfixed-range=@var{register-range}} @emph{D30V Options} -@gccoptlist{ --mextmem -mextmemory -monchip -mno-asm-optimize @gol --masm-optimize -mbranch-cost=@var{n} -mcond-exec=@var{n}} +@gccoptlist{-mextmem -mextmemory -monchip -mno-asm-optimize @gol +-masm-optimize -mbranch-cost=@var{n} -mcond-exec=@var{n}} @emph{S/390 and zSeries Options} -@gccoptlist{ --mhard-float -msoft-float -mbackchain -mno-backchain @gol --msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol --m64 -m31 -mdebug -mno-debug} +@gccoptlist{-mhard-float -msoft-float -mbackchain -mno-backchain @gol +-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol +-m64 -m31 -mdebug -mno-debug} @emph{CRIS Options} -@gccoptlist{ --mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol --mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol --metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol --mstack-align -mdata-align -mconst-align @gol --m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol --melf -maout -melinux -mlinux -sim -sim2} +@gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol +-mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol +-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol +-mstack-align -mdata-align -mconst-align @gol +-m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol +-melf -maout -melinux -mlinux -sim -sim2} @emph{PDP-11 Options} -@gccoptlist{ --mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol +@gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol -mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol -mint16 -mno-int32 -mfloat32 -mno-float64 @gol -mfloat64 -mno-float32 -mabshi -mno-abshi @gol @@ -644,44 +614,57 @@ in the following sections. -msplit -mno-split -munix-asm -mdec-asm} @emph{Xstormy16 Options} -@gccoptlist{ --msim} +@gccoptlist{-msim} @emph{Xtensa Options} -@gccoptlist{ --mbig-endian -mlittle-endian @gol --mdensity -mno-density @gol --mmac16 -mno-mac16 @gol --mmul16 -mno-mul16 @gol --mmul32 -mno-mul32 @gol --mnsa -mno-nsa @gol --mminmax -mno-minmax @gol --msext -mno-sext @gol --mbooleans -mno-booleans @gol --mhard-float -msoft-float @gol --mfused-madd -mno-fused-madd @gol --mserialize-volatile -mno-serialize-volatile @gol --mtext-section-literals -mno-text-section-literals @gol --mtarget-align -mno-target-align @gol --mlongcalls -mno-longcalls} +@gccoptlist{-mbig-endian -mlittle-endian @gol +-mdensity -mno-density @gol +-mmac16 -mno-mac16 @gol +-mmul16 -mno-mul16 @gol +-mmul32 -mno-mul32 @gol +-mnsa -mno-nsa @gol +-mminmax -mno-minmax @gol +-msext -mno-sext @gol +-mbooleans -mno-booleans @gol +-mhard-float -msoft-float @gol +-mfused-madd -mno-fused-madd @gol +-mserialize-volatile -mno-serialize-volatile @gol +-mtext-section-literals -mno-text-section-literals @gol +-mtarget-align -mno-target-align @gol +-mlongcalls -mno-longcalls} + +@emph{FRV Options} +@gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol +-mhard-float -msoft-float -malloc-cc -mfixed-cc @gol +-mdword -mno-dword -mdouble -mno-double @gol +-mmedia -mno-media -mmuladd -mno-muladd -mlibrary-pic @gol +-macc-4 -macc-8 -mpack -mno-pack -mno-eflags @gol +-mcond-move -mno-cond-move -mscc -mno-scc @gol +-mcond-exec -mno-cond-exec -mvliw-branch -mno-vliw-branch @gol +-mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol +-mno-nested-cond-exec -mtomcat-stats @gol +-mcpu=@var{cpu}} + + @item Code Generation Options @xref{Code Gen Options,,Options for Code Generation Conventions}. -@gccoptlist{ --fcall-saved-@var{reg} -fcall-used-@var{reg} @gol --ffixed-@var{reg} -fexceptions @gol +@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol +-ffixed-@var{reg} -fexceptions @gol -fnon-call-exceptions -funwind-tables @gol -fasynchronous-unwind-tables @gol -finhibit-size-directive -finstrument-functions @gol -fno-common -fno-ident -fno-gnu-linker @gol -fpcc-struct-return -fpic -fPIC @gol -freg-struct-return -fshared-data -fshort-enums @gol --fshort-double -fshort-wchar -fvolatile @gol +-fshort-double -fshort-wchar -fvolatile @gol -fvolatile-global -fvolatile-static @gol -fverbose-asm -fpack-struct -fstack-check @gol -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol -fargument-alias -fargument-noalias @gol --fargument-noalias-global -fleading-underscore} +-fargument-noalias-global -fleading-underscore @gol +-ftls-model=@var{model} @gol +-ftrapv -fbounds-check} @end table @menu @@ -818,6 +801,7 @@ assembler assembler-with-cpp ada f77 f77-cpp-input ratfor java +treelang @end example @item -x none @@ -974,11 +958,11 @@ from C, such as C++ and Objective-C) that the compiler accepts: @cindex ISO support @item -ansi @opindex ansi -In C mode, support all ISO C89 programs. In C++ mode, +In C mode, support all ISO C90 programs. In C++ mode, remove GNU extensions that conflict with ISO C++. This turns off certain features of GCC that are incompatible with ISO -C89 (when compiling C code), or of standard C++ (when compiling C++ code), +C90 (when compiling C code), or of standard C++ (when compiling C++ code), such as the @code{asm} and @code{typeof} keywords, and predefined macros such as @code{unix} and @code{vax} that identify the type of system you are using. It also enables the undesirable and @@ -1013,33 +997,39 @@ affected. @item -std= @opindex std Determine the language standard. This option is currently only -supported when compiling C@. A value for this option must be provided; -possible values are +supported when compiling C or C++. A value for this option must be +provided; possible values are @table @samp @item c89 @itemx iso9899:1990 -ISO C89 (same as @option{-ansi}). +ISO C90 (same as @option{-ansi}). @item iso9899:199409 -ISO C89 as modified in amendment 1. +ISO C90 as modified in amendment 1. @item c99 @itemx c9x @itemx iso9899:1999 @itemx iso9899:199x ISO C99. Note that this standard is not yet fully supported; see -@w{@uref{http://gcc.gnu.org/gcc-3.1/c99status.html}} for more information. The +@w{@uref{http://gcc.gnu.org/gcc-3.3/c99status.html}} for more information. The names @samp{c9x} and @samp{iso9899:199x} are deprecated. @item gnu89 -Default, ISO C89 plus GNU extensions (including some C99 features). +Default, ISO C90 plus GNU extensions (including some C99 features). @item gnu99 @item gnu9x ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC, this will become the default. The name @samp{gnu9x} is deprecated. +@item c++98 +The 1998 ISO C++ standard plus amendments. + +@item gnu++98 +The same as @option{-std=c++98} plus GNU extensions. This is the +default for C++ code. @end table Even when this option is not specified, you can still use some of the @@ -1048,7 +1038,7 @@ previous C standards. For example, you may use @code{__restrict__} even when @option{-std=c99} is not specified. The @option{-std} options specifying some version of ISO C have the same -effects as @option{-ansi}, except that features that were not in ISO C89 +effects as @option{-ansi}, except that features that were not in ISO C90 but are in the specified version (for example, @samp{//} comments and the @code{inline} keyword in ISO C99) are not disabled. @@ -1086,7 +1076,7 @@ switch only affects the @code{asm} and @code{typeof} keywords, since @code{inline} is a standard keyword in ISO C99. @item -fno-builtin -@itemx -fno-builtin-@var{function} @r{(C and Objective-C only)} +@itemx -fno-builtin-@var{function} @opindex fno-builtin @cindex built-in functions Don't recognize built-in functions that do not begin with @@ -1104,15 +1094,8 @@ and faster, but since the function calls no longer appear as such, you cannot set a breakpoint on those calls, nor can you change the behavior of the functions by linking with a different library. -In C++, @option{-fno-builtin} is always in effect. The @option{-fbuiltin} -option has no effect. Therefore, in C++, the only way to get the -optimization benefits of built-in functions is to call the function -using the @samp{__builtin_} prefix. The GNU C++ Standard Library uses -built-in functions to implement many functions (like -@code{std::strchr}), so that you automatically get efficient code. - -With the @option{-fno-builtin-@var{function}} option, not available -when compiling C++, only the built-in function @var{function} is +With the @option{-fno-builtin-@var{function}} option +only the built-in function @var{function} is disabled. @var{function} must not begin with @samp{__builtin_}. If a function is named this is not built-in in this version of GCC, this option is ignored. There is no corresponding @@ -1148,6 +1131,10 @@ This is equivalent to @option{-fno-hosted}. @xref{Standards,,Language Standards Supported by GCC}, for details of freestanding and hosted environments. +@item -fms-extensions +@opindex fms-extensions +Accept some non-standard constructs used in Microsoft header files. + @item -trigraphs @opindex trigraphs Support ISO C trigraphs. The @option{-ansi} option (and @option{-std} @@ -1155,86 +1142,25 @@ options for strict ISO C conformance) implies @option{-trigraphs}. @item -no-integrated-cpp @opindex no-integrated-cpp -Invoke the external cpp during compilation. The default is to use the -integrated cpp (internal cpp). This option also allows a -user-supplied cpp via the @option{-B} option. This flag is applicable -in both C and C++ modes. +Performs a compilation in two passes: preprocessing and compiling. This +option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the +@option{-B} option. The user supplied compilation step can then add in +an additional preprocessing step after normal preprocessing but before +compiling. The default is to use the integrated cpp (internal cpp) -We do not guarantee to retain this option in future, and we may change -its semantics. +The semantics of this option will change if "cc1", "cc1plus", and +"cc1obj" are merged. @cindex traditional C language @cindex C language, traditional @item -traditional -@opindex traditional -Attempt to support some aspects of traditional C compilers. -Specifically: - -@itemize @bullet -@item -All @code{extern} declarations take effect globally even if they -are written inside of a function definition. This includes implicit -declarations of functions. - -@item -The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const} -and @code{volatile} are not recognized. (You can still use the -alternative keywords such as @code{__typeof__}, @code{__inline__}, and -so on.) - -@item -Comparisons between pointers and integers are always allowed. - -@item -Integer types @code{unsigned short} and @code{unsigned char} promote -to @code{unsigned int}. - -@item -Out-of-range floating point literals are not an error. - -@item -Certain constructs which ISO regards as a single invalid preprocessing -number, such as @samp{0xe-0xd}, are treated as expressions instead. - -@item -String ``constants'' are not necessarily constant; they are stored in -writable space, and identical looking constants are allocated -separately. (This is the same as the effect of -@option{-fwritable-strings}.) - -@cindex @code{longjmp} and automatic variables -@item -All automatic variables not declared @code{register} are preserved by -@code{longjmp}. Ordinarily, GNU C follows ISO C: automatic variables -not declared @code{volatile} may be clobbered. - -@item -@cindex @samp{\x} -@cindex @samp{\a} -@cindex escape sequences, traditional -The character escape sequences @samp{\x} and @samp{\a} evaluate as the -literal characters @samp{x} and @samp{a} respectively. Without -@w{@option{-traditional}}, @samp{\x} is a prefix for the hexadecimal -representation of a character, and @samp{\a} produces a bell. -@end itemize - -This option is deprecated and may be removed. - -You may wish to use @option{-fno-builtin} as well as @option{-traditional} -if your program uses names that are normally GNU C built-in functions for -other purposes of its own. - -You cannot use @option{-traditional} if you include any header files that -rely on ISO C features. Some vendors are starting to ship systems with -ISO C header files and you cannot use @option{-traditional} on such -systems to compile files that include any system headers. - -The @option{-traditional} option also enables @option{-traditional-cpp}. - -@item -traditional-cpp +@itemx -traditional-cpp @opindex traditional-cpp -Attempt to support some aspects of traditional C preprocessors. -See the GNU CPP manual for details. +@opindex traditional +Formerly, these options caused GCC to attempt to emulate a pre-standard +C compiler. They are now only supported with the @option{-E} switch. +The preprocessor continues to support a pre-standard mode. See the GNU +CPP manual for details. @item -fcond-mismatch @opindex fcond-mismatch @@ -1282,31 +1208,14 @@ declaration does not use either @code{signed} or @code{unsigned}. By default, such a bit-field is signed, because this is consistent: the basic integer types such as @code{int} are signed types. -However, when @option{-traditional} is used, bit-fields are all unsigned -no matter what. - @item -fwritable-strings @opindex 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. The option @option{-traditional} also has -this effect. +write into string constants. Writing into string constants is a very bad idea; ``constants'' should be constant. - -@item -fallow-single-precision -@opindex fallow-single-precision -Do not promote single precision math operations to double precision, -even when compiling with @option{-traditional}. - -Traditional K&R C promotes all floating point operations to double -precision, regardless of the sizes of the operands. On the -architecture for which you are compiling, single precision may be faster -than double precision. If you must use @option{-traditional}, but want -to use single precision operations when the operands are single -precision, use this option. This option has no effect when compiling -with ISO or GNU C conventions (the default). @end table @node C++ Dialect Options @@ -1332,6 +1241,17 @@ language supported by GCC@. Here is a list of options that are @emph{only} for compiling C++ programs: @table @gcctabopt + +@item -fabi-version=@var{n} +@opindex fabi-version +Use version @var{n} of the C++ ABI. Version 1 is the version of the C++ +ABI that first appeared in G++ 3.2. Version 0 will always be the +version that conforms most closely to the C++ ABI specification. +Therefore, the ABI obtained using version 0 will change as ABI bugs are +fixed. + +The default is version 1. + @item -fno-access-control @opindex fno-access-control Turn off all access checking. This switch is mainly useful for working @@ -1340,14 +1260,14 @@ around bugs in the access control code. @item -fcheck-new @opindex fcheck-new Check that the pointer returned by @code{operator new} is non-null -before attempting to modify the storage allocated. The current Working -Paper requires that @code{operator new} never return a null pointer, so -this check is normally unnecessary. - -An alternative to using this option is to specify that your -@code{operator new} does not throw any exceptions; if you declare it -@samp{throw()}, G++ will check the return value. See also @samp{new -(nothrow)}. +before attempting to modify the storage allocated. This check is +normally unnecessary because the C++ standard specifies that +@code{operator new} will only return @code{0} if it is declared +@samp{throw()}, in which case the compiler will always check the +return value even without this option. In all other cases, when +@code{operator new} has a non-empty exception specification, memory +exhaustion is signalled by throwing @code{std::bad_alloc}. See also +@samp{new (nothrow)}. @item -fconserve-space @opindex fconserve-space @@ -1478,10 +1398,9 @@ a name having multiple meanings within a class. @item -fpermissive @opindex fpermissive -Downgrade messages about nonconformant code from errors to warnings. By -default, G++ effectively sets @option{-pedantic-errors} without -@option{-pedantic}; this option reverses that. This behavior and this -option are superseded by @option{-pedantic}, which works as it does for GNU C@. +Downgrade some diagnostics about nonconformant code from errors to +warnings. Thus, using @option{-fpermissive} will allow some +nonconforming code to compile. @item -frepo @opindex frepo @@ -1568,7 +1487,7 @@ You should rewrite your code to avoid these warnings if you are concerned about the fact that code generated by G++ may not be binary compatible with code generated by other compilers. -The known incompatibilites at this point include: +The known incompatibilities at this point include: @itemize @bullet @@ -1605,18 +1524,66 @@ explicitly padding @code{A} so that its size is a multiple of its alignment (ignoring virtual base classes); that will cause G++ and other compilers to layout @code{C} identically. +@item +Incorrect handling of bit-fields with declared widths greater than that +of their underlying types, when the bit-fields appear in a union. For +example: + +@smallexample +union U @{ int i : 4096; @}; +@end smallexample + +@noindent +Assuming that an @code{int} does not have 4096 bits, G++ will make the +union too small by the number of bits in an @code{int}. + +@item +Empty classes can be placed at incorrect offsets. For example: + +@smallexample +struct A @{@}; + +struct B @{ + A a; + virtual void f (); +@}; + +struct C : public B, public A @{@}; +@end smallexample + +@noindent +G++ will place the @code{A} base class of @code{C} at a nonzero offset; +it should be placed at offset zero. G++ mistakenly believes that the +@code{A} data member of @code{B} is already at offset zero. + +@item +Names of template functions whose types involve @code{typename} or +template template parameters can be mangled incorrectly. + +@smallexample +template <typename Q> +void f(typename Q::X) @{@} + +template <template <typename> class Q> +void f(typename Q<int>::X) @{@} +@end smallexample + +@noindent +Instantiations of these templates may be mangled incorrectly. + @end itemize @item -Wctor-dtor-privacy @r{(C++ only)} @opindex Wctor-dtor-privacy Warn when a class seems unusable, because all the constructors or destructors in a class are private and the class has no friends or -public static member functions. +public static member functions. This warning is enabled by default. @item -Wnon-virtual-dtor @r{(C++ only)} @opindex Wnon-virtual-dtor Warn when a class declares a non-virtual destructor that should probably be virtual, because it looks like the class will be used polymorphically. +This warning is enabled by @option{-Wall}. @item -Wreorder @r{(C++ only)} @opindex Wreorder @@ -1635,7 +1602,7 @@ struct A @{ Here the compiler will warn that the member initializers for @samp{i} and @samp{j} will be rearranged to match the declaration order of the -members. +members. This warning is enabled by @option{-Wall}. @end table The following @option{-W@dots{}} options are not affected by @option{-Wall}. @@ -1810,7 +1777,9 @@ runtime. This is the default for most types of systems. @item -fnext-runtime @opindex fnext-runtime Generate output compatible with the NeXT runtime. This is the default -for NeXT-based systems, including Darwin and Mac OS X@. +for NeXT-based systems, including Darwin and Mac OS X@. The macro +@code{__NEXT_RUNTIME__} is predefined if (and only if) this option is +used. @item -gen-decls @opindex gen-decls @@ -1819,12 +1788,39 @@ file named @file{@var{sourcename}.decl}. @item -Wno-protocol @opindex Wno-protocol -Do not warn if methods required by a protocol are not implemented -in the class adopting it. +If a class is declared to implement a protocol, a warning is issued for +every method in the protocol that is not implemented by the class. The +default behavior is to issue a warning for every method not explicitly +implemented in the class, even if a method implementation is inherited +from the superclass. If you use the @code{-Wno-protocol} option, then +methods inherited from the superclass are considered to be implemented, +and no warning is issued for them. @item -Wselector @opindex Wselector -Warn if a selector has multiple methods of different types defined. +Warn if multiple methods of different types for the same selector are +found during compilation. The check is performed on the list of methods +in the final stage of compilation. Additionally, a check is performed +that for each selector appearing in a @code{@@selector(@dots{})} +expression, a corresponding method with that selector has been found +during compilation. Because these checks scan the method table only at +the end of compilation, these warnings are not produced if the final +stage of compilation is not reached, for example because an error is +found during compilation, or because the @code{-fsyntax-only} option is +being used. + +@item -Wundeclared-selector +@opindex Wundeclared-selector +Warn if a @code{@@selector(@dots{})} expression referring to an +undeclared selector is found. A selector is considered undeclared if no +method with that name has been declared (explicitly, in an +@code{@@interface} or @code{@@protocol} declaration, or implicitly, in +an @code{@@implementation} section) before the +@code{@@selector(@dots{})} expression. This option always performs its +checks as soon as a @code{@@selector(@dots{})} expression is found +(while @code{-Wselector} only performs its checks in the final stage of +compilation), and so additionally enforces the coding style convention +that methods and selectors must be declared before being used. @c not documented because only avail via -Wp @c @item -print-objc-runtime-info @@ -1975,7 +1971,7 @@ attributes (@pxref{Function Attributes}), in the @code{printf}, not in the C standard) families. The formats are checked against the format features supported by GNU -libc version 2.2. These include all ISO C89 and C99 features, as well +libc version 2.2. These include all ISO C90 and C99 features, as well as features from the Single Unix Specification and some BSD and GNU extensions. Other library implementations may not support all these features; GCC does not support warning about features that go beyond a @@ -1985,11 +1981,14 @@ in the selected standard version (but not for @code{strfmon} formats, since those are not in any version of the C standard). @xref{C Dialect Options,,Options Controlling C Dialect}. +Since @option{-Wformat} also checks for null format arguments for +several functions, @option{-Wformat} also implies @option{-Wnonnull}. + @option{-Wformat} is included in @option{-Wall}. For more control over some aspects of format checking, the options @option{-Wno-format-y2k}, -@option{-Wno-format-extra-args}, @option{-Wformat-nonliteral}, -@option{-Wformat-security} and @option{-Wformat=2} are available, but are -not included in @option{-Wall}. +@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length}, +@option{-Wformat-nonliteral}, @option{-Wformat-security}, and +@option{-Wformat=2} are available, but are not included in @option{-Wall}. @item -Wno-format-y2k @opindex Wno-format-y2k @@ -2010,6 +2009,11 @@ in the case of @code{scanf} formats, this option will suppress the warning if the unused arguments are all pointers, since the Single Unix Specification says that such unused arguments are allowed. +@item -Wno-format-zero-length +@opindex Wno-format-zero-length +If @option{-Wformat} is specified, do not warn about zero-length formats. +The C standard specifies that zero-length formats are allowed. + @item -Wformat-nonliteral @opindex Wformat-nonliteral If @option{-Wformat} is specified, also warn if the format string is not a @@ -2034,6 +2038,14 @@ Enable @option{-Wformat} plus format checks not included in @option{-Wformat}. Currently equivalent to @samp{-Wformat -Wformat-nonliteral -Wformat-security}. +@item -Wnonnull +@opindex Wnonnull +Enable warning about passing a null pointer for arguments marked as +requiring a non-null value by the @code{nonnull} function attribute. + +@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It +can be disabled with the @option{-Wno-nonnull} option. + @item -Wimplicit-int @opindex Wimplicit-int Warn when a declaration does not specify a type. @@ -2176,6 +2188,18 @@ 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 -Wswitch-default +@opindex Wswitch-switch +Warn whenever a @code{switch} statement does not have a @code{default} +case. + +@item -Wswitch-enum +@opindex Wswitch-enum +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. @code{case} labels outside the enumeration range also +provoke warnings when this option is used. + @item -Wtrigraphs @opindex Wtrigraphs Warn if any trigraphs are encountered that might change the meaning of @@ -2216,7 +2240,7 @@ To suppress this warning cast the expression to @samp{void}. @item -Wunused @opindex Wunused -All all the above @option{-Wunused} options combined. +All the above @option{-Wunused} options combined. In order to get a warning about an unused function parameter, you must either specify @samp{-W -Wunused} or separately specify @@ -2297,13 +2321,6 @@ Some spurious warnings can be avoided if you declare all the functions you use that never return as @code{noreturn}. @xref{Function Attributes}. -@item -Wreorder @r{(C++ only)} -@opindex Wreorder -@cindex reordering, warning -@cindex warning for reordering of member initializers -Warn when the order of member initializers given in the code does not -match the order in which they must be executed. For instance: - @item -Wunknown-pragmas @opindex Wunknown-pragmas @cindex warning for unknown pragmas @@ -2314,41 +2331,22 @@ GCC@. If this command line option is used, warnings will even be issued for unknown pragmas in system header files. This is not the case if the warnings were only enabled by the @option{-Wall} command line option. +@item -Wstrict-aliasing +@opindex Wstrict-aliasing +This option is only active when @option{-fstrict-aliasing} is active. +It warns about code which might break the strict aliasing rules that the +compiler is using for optimization. The warning does not catch all +cases, but does attempt to catch the more common pitfalls. It is +included in @option{-Wall}. + @item -Wall @opindex Wall All of the above @samp{-W} options combined. This enables all the warnings about constructions that some users consider questionable, and that are easy to avoid (or modify to prevent the warning), even in -conjunction with macros. - -@item -Wdiv-by-zero -@opindex Wno-div-by-zero -@opindex Wdiv-by-zero -Warn about compile-time integer division by zero. This is default. To -inhibit the warning messages, use @option{-Wno-div-by-zero}. Floating -point division by zero is not warned about, as it can be a legitimate -way of obtaining infinities and NaNs. - -@item -Wmultichar -@opindex Wno-multichar -@opindex Wmultichar -Warn if a multicharacter constant (@samp{'FOOF'}) is used. This is -default. To inhibit the warning messages, use @option{-Wno-multichar}. -Usually they indicate a typo in the user's code, as they have -implementation-defined values, and should not be used in portable code. - -@item -Wsystem-headers -@opindex Wsystem-headers -@cindex warnings from system headers -@cindex system headers, warnings from -Print warning messages for constructs found in system header files. -Warnings from system headers are normally suppressed, on the assumption -that they usually do not indicate real problems and would only make the -compiler output harder to read. Using this command line option tells -GCC to emit warnings from system headers as if they occurred in user -code. However, note that using @option{-Wall} in conjunction with this -option will @emph{not} warn about unknown pragmas in system -headers---for that, @option{-Wunknown-pragmas} must also be used. +conjunction with macros. This also enables some language-specific +warnings described in @ref{C++ Dialect Options} and +@ref{Objective-C Dialect Options}. @end table The following @option{-W@dots{}} options are not implied by @option{-Wall}. @@ -2437,6 +2435,26 @@ struct s x = @{ 3, 4 @}; @end smallexample @end itemize +@item -Wno-div-by-zero +@opindex Wno-div-by-zero +@opindex Wdiv-by-zero +Do not warn about compile-time integer division by zero. Floating point +division by zero is not warned about, as it can be a legitimate way of +obtaining infinities and NaNs. + +@item -Wsystem-headers +@opindex Wsystem-headers +@cindex warnings from system headers +@cindex system headers, warnings from +Print warning messages for constructs found in system header files. +Warnings from system headers are normally suppressed, on the assumption +that they usually do not indicate real problems and would only make the +compiler output harder to read. Using this command line option tells +GCC to emit warnings from system headers as if they occurred in user +code. However, note that using @option{-Wall} in conjunction with this +option will @emph{not} warn about unknown pragmas in system +headers---for that, @option{-Wunknown-pragmas} must also be used. + @item -Wfloat-equal @opindex Wfloat-equal Warn if floating point values are used in equality comparisons. @@ -2444,7 +2462,7 @@ Warn if floating point values are used in equality comparisons. The idea behind this is that sometimes it is convenient (for the programmer) to consider floating-point values as approximations to infinitely precise real numbers. If you are doing this, then you need -to compute (by analysing the code, or in some other way) the maximum or +to compute (by analyzing the code, or in some other way) the maximum or likely maximum error that the computation introduces, and allow for it when performing comparisons (and when producing output, but that's a different problem). In particular, instead of testing for equality, you @@ -2529,12 +2547,25 @@ Conversions by prototypes between fixed/floating point values and vice versa. The absence of these prototypes when compiling with traditional C would cause serious problems. This is a subset of the possible conversion warnings, for the full set use @option{-Wconversion}. + +@item +Use of ISO C style function definitions. This warning intentionally is +@emph{not} issued for prototype declarations or variadic functions +because these ISO C features will appear in your code when using +libiberty's traditional C compatibility macros, @code{PARAMS} and +@code{VPARAMS}. This warning is also bypassed for nested functions +because that feature is already a gcc extension and thus not relevant to +traditional C compatibility. @end itemize @item -Wundef @opindex Wundef Warn if an undefined identifier is evaluated in an @samp{#if} directive. +@item -Wendif-labels +@opindex Wendif-labels +Warn whenever an @samp{#else} or an @samp{#endif} are followed by text. + @item -Wshadow @opindex Wshadow Warn whenever a local variable shadows another local variable, parameter or @@ -2602,8 +2633,8 @@ casts like @code{(unsigned) -1}. @cindex signed and unsigned values, comparison warning Warn when a comparison between signed and unsigned values could produce an incorrect result when the signed value is converted to unsigned. -This warning is also enabled by @option{-W}; to get the other warnings -of @option{-W} without this warning, use @samp{-W -Wno-sign-compare}. +This warning is enabled by @option{-W}, and by @option{-Wall} +in C++ only. @item -Waggregate-return @opindex Waggregate-return @@ -2625,7 +2656,7 @@ declaration. This warning is issued even if the definition itself provides a prototype. The aim is to detect global functions that fail to be declared in header files. -@item -Wmissing-declarations +@item -Wmissing-declarations @r{(C only)} @opindex Wmissing-declarations Warn if a global function is defined without a previous declaration. Do so even if the definition itself provides a prototype. @@ -2653,6 +2684,13 @@ case, and some functions for which @code{format} attributes are appropriate may not be detected. This option has no effect unless @option{-Wformat} is enabled (possibly by @option{-Wall}). +@item -Wno-multichar +@opindex Wno-multichar +@opindex Wmultichar +Do not warn if a multicharacter constant (@samp{'FOOF'}) is used. +Usually they indicate a typo in the user's code, as they have +implementation-defined values, and should not be used in portable code. + @item -Wno-deprecated-declarations @opindex Wno-deprecated-declarations Do not warn about uses of functions, variables, and types marked as @@ -2723,6 +2761,15 @@ code is to provide behavior which is selectable at compile-time. @item -Winline @opindex Winline Warn if a function can not be inlined and it was declared as inline. +Even with this option, the compiler will not warn about failures to +inline functions declared in system headers. + +The compiler uses a variety of heuristics to determine whether or not +to inline a function. For example, the compiler takes into account +the size of the function being inlined and the the amount of inlining +that has already been done in the current function. Therefore, +seemingly insignificant changes in the source program can cause the +warnings produced by @option{-Winline} to appear or disappear. @item -Wlong-long @opindex Wlong-long @@ -2831,6 +2878,8 @@ Produce debugging information in DWARF version 1 format (if that is supported). This is the format used by SDB on most System V Release 4 systems. +This option is deprecated. + @item -gdwarf+ @opindex gdwarf+ Produce debugging information in DWARF version 1 format (if that is @@ -2838,6 +2887,8 @@ supported), using GNU extensions understood only by the GNU debugger (GDB)@. The use of these extensions is likely to make other debuggers crash or refuse to read the program. +This option is deprecated. + @item -gdwarf-2 @opindex gdwarf-2 Produce debugging information in DWARF version 2 format (if that is @@ -2871,19 +2922,25 @@ and DWARF2, neither @option{-gdwarf} nor @option{-gdwarf-2} accept a concatenated debug level. Instead use an additional @option{-g@var{level}} option to change the debug level for DWARF1 or DWARF2. -@cindex @code{prof} +@item -feliminate-dwarf2-dups +@opindex feliminate-dwarf2-dups +Compress DWARF2 debugging information by eliminating duplicated +information about each symbol. This option only makes sense when +generating DWARF2 debugging information with @option{-gdwarf-2}. + +@cindex @command{prof} @item -p @opindex p Generate extra code to write profile information suitable for the -analysis program @code{prof}. You must use this option when compiling +analysis program @command{prof}. You must use this option when compiling the source files you want data about, and you must also use it when linking. -@cindex @code{gprof} +@cindex @command{gprof} @item -pg @opindex pg Generate extra code to write profile information suitable for the -analysis program @code{gprof}. You must use this option when compiling +analysis program @command{gprof}. You must use this option when compiling the source files you want data about, and you must also use it when linking. @@ -2904,11 +2961,16 @@ allocation when it finishes. @item -fprofile-arcs @opindex fprofile-arcs -Instrument @dfn{arcs} during compilation to generate coverage data -or for profile-directed block ordering. During execution the program +Instrument @dfn{arcs} during compilation to generate coverage data or +for profile-directed block ordering. During execution the program records how many times each branch is executed and how many times it is taken. When the compiled program exits it saves this data to a file -called @file{@var{sourcename}.da} for each source file. +called @file{@var{auxname}.da} for each source file. @var{auxname} is +generated from the name of the output file, if explicitly specified and +it is not the final executable, otherwise it is the basename of the +source file. In both cases any suffix is removed (e.g. @file{foo.da} +for input file @file{dir/foo.c}, or @file{dir/foo.da} for output file +specified as @option{-o dir/foo.o}). For profile-directed block ordering, compile the program with @option{-fprofile-arcs} plus optimization and code generation options, @@ -2918,7 +2980,7 @@ optimization and code generation options plus @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that Control Optimization}). -The other use of @option{-fprofile-arcs} is for use with @code{gcov}, +The other use of @option{-fprofile-arcs} is for use with @command{gcov}, when it is used with the @option{-ftest-coverage} option. With @option{-fprofile-arcs}, for each function of your program GCC @@ -2933,19 +2995,19 @@ block must be created to hold the instrumentation code. @item -ftest-coverage @opindex ftest-coverage Create data files for the @command{gcov} code-coverage utility -(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}). -The data file names begin with the name of your source file: +(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}). See +@option{-fprofile-arcs} option above for a description of @var{auxname}. @table @gcctabopt -@item @var{sourcename}.bb -A mapping from basic blocks to line numbers, which @code{gcov} uses to +@item @var{auxname}.bb +A mapping from basic blocks to line numbers, which @command{gcov} uses to associate basic block execution counts with line numbers. -@item @var{sourcename}.bbg -A list of all arcs in the program flow graph. This allows @code{gcov} +@item @var{auxname}.bbg +A list of all arcs in the program flow graph. This allows @command{gcov} to reconstruct the program flow graph, so that it can compute all basic block and arc execution counts from the information in the -@code{@var{sourcename}.da} file. +@file{@var{auxname}.da} file. @end table Use @option{-ftest-coverage} with @option{-fprofile-arcs}; the latter @@ -2953,9 +3015,9 @@ option adds instrumentation to the program, which then writes execution counts to another data file: @table @gcctabopt -@item @var{sourcename}.da +@item @var{auxname}.da Runtime arc execution counts, used in conjunction with the arc -information in the file @code{@var{sourcename}.bbg}. +information in the file @file{@var{auxname}.bbg}. @end table Coverage data will map better to the source files if @@ -2966,8 +3028,12 @@ Coverage data will map better to the source files if Says to make debugging dumps during compilation at times specified by @var{letters}. This is used for debugging the compiler. The file names for most of the dumps are made by appending a pass number and a word to -the source file name (e.g. @file{foo.c.00.rtl} or @file{foo.c.01.sibling}). -Here are the possible letters for use in @var{letters}, and their meanings: +the @var{dumpname}. @var{dumpname} is generated from the name of the +output file, if explicitly specified and it is not an executable, +otherwise it is the basename of the source file. In both cases any +suffix is removed (e.g. @file{foo.00.rtl} or @file{foo.01.sibling}). +Here are the possible letters for use in @var{letters}, and their +meanings: @table @samp @item A @@ -2978,16 +3044,16 @@ Annotate the assembler output with miscellaneous debugging information. Dump after computing branch probabilities, to @file{@var{file}.14.bp}. @item B @opindex dB -Dump after block reordering, to @file{@var{file}.29.bbro}. +Dump after block reordering, to @file{@var{file}.32.bbro}. @item c @opindex dc -Dump after instruction combination, to the file @file{@var{file}.16.combine}. +Dump after instruction combination, to the file @file{@var{file}.19.combine}. @item C @opindex dC -Dump after the first if conversion, to the file @file{@var{file}.17.ce}. +Dump after the first if conversion, to the file @file{@var{file}.15.ce1}. @item d @opindex dd -Dump after delayed branch scheduling, to @file{@var{file}.31.dbr}. +Dump after delayed branch scheduling, to @file{@var{file}.34.dbr}. @item D @opindex dD Dump all macro definitions, at the end of preprocessing, in addition to @@ -2998,28 +3064,23 @@ Dump after SSA optimizations, to @file{@var{file}.04.ssa} and @file{@var{file}.07.ussa}. @item E @opindex dE -Dump after the second if conversion, to @file{@var{file}.26.ce2}. +Dump after the second if conversion, to @file{@var{file}.29.ce3}. @item f @opindex df -Dump after life analysis, to @file{@var{file}.15.life}. +Dump after control and data flow analysis, to @file{@var{file}.14.cfg}. +Also dump after life analysis, to @file{@var{file}.18.life}. @item F @opindex dF -Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.09.addressof}. +Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.10.addressof}. @item g @opindex dg -Dump after global register allocation, to @file{@var{file}.21.greg}. +Dump after global register allocation, to @file{@var{file}.24.greg}. +@item G +@opindex dG +Dump after GCSE, to @file{@var{file}.11.gcse}. @item h @opindex dh Dump after finalization of EH handling code, to @file{@var{file}.02.eh}. -@item k -@opindex dk -Dump after reg-to-stack conversion, to @file{@var{file}.28.stack}. -@item o -@opindex do -Dump after post-reload optimizations, to @file{@var{file}.22.postreload}. -@item G -@opindex dG -Dump after GCSE, to @file{@var{file}.10.gcse}. @item i @opindex di Dump after sibling call optimizations, to @file{@var{file}.01.sibling}. @@ -3028,49 +3089,62 @@ Dump after sibling call optimizations, to @file{@var{file}.01.sibling}. Dump after the first jump optimization, to @file{@var{file}.03.jump}. @item k @opindex dk -Dump after conversion from registers to stack, to @file{@var{file}.32.stack}. +Dump after conversion from registers to stack, to @file{@var{file}.31.stack}. @item l @opindex dl -Dump after local register allocation, to @file{@var{file}.20.lreg}. +Dump after local register allocation, to @file{@var{file}.23.lreg}. @item L @opindex dL -Dump after loop optimization, to @file{@var{file}.11.loop}. +Dump after loop optimization, to @file{@var{file}.12.loop}. @item M @opindex dM -Dump after performing the machine dependent reorganisation pass, to -@file{@var{file}.30.mach}. +Dump after performing the machine dependent reorganization pass, to +@file{@var{file}.33.mach}. @item n @opindex dn -Dump after register renumbering, to @file{@var{file}.25.rnreg}. +Dump after register renumbering, to @file{@var{file}.28.rnreg}. @item N @opindex dN -Dump after the register move pass, to @file{@var{file}.18.regmove}. +Dump after the register move pass, to @file{@var{file}.21.regmove}. +@item o +@opindex do +Dump after post-reload optimizations, to @file{@var{file}.25.postreload}. @item r @opindex dr Dump after RTL generation, to @file{@var{file}.00.rtl}. @item R @opindex dR -Dump after the second scheduling pass, to @file{@var{file}.27.sched2}. +Dump after the second scheduling pass, to @file{@var{file}.30.sched2}. @item s @opindex ds Dump after CSE (including the jump optimization that sometimes follows -CSE), to @file{@var{file}.08.cse}. +CSE), to @file{@var{file}.09.cse}. @item S @opindex dS -Dump after the first scheduling pass, to @file{@var{file}.19.sched}. +Dump after the first scheduling pass, to @file{@var{file}.22.sched}. @item t @opindex dt Dump after the second CSE pass (including the jump optimization that -sometimes follows CSE), to @file{@var{file}.12.cse2}. +sometimes follows CSE), to @file{@var{file}.17.cse2}. +@item T +@opindex dT +Dump after running tracer, to @file{@var{file}.16.tracer}. +@item u +@opindex du +Dump after null pointer elimination pass to @file{@var{file}.08.null}. @item w @opindex dw -Dump after the second flow pass, to @file{@var{file}.23.flow2}. +Dump after the second flow pass, to @file{@var{file}.26.flow2}. +@item W +@opindex dW +Dump after SSA conditional constant propagation, to +@file{@var{file}.05.ssaccp}. @item X @opindex dX Dump after SSA dead code elimination, to @file{@var{file}.06.ssadce}. @item z @opindex dz -Dump after the peephole pass, to @file{@var{file}.24.peephole2}. +Dump after the peephole pass, to @file{@var{file}.27.peephole2}. @item a @opindex da Produce all the dumps listed above. @@ -3160,6 +3234,14 @@ Dump after all tree based optimization, to @file{@var{file}.optimized}. Dump after function inlining, to @file{@var{file}.inlined}. @end table +@item -frandom-seed=@var{string} +@opindex frandom-string +This option provides a seed that GCC uses when it would otherwise use +random numbers. At present, this is used to generate certain symbol names +that have to be different in every compiled file. + +The @var{string} should be different for every file you compile. + @item -fsched-verbose=@var{n} @opindex fsched-verbose On targets that use instruction scheduling, this option controls the @@ -3177,14 +3259,6 @@ and unit/insn info. For @var{n} greater than two, it includes RTL at abort point, control-flow and regions info. And for @var{n} over four, @option{-fsched-verbose} also includes dependence info. -@item -fpretend-float -@opindex fpretend-float -When running a cross-compiler, pretend that the target machine uses the -same floating point format as the host machine. This causes incorrect -output of the actual floating constants, but the actual instruction -sequence will probably be the same as GCC would make when running on -the target machine. - @item -save-temps @opindex save-temps Store the usual ``temporary'' intermediate files permanently; place them @@ -3280,7 +3354,22 @@ is used when GCC itself is being built.) @xref{Spec Files}. @cindex optimize options @cindex options, optimization -These options control various sorts of optimizations: +These options control various sorts of optimizations. + +Without any optimization option, the compiler's goal is to reduce the +cost of compilation and to make debugging produce the expected +results. Statements are independent: if you stop the program with a +breakpoint between statements, you can then assign a new value to any +variable or change the program counter to any other statement in the +function and get exactly the results you would expect from the source +code. + +Turning on optimization flags makes the compiler attempt to improve +the performance and/or code size at the expense of compilation time +and possibly the ability to debug the program. + +Not all optimizations are controlled directly by a flag. Only +optimizations that have a flag are listed. @table @gcctabopt @item -O @@ -3290,17 +3379,25 @@ These options control various sorts of optimizations: Optimize. Optimizing compilation takes somewhat more time, and a lot more memory for a large function. -Without @option{-O}, the compiler's goal is to reduce the cost of -compilation and to make debugging produce the expected results. -Statements are independent: if you stop the program with a breakpoint -between statements, you can then assign a new value to any variable or -change the program counter to any other statement in the function and -get exactly the results you would expect from the source code. - With @option{-O}, the compiler tries to reduce code size and execution time, without performing any optimizations that take a great deal of compilation time. +@option{-O} turns on the following optimization flags: +@gccoptlist{-fdefer-pop @gol +-fmerge-constants @gol +-fthread-jumps @gol +-floop-optimize @gol +-fcrossjumping @gol +-fif-conversion @gol +-fif-conversion2 @gol +-fdelayed-branch @gol +-fguess-branch-probability @gol +-fcprop-registers} + +@option{-O} also turns on @option{-fomit-frame-pointer} on machines +where doing so does not interfere with debugging. + @item -O2 @opindex O2 Optimize even more. GCC performs nearly all supported optimizations @@ -3309,10 +3406,25 @@ perform loop unrolling or function inlining when you specify @option{-O2}. As compared to @option{-O}, this option increases both compilation time and the performance of the generated code. -@option{-O2} turns on all optional optimizations except for loop unrolling, -function inlining, and register renaming. It also turns on the -@option{-fforce-mem} option on all machines and frame pointer elimination -on machines where doing so does not interfere with debugging. +@option{-O2} turns on all optimization flags specified by @option{-O}. It +also turns on the following optimization flags: +@gccoptlist{-fforce-mem @gol +-foptimize-sibling-calls @gol +-fstrength-reduce @gol +-fcse-follow-jumps -fcse-skip-blocks @gol +-frerun-cse-after-loop -frerun-loop-opt @gol +-fgcse -fgcse-lm -fgcse-sm @gol +-fdelete-null-pointer-checks @gol +-fexpensive-optimizations @gol +-fregmove @gol +-fschedule-insns -fschedule-insns2 @gol +-fsched-interblock -fsched-spec @gol +-fcaller-saves @gol +-fpeephole2 @gol +-freorder-blocks -freorder-functions @gol +-fstrict-aliasing @gol +-falign-functions -falign-jumps @gol +-falign-loops -falign-labels} Please note the warning under @option{-fgcse} about invoking @option{-O2} on programs that use computed gotos. @@ -3325,7 +3437,7 @@ Optimize yet more. @option{-O3} turns on all optimizations specified by @item -O0 @opindex O0 -Do not optimize. +Do not optimize. This is the default. @item -Os @opindex Os @@ -3333,33 +3445,27 @@ Optimize for size. @option{-Os} enables all @option{-O2} optimizations that do not typically increase code size. It also performs further optimizations designed to reduce code size. +@option{-Os} disables the following optimization flags: +@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol +-falign-labels -freorder-blocks -fprefetch-loop-arrays} + If you use multiple @option{-O} options, with or without level numbers, the last such option is the one that is effective. @end table Options of the form @option{-f@var{flag}} specify machine-independent flags. Most flags have both positive and negative forms; the negative -form of @option{-ffoo} would be @option{-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 @gcctabopt -@item -ffloat-store -@opindex ffloat-store -Do not store floating point variables in registers, and inhibit other -options that might change whether a floating point value is taken from a -register or memory. +form of @option{-ffoo} would be @option{-fno-foo}. In the table +below, only one of the forms is listed---the one you typically will +use. You can figure out the other form by either removing @samp{no-} +or adding it. -@cindex floating point precision -This option prevents undesirable excess precision on machines such as -the 68000 where the floating registers (of the 68881) keep more -precision than a @code{double} is supposed to have. Similarly for the -x86 architecture. For most programs, the excess precision does only -good, but a few programs rely on the precise definition of IEEE floating -point. Use @option{-ffloat-store} for such programs, after modifying -them to store all pertinent intermediate computations into variables. +The following options control specific optimizations. They are either +activated by @option{-O} options or are related to ones that are. You +can use the following flags in the rare cases when ``fine-tuning'' of +optimizations to be performed is desired. +@table @gcctabopt @item -fno-default-inline @opindex fno-default-inline Do not make member functions inline by default merely because they are @@ -3375,13 +3481,17 @@ returns. For machines which must pop arguments after a function call, the compiler normally lets arguments accumulate on the stack for several function calls and pops them all at once. +Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + @item -fforce-mem @opindex fforce-mem Force memory operands to be copied into registers before doing arithmetic on them. This produces better code by making all memory references potential common subexpressions. When they are not common subexpressions, instruction combination should eliminate the separate -register-load. The @option{-O2} option turns on this option. +register-load. + +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. @item -fforce-addr @opindex fforce-addr @@ -3404,14 +3514,13 @@ machine-description macro @code{FRAME_POINTER_REQUIRED} controls whether a target machine supports this flag. @xref{Registers,,Register Usage, gccint, GNU Compiler Collection (GCC) Internals}. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + @item -foptimize-sibling-calls @opindex foptimize-sibling-calls Optimize sibling and tail recursive calls. -@item -ftrapv -@opindex ftrapv -This option generates traps for signed overflow on addition, subtraction, -multiplication operations. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. @item -fno-inline @opindex fno-inline @@ -3429,11 +3538,13 @@ If all calls to a given function are integrated, and the function is declared @code{static}, then the function is normally not output as assembler code in its own right. +Enabled at level @option{-O3}. + @item -finline-limit=@var{n} @opindex finline-limit By default, gcc limits the size of functions that can be inlined. This flag allows the control of this limit for functions that are explicitly marked as -inline (ie marked with the inline keyword or defined within the class +inline (i.e., marked with the inline keyword or defined within the class definition in c++). @var{n} is the size of functions that can be inlined in number of pseudo instructions (not counting parameter handling). The default value of @var{n} is 600. @@ -3443,6 +3554,28 @@ the compilation faster and less code will be inlined (which presumably means slower programs). This option is particularly useful for programs that use inlining heavily such as those based on recursive templates with C++. +Inlining is actually controlled by a number of parameters, which may be +specified individually by using @option{--param @var{name}=@var{value}}. +The @option{-finline-limit=@var{n}} option sets some of these parameters +as follows: + + @table @gcctabopt + @item max-inline-insns + is set to @var{n}. + @item max-inline-insns-single + is set to @var{n}/2. + @item max-inline-insns-auto + is set to @var{n}/2. + @item min-inline-insns + is set to 130 or @var{n}/4, whichever is smaller. + @item max-inline-insns-rtl + is set to @var{n}. + @end table + +Using @option{-finline-limit=600} thus results in the default settings +for these parameters. See below for a documentation of the individual +parameters controlling inlining. + @emph{Note:} pseudo instruction represents, in this particular context, an abstract measurement of function's size. In no way, it represents a count of assembly instructions and as such its exact meaning might change from one @@ -3466,10 +3599,13 @@ optimization is turned on, use the @option{-fno-keep-static-consts} option. @item -fmerge-constants Attempt to merge identical constants (string constants and floating point -constants) accross compilation units. +constants) across compilation units. -This option is default for optimized compilation if assembler and linker -support it. Use @option{-fno-merge-constants} to inhibit this behavior. +This option is the default for optimized compilation if the assembler and +linker support it. Use @option{-fno-merge-constants} to inhibit this +behavior. + +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. @item -fmerge-all-constants Attempt to merge identical constants and identical variables. @@ -3489,6 +3625,9 @@ register, compare it against zero, then branch based upon the result. This option is only meaningful on architectures that support such instructions, which include x86, PowerPC, IA-64 and S/390. +The default is @option{-fbranch-count-reg}, enabled when +@option{-fstrength-reduce} is enabled. + @item -fno-function-cse @opindex fno-function-cse Do not put function addresses in registers; make each instruction that @@ -3498,87 +3637,28 @@ This option results in less efficient code, but some strange hacks that alter the assembler output may be confused by the optimizations performed when this option is not used. -@item -ffast-math -@opindex ffast-math -Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, and @* -@option{-fno-trapping-math}. - -This option causes the preprocessor macro @code{__FAST_MATH__} to be defined. - -This option should never be turned on by any @option{-O} option since -it can result in incorrect output for programs which depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. - -@item -fno-math-errno -@opindex fno-math-errno -Do not set ERRNO after calling math functions that are executed -with a single instruction, e.g., sqrt. A program that relies on -IEEE exceptions for math error handling may want to use this flag -for speed while maintaining IEEE arithmetic compatibility. - -This option should never be turned on by any @option{-O} option since -it can result in incorrect output for programs which depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. - -The default is @option{-fmath-errno}. - -@item -funsafe-math-optimizations -@opindex funsafe-math-optimizations -Allow optimizations for floating-point arithmetic that (a) assume -that arguments and results are valid and (b) may violate IEEE or -ANSI standards. When used at link-time, it may include libraries -or startup files that change the default FPU control word or other -similar optimizations. +The default is @option{-ffunction-cse} -This option should never be turned on by any @option{-O} option since -it can result in incorrect output for programs which depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. +@item -fno-zero-initialized-in-bss +@opindex fno-zero-initialized-in-bss +If the target supports a BSS section, GCC by default puts variables that +are initialized to zero into BSS@. This can save space in the resulting +code. -The default is @option{-fno-unsafe-math-optimizations}. +This option turns off this behavior because some programs explicitly +rely on variables going to the data section. E.g., so that the +resulting executable can find the beginning of that section and/or make +assumptions based on that. -@item -fno-trapping-math -@opindex fno-trapping-math -Compile code assuming that floating-point operations cannot generate -user-visible traps. Setting this option may allow faster code -if one relies on ``non-stop'' IEEE arithmetic, for example. +The default is @option{-fzero-initialized-in-bss}. -This option should never be turned on by any @option{-O} option since -it can result in incorrect output for programs which depend on -an exact implementation of IEEE or ISO rules/specifications for -math functions. - -The default is @option{-ftrapping-math}. - -@item -fbounds-check -@opindex fbounds-check -For front-ends that support it, generate additional code to check that -indices used to access arrays are within the declared range. This is -currenly only supported by the Java and Fortran 77 front-ends, where -this option defaults to true and false respectively. - -@end table - -The following options control specific optimizations. The @option{-O2} -option turns on all of these optimizations except @option{-funroll-loops} -and @option{-funroll-all-loops}. On most machines, the @option{-O} option -turns on the @option{-fthread-jumps} and @option{-fdelayed-branch} options, -but specific machines may handle it differently. - -You can use the following flags in the rare cases when ``fine-tuning'' -of optimizations to be performed is desired. - -Not all of the optimizations performed by GCC have @option{-f} options -to control them. - -@table @gcctabopt @item -fstrength-reduce @opindex fstrength-reduce Perform the optimizations of loop strength reduction and elimination of iteration variables. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -fthread-jumps @opindex fthread-jumps Perform optimizations where we check to see if a jump branches to a @@ -3587,6 +3667,8 @@ so, the first branch is redirected to either the destination of the second branch or a point immediately following it, depending on whether the condition is known to be true or false. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + @item -fcse-follow-jumps @opindex fcse-follow-jumps In common subexpression elimination, scan through jump instructions @@ -3595,6 +3677,8 @@ example, when CSE encounters an @code{if} statement with an @code{else} clause, CSE will follow the jump when the condition tested is false. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -fcse-skip-blocks @opindex fcse-skip-blocks This is similar to @option{-fcse-follow-jumps}, but causes CSE to @@ -3603,15 +3687,21 @@ encounters a simple @code{if} statement with no else clause, @option{-fcse-skip-blocks} causes CSE to follow the jump around the body of the @code{if}. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -frerun-cse-after-loop @opindex frerun-cse-after-loop Re-run common subexpression elimination after loop optimizations has been performed. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -frerun-loop-opt @opindex frerun-loop-opt Run the loop optimizer twice. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -fgcse @opindex fgcse Perform a global common subexpression elimination pass. @@ -3619,9 +3709,11 @@ This pass also performs global constant and copy propagation. @emph{Note:} When compiling a program using computed gotos, a GCC extension, you may get better runtime performance if you disable -the global common subexpression elmination pass by adding +the global common subexpression elimination pass by adding @option{-fno-gcse} to the command line. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -fgcse-lm @opindex fgcse-lm When @option{-fgcse-lm} is enabled, global common subexpression elimination will @@ -3629,6 +3721,8 @@ attempt to move loads which are only killed by stores into themselves. This allows a loop containing a load/store sequence to be changed to a load outside the loop, and a copy/store within the loop. +Enabled by default when gcse is enabled. + @item -fgcse-sm @opindex fgcse-sm When @option{-fgcse-sm} is enabled, A store motion pass is run after global common @@ -3636,6 +3730,39 @@ subexpression elimination. This pass will attempt to move stores out of loops. When used in conjunction with @option{-fgcse-lm}, loops containing a load/store sequence can be changed to a load before the loop and a store after the loop. +Enabled by default when gcse is enabled. + +@item -floop-optimize +@opindex floop-optimize +Perform loop optimizations: move constant expressions out of loops, simplify +exit test conditions and optionally do strength-reduction and loop unrolling as +well. + +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + +@item -fcrossjumping +@opindex crossjumping +Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The +resulting code may or may not perform better than without cross-jumping. + +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + +@item -fif-conversion +@opindex if-conversion +Attempt to transform conditional jumps into branch-less equivalents. This +include use of conditional moves, min, max, set flags and abs instructions, and +some tricks doable by standard arithmetics. The use of conditional execution +on chips where it is available is controlled by @code{if-conversion2}. + +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + +@item -fif-conversion2 +@opindex if-conversion2 +Use conditional execution (where available) to transform conditional jumps into +branch-less equivalents. + +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + @item -fdelete-null-pointer-checks @opindex fdelete-null-pointer-checks Use global dataflow analysis to identify and eliminate useless checks @@ -3648,10 +3775,14 @@ safely dereference null pointers. Use @option{-fno-delete-null-pointer-checks} to disable this optimization for programs which depend on that behavior. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -fexpensive-optimizations @opindex fexpensive-optimizations Perform a number of minor optimizations that are relatively expensive. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -foptimize-register-move @itemx -fregmove @opindex foptimize-register-move @@ -3659,18 +3790,21 @@ Perform a number of minor optimizations that are relatively expensive. Attempt to reassign register numbers in move instructions and as operands of other simple instructions in order to maximize the amount of register tying. This is especially helpful on machines with two-operand -instructions. GCC enables this optimization by default with @option{-O2} -or higher. +instructions. Note @option{-fregmove} and @option{-foptimize-register-move} are the same optimization. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -fdelayed-branch @opindex fdelayed-branch If supported for the target machine, attempt to reorder instructions to exploit instruction slots available after delayed branch instructions. +Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + @item -fschedule-insns @opindex fschedule-insns If supported for the target machine, attempt to reorder instructions to @@ -3679,6 +3813,8 @@ helps machines that have slow floating point or memory load instructions by allowing other instructions to be issued until the result of the load or floating point instruction is required. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -fschedule-insns2 @opindex fschedule-insns2 Similar to @option{-fschedule-insns}, but requests an additional pass of @@ -3686,6 +3822,8 @@ instruction scheduling after register allocation has been done. This is especially useful on machines with a relatively small number of registers and where memory load instructions take more than one cycle. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -fno-sched-interblock @opindex fno-sched-interblock Don't schedule instructions across basic blocks. This is normally @@ -3710,28 +3848,6 @@ Allow speculative motion of more load instructions. This only makes sense when scheduling before register allocation, i.e.@: with @option{-fschedule-insns} or at @option{-O2} or higher. -@item -ffunction-sections -@itemx -fdata-sections -@opindex ffunction-sections -@opindex fdata-sections -Place each function or data item into its own section in the output -file if the target supports arbitrary sections. The name of the -function or the name of the data item determines the section's name -in the output file. - -Use these options on systems where the linker can perform optimizations -to improve locality of reference in the instruction space. HPPA -processors running HP-UX and Sparc processors running Solaris 2 have -linkers with such optimizations. Other systems using the ELF object format -as well as AIX may have these optimizations in the future. - -Only use these options when there are significant benefits from doing -so. When you specify these options, the assembler and linker will -create larger object and executable files and will also be slower. -You will not be able to use @code{gprof} on all systems if you -specify this option and you may have problems with debugging if -you specify both this option and @option{-g}. - @item -fcaller-saves @opindex fcaller-saves Enable values to be allocated in registers that will be clobbered by @@ -3742,27 +3858,7 @@ seems to result in better code than would otherwise be produced. This option is always enabled by default on certain machines, usually those which have no call-preserved registers to use instead. -For all machines, optimization level 2 and higher enables this flag by -default. - -@item -funroll-loops -@opindex funroll-loops -Unroll loops whose number of iterations can be determined at compile -time or upon entry to the loop. @option{-funroll-loops} implies both -@option{-fstrength-reduce} and @option{-frerun-cse-after-loop}. This -option makes code larger, and may or may not make it run faster. - -@item -funroll-all-loops -@opindex funroll-all-loops -Unroll all loops, even if their number of iterations is uncertain when -the loop is entered. This usually makes programs run more slowly. -@option{-funroll-all-loops} implies the same options as -@option{-funroll-loops}, - -@item -fprefetch-loop-arrays -@opindex fprefetch-loop-arrays -If supported by the target machine, generate instructions to prefetch -memory to improve the performance of loops that access large arrays. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. @item -fmove-all-movables @opindex fmove-all-movables @@ -3800,27 +3896,10 @@ between @option{-fno-peephole} and @option{-fno-peephole2} is in how they are implemented in the compiler; some targets use one, some use the other, a few use both. -@item -fbranch-probabilities -@opindex fbranch-probabilities -After running a program compiled with @option{-fprofile-arcs} -(@pxref{Debugging Options,, Options for Debugging Your Program or -@command{gcc}}), you can compile it a second time using -@option{-fbranch-probabilities}, to improve optimizations based on -the number of times each branch was taken. When the program -compiled with @option{-fprofile-arcs} exits it saves arc execution -counts to a file called @file{@var{sourcename}.da} for each source -file The information in this data file is very dependent on the -structure of the generated code, so you must use the same source code -and the same optimization options for both compilations. - -With @option{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT} -note on the first instruction of each basic block, and a -@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}. -These can be used to improve optimization. Currently, they are only -used in one place: in @file{reorg.c}, instead of guessing which path a -branch is mostly to take, the @samp{REG_BR_PROB} values are used to -exactly determine which path is taken more often. +@option{-fpeephole} is enabled by default. +@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. +@item -fbranch-probabilities @item -fno-guess-branch-probability @opindex fno-guess-branch-probability Do not guess branch probabilities using a randomized model. @@ -3837,6 +3916,30 @@ non-determinism is of paramount import. This switch allows users to reduce non-determinism, possibly at the expense of inferior optimization. +The default is @option{-fguess-branch-probability} at levels +@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + +@item -freorder-blocks +@opindex freorder-blocks +Reorder basic blocks in the compiled function in order to reduce number of +taken branches and improve code locality. + +Enabled at levels @option{-O2}, @option{-O3}. + +@item -freorder-functions +@opindex freorder-functions +Reorder basic blocks in the compiled function in order to reduce number of +taken branches and improve code locality. This is implemented by using special +subsections @code{text.hot} for most frequently executed functions and +@code{text.unlikely} for unlikely executed functions. Reordering is done by +the linker so object file format must support named sections and linker must +place them in a reasonable way. + +Also profile feedback must be available in to make this option effective. See +@option{-fprofile-arcs} for details. + +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -fstrict-aliasing @opindex fstrict-aliasing Allows the compiler to assume the strictest aliasing rules applicable to @@ -3882,6 +3985,8 @@ node, an alias set for the node. Nodes in different alias sets are not allowed to alias. For an example, see the C front-end function @code{c_get_alias_set}. +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. + @item -falign-functions @itemx -falign-functions=@var{n} @opindex falign-functions @@ -3897,7 +4002,9 @@ equivalent and mean that functions will not be aligned. Some assemblers only support this flag when @var{n} is a power of two; in that case, it is rounded up. -If @var{n} is not specified, use a machine-dependent default. +If @var{n} is not specified or is zero, use a machine-dependent default. + +Enabled at levels @option{-O2}, @option{-O3}. @item -falign-labels @itemx -falign-labels=@var{n} @@ -3907,11 +4014,16 @@ Align all branch targets to a power-of-two boundary, skipping up to make code slower, because it must insert dummy operations for when the branch target is reached in the usual flow of the code. +@option{-fno-align-labels} and @option{-falign-labels=1} are +equivalent and mean that labels will not be aligned. + If @option{-falign-loops} or @option{-falign-jumps} are applicable and are greater than this value, then their values are used instead. -If @var{n} is not specified, use a machine-dependent default which is -very likely to be @samp{1}, meaning no alignment. +If @var{n} is not specified or is zero, use a machine-dependent default +which is very likely to be @samp{1}, meaning no alignment. + +Enabled at levels @option{-O2}, @option{-O3}. @item -falign-loops @itemx -falign-loops=@var{n} @@ -3921,7 +4033,12 @@ like @option{-falign-functions}. The hope is that the loop will be executed many times, which will make up for any execution of the dummy operations. -If @var{n} is not specified, use a machine-dependent default. +@option{-fno-align-loops} and @option{-falign-loops=1} are +equivalent and mean that loops will not be aligned. + +If @var{n} is not specified or is zero, use a machine-dependent default. + +Enabled at levels @option{-O2}, @option{-O3}. @item -falign-jumps @itemx -falign-jumps=@var{n} @@ -3931,7 +4048,224 @@ where the targets can only be reached by jumping, skipping up to @var{n} bytes like @option{-falign-functions}. In this case, no dummy operations need be executed. -If @var{n} is not specified, use a machine-dependent default. +@option{-fno-align-jumps} and @option{-falign-jumps=1} are +equivalent and mean that loops will not be aligned. + +If @var{n} is not specified or is zero, use a machine-dependent default. + +Enabled at levels @option{-O2}, @option{-O3}. + +@item -frename-registers +@opindex frename-registers +Attempt to avoid false dependencies in scheduled code by making use +of registers left over after register allocation. This optimization +will most benefit processors with lots of registers. It can, however, +make debugging impossible, since variables will no longer stay in +a ``home register''. + +Enabled at levels @option{-O3}. + +@item -fno-cprop-registers +@opindex fno-cprop-registers +After register allocation and post-register allocation instruction splitting, +we perform a copy-propagation pass to try to reduce scheduling dependencies +and occasionally eliminate the copy. + +Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. + +@end table + +The following options control compiler behavior regarding floating +point arithmetic. These options trade off between speed and +correctness. All must be specifically enabled. + +@table @gcctabopt +@item -ffloat-store +@opindex ffloat-store +Do not store floating point variables in registers, and inhibit other +options that might change whether a floating point value is taken from a +register or memory. + +@cindex floating point precision +This option prevents undesirable excess precision on machines such as +the 68000 where the floating registers (of the 68881) keep more +precision than a @code{double} is supposed to have. Similarly for the +x86 architecture. For most programs, the excess precision does only +good, but a few programs rely on the precise definition of IEEE floating +point. Use @option{-ffloat-store} for such programs, after modifying +them to store all pertinent intermediate computations into variables. + +@item -ffast-math +@opindex ffast-math +Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @* +@option{-fno-trapping-math}, @option{-ffinite-math-only} and @* +@option{-fno-signaling-nans}. + +This option causes the preprocessor macro @code{__FAST_MATH__} to be defined. + +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. + +@item -fno-math-errno +@opindex fno-math-errno +Do not set ERRNO after calling math functions that are executed +with a single instruction, e.g., sqrt. A program that relies on +IEEE exceptions for math error handling may want to use this flag +for speed while maintaining IEEE arithmetic compatibility. + +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. + +The default is @option{-fmath-errno}. + +@item -funsafe-math-optimizations +@opindex funsafe-math-optimizations +Allow optimizations for floating-point arithmetic that (a) assume +that arguments and results are valid and (b) may violate IEEE or +ANSI standards. When used at link-time, it may include libraries +or startup files that change the default FPU control word or other +similar optimizations. + +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. + +The default is @option{-fno-unsafe-math-optimizations}. + +@item -ffinite-math-only +@opindex ffinite-math-only +Allow optimizations for floating-point arithmetic that assume +that arguments and results are not NaNs or +-Infs. + +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ISO rules/specifications. + +The default is @option{-fno-finite-math-only}. + +@item -fno-trapping-math +@opindex fno-trapping-math +Compile code assuming that floating-point operations cannot generate +user-visible traps. These traps include division by zero, overflow, +underflow, inexact result and invalid operation. This option implies +@option{-fno-signaling-nans}. Setting this option may allow faster +code if one relies on ``non-stop'' IEEE arithmetic, for example. + +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. + +The default is @option{-ftrapping-math}. + +@item -fsignaling-nans +@opindex fsignaling-nans +Compile code assuming that IEEE signaling NaNs may generate user-visible +traps during floating-point operations. Setting this option disables +optimizations that may change the number of exceptions visible with +signaling NaNs. This option implies @option{-ftrapping-math}. + +This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to +be defined. + +The default is @option{-fno-signaling-nans}. + +This option is experimental and does not currently guarantee to +disable all GCC optimizations that affect signaling NaN behavior. + +@item -fsingle-precision-constant +@opindex fsingle-precision-constant +Treat floating point constant as single precision constant instead of +implicitly converting it to double precision constant. + + +@end table + +The following options control optimizations that may improve +performance, but are not enabled by any @option{-O} options. This +section includes experimental options that may produce broken code. + +@table @gcctabopt +@item -fbranch-probabilities +@opindex fbranch-probabilities +After running a program compiled with @option{-fprofile-arcs} +(@pxref{Debugging Options,, Options for Debugging Your Program or +@command{gcc}}), you can compile it a second time using +@option{-fbranch-probabilities}, to improve optimizations based on +the number of times each branch was taken. When the program +compiled with @option{-fprofile-arcs} exits it saves arc execution +counts to a file called @file{@var{sourcename}.da} for each source +file The information in this data file is very dependent on the +structure of the generated code, so you must use the same source code +and the same optimization options for both compilations. + +With @option{-fbranch-probabilities}, GCC puts a +@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}. +These can be used to improve optimization. Currently, they are only +used in one place: in @file{reorg.c}, instead of guessing which path a +branch is mostly to take, the @samp{REG_BR_PROB} values are used to +exactly determine which path is taken more often. + +@item -fnew-ra +@opindex fnew-ra +Use a graph coloring register allocator. Currently this option is meant +for testing, so we are interested to hear about miscompilations with +@option{-fnew-ra}. + +@item -ftracer +@opindex ftracer +Perform tail duplication to enlarge superblock size. This transformation +simplifies the control flow of the function allowing other optimizations to do +better job. + +@item -funroll-loops +@opindex funroll-loops +Unroll loops whose number of iterations can be determined at compile +time or upon entry to the loop. @option{-funroll-loops} implies both +@option{-fstrength-reduce} and @option{-frerun-cse-after-loop}. This +option makes code larger, and may or may not make it run faster. + +@item -funroll-all-loops +@opindex funroll-all-loops +Unroll all loops, even if their number of iterations is uncertain when +the loop is entered. This usually makes programs run more slowly. +@option{-funroll-all-loops} implies the same options as +@option{-funroll-loops}, + +@item -fprefetch-loop-arrays +@opindex fprefetch-loop-arrays +If supported by the target machine, generate instructions to prefetch +memory to improve the performance of loops that access large arrays. + +Disabled at level @option{-Os}. + +@item -ffunction-sections +@itemx -fdata-sections +@opindex ffunction-sections +@opindex fdata-sections +Place each function or data item into its own section in the output +file if the target supports arbitrary sections. The name of the +function or the name of the data item determines the section's name +in the output file. + +Use these options on systems where the linker can perform optimizations +to improve locality of reference in the instruction space. Most systems +using the ELF object format and SPARC processors running Solaris 2 have +linkers with such optimizations. AIX may have these optimizations in +the future. + + +Only use these options when there are significant benefits from doing +so. When you specify these options, the assembler and linker will +create larger object and executable files and will also be slower. +You will not be able to use @code{gprof} on all systems if you +specify this option and you may have problems with debugging if +you specify both this option and @option{-g}. @item -fssa @opindex fssa @@ -3950,24 +4284,6 @@ Perform Sparse Conditional Constant Propagation in SSA form. Requires Perform aggressive dead-code elimination in SSA form. Requires @option{-fssa}. Like @option{-fssa}, this is an experimental feature. -@item -fsingle-precision-constant -@opindex fsingle-precision-constant -Treat floating point constant as single precision constant instead of -implicitly converting it to double precision constant. - -@item -frename-registers -@opindex frename-registers -Attempt to avoid false dependencies in scheduled code by making use -of registers left over after register allocation. This optimization -will most benefit processors with lots of registers. It can, however, -make debugging impossible, since variables will no longer stay in -a ``home register''. - -@item -fno-cprop-registers -@opindex fno-cprop-registers -After register allocation and post-register allocation instruction splitting, -we perform a copy-propagation pass to try to reduce scheduling dependencies -and occasionally eliminate the copy. @item --param @var{name}=@var{value} @opindex param @@ -3981,6 +4297,13 @@ In each case, the @var{value} is an integer. The allowable choices for @var{name} are given in the following table: @table @gcctabopt +@item max-crossjump-edges +The maximum number of incoming edges to consider for crossjumping. +The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in +the number of edges incoming to each block. Increasing values mean +more aggressive optimization, making the compile time increase with +probably small improvement in executable size. + @item max-delay-slot-insn-search The maximum number of instructions to consider when looking for an instruction to fill a delay slot. If more than this arbitrary number of @@ -4012,10 +4335,133 @@ before flushing the current state and starting over. Large functions with few branches or calls can create excessively large lists which needlessly consume memory and resources. +@item max-inline-insns-single +Several parameters control the tree inliner used in gcc. +This number sets the maximum number of instructions (counted in gcc's +internal representation) in a single function that the tree inliner +will consider for inlining. This only affects functions declared +inline and methods implemented in a class declaration (C++). +The default value is 300. + +@item max-inline-insns-auto +When you use @option{-finline-functions} (included in @option{-O3}), +a lot of functions that would otherwise not be considered for inlining +by the compiler will be investigated. To those functions, a different +(more restrictive) limit compared to functions declared inline can +be applied. +The default value is 300. + @item max-inline-insns -If an function contains more than this many instructions, it -will not be inlined. This option is precisely equivalent to -@option{-finline-limit}. +The tree inliner does decrease the allowable size for single functions +to be inlined after we already inlined the number of instructions +given here by repeated inlining. This number should be a factor of +two or more larger than the single function limit. +Higher numbers result in better runtime performance, but incur higher +compile-time resource (CPU time, memory) requirements and result in +larger binaries. Very high values are not advisable, as too large +binaries may adversely affect runtime performance. +The default value is 600. + +@item max-inline-slope +After exceeding the maximum number of inlined instructions by repeated +inlining, a linear function is used to decrease the allowable size +for single functions. The slope of that function is the negative +reciprocal of the number specified here. +The default value is 32. + +@item min-inline-insns +The repeated inlining is throttled more and more by the linear function +after exceeding the limit. To avoid too much throttling, a minimum for +this function is specified here to allow repeated inlining for very small +functions even when a lot of repeated inlining already has been done. +The default value is 130. + +@item max-inline-insns-rtl +For languages that use the RTL inliner (this happens at a later stage +than tree inlining), you can set the maximum allowable size (counted +in RTL instructions) for the RTL inliner with this parameter. +The default value is 600. + + +@item max-unrolled-insns +The maximum number of instructions that a loop should have if that loop +is unrolled, and if the loop is unrolled, it determines how many times +the loop code is unrolled. + +@item hot-bb-count-fraction +Select fraction of the maximal count of repetitions of basic block in program +given basic block needs to have to be considered hot. + +@item hot-bb-frequency-fraction +Select fraction of the maximal frequency of executions of basic block in +function given basic block needs to have to be considered hot + +@item tracer-dynamic-coverage +@itemx tracer-dynamic-coverage-feedback + +This value is used to limit superblock formation once the given percentage of +executed instructions is covered. This limits unnecessary code size +expansion. + +The @option{tracer-dynamic-coverage-feedback} is used only when profile +feedback is available. The real profiles (as opposed to statically estimated +ones) are much less balanced allowing the threshold to be larger value. + +@item tracer-max-code-growth +Stop tail duplication once code growth has reached given percentage. This is +rather hokey argument, as most of the duplicates will be eliminated later in +cross jumping, so it may be set to much higher values than is the desired code +growth. + +@item tracer-min-branch-ratio + +Stop reverse growth when the reverse probability of best edge is less than this +threshold (in percent). + +@item tracer-min-branch-ratio +@itemx tracer-min-branch-ratio-feedback + +Stop forward growth if the best edge do have probability lower than this +threshold. + +Similarly to @option{tracer-dynamic-coverage} two values are present, one for +compilation for profile feedback and one for compilation without. The value +for compilation with profile feedback needs to be more conservative (higher) in +order to make tracer effective. + +@item ggc-min-expand + +GCC uses a garbage collector to manage its own memory allocation. This +parameter specifies the minimum percentage by which the garbage +collector's heap should be allowed to expand between collections. +Tuning this may improve compilation speed; it has no effect on code +generation. + +The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when +RAM >= 1GB. If @code{getrlimit} is available, the notion of "RAM" is +the smallest of actual RAM, RLIMIT_RSS, RLIMIT_DATA and RLIMIT_AS. If +GCC is not able to calculate RAM on a particular platform, the lower +bound of 30% is used. Setting this parameter and +@option{ggc-min-heapsize} to zero causes a full collection to occur at +every opportunity. This is extremely slow, but can be useful for +debugging. + +@item ggc-min-heapsize + +Minimum size of the garbage collector's heap before it begins bothering +to collect garbage. The first collection occurs after the heap expands +by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again, +tuning this may improve compilation speed, and has no effect on code +generation. + +The default is RAM/8, with a lower bound of 4096 (four megabytes) and an +upper bound of 131072 (128 megabytes). If @code{getrlimit} is +available, the notion of "RAM" is the smallest of actual RAM, +RLIMIT_RSS, RLIMIT_DATA and RLIMIT_AS. If GCC is not able to calculate +RAM on a particular platform, the lower bound is used. Setting this +parameter very large effectively disables garbage collection. Setting +this parameter and @option{ggc-min-expand} to zero causes a full +collection to occur at every opportunity. @end table @end table @@ -4287,7 +4733,7 @@ If a standard system include directory, or a directory specified with option will be ignored. The directory will still be searched but as a system directory at its normal position in the system include chain. This is to ensure that GCC's procedure to fix buggy system headers and -the ordering for the include_next directive are not inadvertantly changed. +the ordering for the include_next directive are not inadvertently changed. If you really need to change the search order for system directories, use the @option{-nostdinc} and/or @option{-isystem} options. @@ -4377,6 +4823,7 @@ are processed in order, from left to right. @node Spec Files @section Specifying subprocesses and the switches to pass to them @cindex Spec Files + @command{gcc} is a driver program. It performs its job by invoking a sequence of other programs to do the work of compiling, assembling and linking. GCC interprets its command-line parameters and uses these to @@ -4725,6 +5172,41 @@ Substitute the variable part of a matched option. See below. Note that each comma in the substituted string is replaced by a single space. +@item %:@var{function}(@var{args}) +Call the named function @var{function}, passing it @var{args}. +@var{args} is first processed as a nested spec string, then split +into an argument vector in the usual fashion. The function returns +a string which is processed as if it had appeared literally as part +of the current spec. + +The following built-in spec functions are provided: + +@table @code +@item @code{if-exists} +The @code{if-exists} spec function takes one argument, an absolute +pathname to a file. If the file exists, @code{if-exists} returns the +pathname. Here is a small example of its usage: + +@smallexample +*startfile: +crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s +@end smallexample + +@item @code{if-exists-else} +The @code{if-exists-else} spec function is similar to the @code{if-exists} +spec function, except that it takes two arguments. The first argument is +an absolute pathname to a file. If the file exists, @code{if-exists-else} +returns the pathname. If it does not exist, it returns the second argument. +This way, @code{if-exists-else} can be used to select one file or another, +based on the existence of the first. Here is a small example of its usage: + +@smallexample +*startfile: +crt0%O%s %:if-exists(crti%O%s) \ +%:if-exists-else(crtbeginT%O%s crtbegin%O%s) +@end smallexample +@end table + @item %@{@code{S}@} Substitutes the @code{-S} switch, if that switch was given to GCC@. If that switch was not specified, this substitutes nothing. Note that @@ -4846,22 +5328,16 @@ proper position among the other output files. @cindex compiler version, specifying @cindex target machine, specifying -By default, GCC compiles code for the same type of machine that you -are using. However, it can also be installed as a cross-compiler, to -compile for some other type of machine. In fact, several different -configurations of GCC, for different target machines, can be -installed side by side. Then you specify which one to use with the -@option{-b} option. - -In addition, older and newer versions of GCC can be installed side -by side. One of them (probably the newest) will be the default, but -you may sometimes wish to use another. +The usual way to run GCC is to run the executable called @file{gcc}, or +@file{<machine>-gcc} when cross-compiling, or +@file{<machine>-gcc-<version>} to run a version other than the one that +was installed last. Sometimes this is inconvenient, so GCC provides +options that will switch to another cross-compiler or version. @table @gcctabopt @item -b @var{machine} @opindex b The argument @var{machine} specifies the target machine for compilation. -This is useful when you have installed GCC as a cross-compiler. The value to use for @var{machine} is the same as was specified as the machine type when configuring GCC as a cross-compiler. For @@ -4869,61 +5345,16 @@ example, if a cross-compiler was configured with @samp{configure i386v}, meaning to compile for an 80386 running System V, then you would specify @option{-b i386v} to run that cross compiler. -When you do not specify @option{-b}, it normally means to compile for -the same type of machine that you are using. - @item -V @var{version} @opindex V The argument @var{version} specifies which version of GCC to run. This is useful when multiple versions are installed. For example, @var{version} might be @samp{2.0}, meaning to run GCC version 2.0. - -The default version, when you do not specify @option{-V}, is the last -version of GCC that you installed. @end table -The @option{-b} and @option{-V} options actually work by controlling part of -the file name used for the executable files and libraries used for -compilation. A given version of GCC, for a given target machine, is -normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}. - -Thus, sites can customize the effect of @option{-b} or @option{-V} either by -changing the names of these directories or adding alternate names (or -symbolic links). If in directory @file{/usr/local/lib/gcc-lib/} the -file @file{80386} is a link to the file @file{i386v}, then @option{-b -80386} becomes an alias for @option{-b i386v}. - -In one respect, the @option{-b} or @option{-V} do not completely change -to a different compiler: the top-level driver program @command{gcc} -that you originally invoked continues to run and invoke the other -executables (preprocessor, compiler per se, assembler and linker) -that do the real work. However, since no real work is done in the -driver program, it usually does not matter that the driver program -in use is not the one for the specified target. It is common for the -interface to the other executables to change incompatibly between -compiler versions, so unless the version specified is very close to that -of the driver (for example, @option{-V 3.0} with a driver program from GCC -version 3.0.1), use of @option{-V} may not work; for example, using -@option{-V 2.95.2} will not work with a driver program from GCC 3.0. - -The only way that the driver program depends on the target machine is -in the parsing and handling of special machine-specific options. -However, this is controlled by a file which is found, along with the -other executables, in the directory for the specified version and -target machine. As a result, a single installed driver program adapts -to any specified target machine, and sufficiently similar compiler -versions. - -The driver program executable does control one significant thing, -however: the default version and target machine. Therefore, you can -install different instances of the driver program, compiled for -different targets or versions, under different names. - -For example, if the driver for version 2.0 is installed as @command{ogcc} -and that for version 2.1 is installed as @command{gcc}, then the command -@command{gcc} will use version 2.1 by default, while @command{ogcc} will use -2.0 by default. However, you can choose either version with either -command with the @option{-V} option. +The @option{-V} and @option{-b} options work by running the +@file{<machine>-gcc-<version>} executable, so there's no real reason to +use them if you can just run that directly. @node Submodel Options @section Hardware Models and Configurations @@ -4956,14 +5387,13 @@ that macro, which enables you to change the defaults. * M68hc1x Options:: * VAX Options:: * SPARC Options:: -* Convex Options:: -* AMD29K Options:: * ARM Options:: * MN10200 Options:: * MN10300 Options:: * M32R/D Options:: * M88K Options:: * RS/6000 and PowerPC Options:: +* Darwin Options:: * RT Options:: * MIPS Options:: * i386 and x86-64 Options:: @@ -4971,7 +5401,6 @@ that macro, which enables you to change the defaults. * Intel 960 Options:: * DEC Alpha Options:: * DEC Alpha/VMS Options:: -* Clipper Options:: * H8/300 Options:: * SH Options:: * System V Options:: @@ -4989,6 +5418,7 @@ that macro, which enables you to change the defaults. * PDP-11 Options:: * Xstormy16 Options:: * Xtensa Options:: +* FRV Options:: @end menu @node M680x0 Options @@ -5187,11 +5617,31 @@ when the compiler is configured for 68HC11-based systems. Generate output for a 68HC12. This is the default when the compiler is configured for 68HC12-based systems. +@item -m68S12 +@itemx -m68hcs12 +@opindex m68S12 +@opindex m68hcs12 +Generate output for a 68HCS12. + @item -mauto-incdec @opindex mauto-incdec Enable the use of 68HC12 pre and post auto-increment and auto-decrement addressing modes. +@item -minmax +@itemx -nominmax +@opindex minmax +@opindex mnominmax +Enable the use of 68HC12 min and max instructions. + +@item -mlong-calls +@itemx -mno-long-calls +@opindex mlong-calls +@opindex mno-long-calls +Treat all calls as being far away (near). If calls are assumed to be +far away, the compiler will use the @code{call} instruction to +call a function and the @code{rtc} instruction for returning. + @item -mshort @opindex mshort Consider type @code{int} to be 16 bits wide, like @code{short int}. @@ -5325,7 +5775,7 @@ With @option{-mfaster-structs}, the compiler assumes that structures should have 8 byte alignment. This enables the use of pairs of @code{ldd} and @code{std} instructions for copies in structure assignment, in place of twice as many @code{ld} and @code{st} pairs. -However, the use of this changed alignment directly violates the Sparc +However, the use of this changed alignment directly violates the SPARC ABI@. Thus, it's intended only for use on targets where the developer acknowledges that their resulting code will not be directly in line with the rules of the ABI@. @@ -5357,11 +5807,11 @@ They have been replaced with @option{-mcpu=xxx}. These two options select the processor for which the code is optimized. With @option{-mcypress} (the default), the compiler optimizes code for the -Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series. -This is also appropriate for the older SparcStation 1, 2, IPX etc. +Cypress CY7C602 chip, as used in the SPARCStation/SPARCServer 3xx series. +This is also appropriate for the older SPARCStation 1, 2, IPX etc. -With @option{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as -used in the SparcStation 10, 1000 and 2000 series. This flag also enables use +With @option{-msupersparc} the compiler optimizes code for the SuperSPARC cpu, as +used in the SPARCStation 10, 1000 and 2000 series. This flag also enables use of the full SPARC v8 instruction set. These options are deprecated and will be deleted in a future GCC release. @@ -5373,7 +5823,8 @@ Set the instruction set, register set, and instruction scheduling parameters for machine type @var{cpu_type}. Supported values for @var{cpu_type} are @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite}, @samp{hypersparc}, @samp{sparclite86x}, @samp{f930}, @samp{f934}, -@samp{sparclet}, @samp{tsc701}, @samp{v9}, and @samp{ultrasparc}. +@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc}, and +@samp{ultrasparc3}. Default instruction scheduling parameters are used for values that select an architecture and not an implementation. These are @samp{v7}, @samp{v8}, @@ -5387,7 +5838,7 @@ implementations. v8: supersparc, hypersparc sparclite: f930, f934, sparclite86x sparclet: tsc701 - v9: ultrasparc + v9: ultrasparc, ultrasparc3 @end smallexample @item -mtune=@var{cpu_type} @@ -5400,7 +5851,8 @@ The same values for @option{-mcpu=@var{cpu_type}} can be used for @option{-mtune=@var{cpu_type}}, but the only useful values are those that select a particular cpu implementation. Those are @samp{cypress}, @samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934}, -@samp{sparclite86x}, @samp{tsc701}, and @samp{ultrasparc}. +@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc}, and +@samp{ultrasparc3}. @end table @@ -5485,195 +5937,6 @@ when making stack frame references. Otherwise, assume no such offset is present. @end table -@node Convex Options -@subsection Convex Options -@cindex Convex options - -These @samp{-m} options are defined for Convex: - -@table @gcctabopt -@item -mc1 -@opindex mc1 -Generate output for C1. The code will run on any Convex machine. -The preprocessor symbol @code{__convex__c1__} is defined. - -@item -mc2 -@opindex mc2 -Generate output for C2. Uses instructions not available on C1. -Scheduling and other optimizations are chosen for max performance on C2. -The preprocessor symbol @code{__convex_c2__} is defined. - -@item -mc32 -@opindex mc32 -Generate output for C32xx. Uses instructions not available on C1. -Scheduling and other optimizations are chosen for max performance on C32. -The preprocessor symbol @code{__convex_c32__} is defined. - -@item -mc34 -@opindex mc34 -Generate output for C34xx. Uses instructions not available on C1. -Scheduling and other optimizations are chosen for max performance on C34. -The preprocessor symbol @code{__convex_c34__} is defined. - -@item -mc38 -@opindex mc38 -Generate output for C38xx. Uses instructions not available on C1. -Scheduling and other optimizations are chosen for max performance on C38. -The preprocessor symbol @code{__convex_c38__} is defined. - -@item -margcount -@opindex margcount -Generate code which puts an argument count in the word preceding each -argument list. This is compatible with regular CC, and a few programs -may need the argument count word. GDB and other source-level debuggers -do not need it; this info is in the symbol table. - -@item -mnoargcount -@opindex mnoargcount -Omit the argument count word. This is the default. - -@item -mvolatile-cache -@opindex mvolatile-cache -Allow volatile references to be cached. This is the default. - -@item -mvolatile-nocache -@opindex mvolatile-nocache -Volatile references bypass the data cache, going all the way to memory. -This is only needed for multi-processor code that does not use standard -synchronization instructions. Making non-volatile references to volatile -locations will not necessarily work. - -@item -mlong32 -@opindex mlong32 -Type long is 32 bits, the same as type int. This is the default. - -@item -mlong64 -@opindex mlong64 -Type long is 64 bits, the same as type long long. This option is useless, -because no library support exists for it. -@end table - -@node AMD29K Options -@subsection AMD29K Options -@cindex AMD29K options - -These @samp{-m} options are defined for the AMD Am29000: - -@table @gcctabopt -@item -mdw -@opindex mdw -@cindex DW bit (29k) -Generate code that assumes the @code{DW} bit is set, i.e., that byte and -halfword operations are directly supported by the hardware. This is the -default. - -@item -mndw -@opindex mndw -Generate code that assumes the @code{DW} bit is not set. - -@item -mbw -@opindex mbw -@cindex byte writes (29k) -Generate code that assumes the system supports byte and halfword write -operations. This is the default. - -@item -mnbw -@opindex mnbw -Generate code that assumes the systems does not support byte and -halfword write operations. @option{-mnbw} implies @option{-mndw}. - -@item -msmall -@opindex msmall -@cindex memory model (29k) -Use a small memory model that assumes that all function addresses are -either within a single 256 KB segment or at an absolute address of less -than 256k. This allows the @code{call} instruction to be used instead -of a @code{const}, @code{consth}, @code{calli} sequence. - -@item -mnormal -@opindex mnormal -Use the normal memory model: Generate @code{call} instructions only when -calling functions in the same file and @code{calli} instructions -otherwise. This works if each file occupies less than 256 KB but allows -the entire executable to be larger than 256 KB@. This is the default. - -@item -mlarge -@opindex mlarge -Always use @code{calli} instructions. Specify this option if you expect -a single file to compile into more than 256 KB of code. - -@item -m29050 -@opindex m29050 -@cindex processor selection (29k) -Generate code for the Am29050. - -@item -m29000 -@opindex m29000 -Generate code for the Am29000. This is the default. - -@item -mkernel-registers -@opindex mkernel-registers -@cindex kernel and user registers (29k) -Generate references to registers @code{gr64-gr95} instead of to -registers @code{gr96-gr127}. This option can be used when compiling -kernel code that wants a set of global registers disjoint from that used -by user-mode code. - -Note that when this option is used, register names in @samp{-f} flags -must use the normal, user-mode, names. - -@item -muser-registers -@opindex muser-registers -Use the normal set of global registers, @code{gr96-gr127}. This is the -default. - -@item -mstack-check -@itemx -mno-stack-check -@opindex mstack-check -@opindex mno-stack-check -@cindex stack checks (29k) -Insert (or do not insert) a call to @code{__msp_check} after each stack -adjustment. This is often used for kernel code. - -@item -mstorem-bug -@itemx -mno-storem-bug -@opindex mstorem-bug -@opindex mno-storem-bug -@cindex storem bug (29k) -@option{-mstorem-bug} handles 29k processors which cannot handle the -separation of a mtsrim insn and a storem instruction (most 29000 chips -to date, but not the 29050). - -@item -mno-reuse-arg-regs -@itemx -mreuse-arg-regs -@opindex mno-reuse-arg-regs -@opindex mreuse-arg-regs -@option{-mno-reuse-arg-regs} tells the compiler to only use incoming argument -registers for copying out arguments. This helps detect calling a function -with fewer arguments than it was declared with. - -@item -mno-impure-text -@itemx -mimpure-text -@opindex mno-impure-text -@opindex mimpure-text -@option{-mimpure-text}, used in addition to @option{-shared}, tells the compiler to -not pass @option{-assert pure-text} to the linker when linking a shared object. - -@item -msoft-float -@opindex msoft-float -Generate output containing library calls for floating point. -@strong{Warning:} the requisite libraries are not part of GCC@. -Normally the facilities of the machine's usual C compiler are used, but -this can't be done directly in cross-compilation. You must make your -own arrangements to provide suitable library functions for -cross-compilation. - -@item -mno-multm -@opindex mno-multm -Do not generate multm or multmu instructions. This is useful for some embedded -systems which do not have trap handlers for these instructions. -@end table - @node ARM Options @subsection ARM Options @cindex ARM options @@ -5803,7 +6066,7 @@ memory a feature of the ARM architecture allows a word load to be used, even if the address is unaligned, and the processor core will rotate the data as it is being loaded. This option tells the compiler that such misaligned accesses will cause a MMU trap and that it should instead -synthesise the access as a series of byte accesses. The compiler can +synthesize the access as a series of byte accesses. The compiler can still use word accesses to load half-word data if it knows that the address is aligned to a word boundary. @@ -5838,25 +6101,6 @@ These are deprecated aliases for @option{-malignment-traps}. @opindex mshort-load-words This are deprecated aliases for @option{-mno-alignment-traps}. -@item -mbsd -@opindex mbsd -This option only applies to RISC iX@. Emulate the native BSD-mode -compiler. This is the default if @option{-ansi} is not specified. - -@item -mxopen -@opindex mxopen -This option only applies to RISC iX@. Emulate the native X/Open-mode -compiler. - -@item -mno-symrename -@opindex mno-symrename -This option only applies to RISC iX@. Do not run the assembler -post-processor, @samp{symrename}, after code has been assembled. -Normally it is necessary to modify some of the standard symbols in -preparation for linking with the RISC iX C library; this option -suppresses this pass. The post-processor is never run when the -compiler is built for cross-compilation. - @item -mcpu=@var{name} @opindex mcpu This specifies the name of the target ARM processor. GCC uses this name @@ -6021,6 +6265,7 @@ of executing a function pointer if this option is enabled. @node MN10200 Options @subsection MN10200 Options @cindex MN10200 options + These @option{-m} options are defined for Matsushita MN10200 architectures: @table @gcctabopt @@ -6036,6 +6281,7 @@ This option makes symbolic debugging impossible. @node MN10300 Options @subsection MN10300 Options @cindex MN10300 options + These @option{-m} options are defined for Matsushita MN10300 architectures: @table @gcctabopt @@ -6198,9 +6444,9 @@ underscore as prefix on each name. Include (or omit) additional debugging information (about registers used in each stack frame) as specified in the 88open Object Compatibility Standard, ``OCS''@. This extra information allows debugging of code that -has had the frame pointer eliminated. The default for DG/UX, SVr4, and -Delta 88 SVr3.2 is to include this information; other 88k configurations -omit this information by default. +has had the frame pointer eliminated. The default for SVr4 and Delta 88 +SVr3.2 is to include this information; other 88k configurations omit this +information by default. @item -mocs-frame-position @opindex mocs-frame-position @@ -6208,7 +6454,7 @@ omit this information by default. When emitting COFF debugging information for automatic variables and parameters stored on the stack, use the offset from the canonical frame address, which is the stack pointer (register 31) on entry to the -function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use +function. The SVr4 and Delta88 SVr3.2, and BCS configurations use @option{-mocs-frame-position}; other 88k configurations have the default @option{-mno-ocs-frame-position}. @@ -6295,9 +6541,8 @@ that is used on System V release 4. SVr4. @end enumerate -@option{-msvr4} is the default for the m88k-motorola-sysv4 and -m88k-dg-dgux m88k configurations. @option{-msvr3} is the default for all -other m88k configurations. +@option{-msvr4} is the default for the m88k-motorola-sysv4 configuration. +@option{-msvr3} is the default for all other m88k configurations. @item -mversion-03.00 @opindex mversion-03.00 @@ -6503,7 +6748,7 @@ The @option{-mcpu} options automatically enable or disable other @table @samp @item common -@option{-mno-power}, @option{-mno-powerc} +@option{-mno-power}, @option{-mno-powerpc} @item power @itemx power2 @@ -6555,6 +6800,21 @@ allow access to the AltiVec instruction set. You may also need to set @option{-mabi=altivec} to adjust the current ABI with AltiVec ABI enhancements. +@item -mabi=spe +@opindex mabi=spe +Extend the current ABI with SPE ABI extensions. This does not change +the default ABI, instead it adds the SPE ABI extensions to the current +ABI@. + +@item -mabi=no-spe +@opindex mabi=no-spe +Disable Booke SPE ABI extensions for the current ABI. + +@item -misel=@var{yes/no} +@itemx -misel +@opindex misel +This switch enables or disables the generation of ISEL instructions. + @item -mfull-toc @itemx -mno-fp-in-toc @itemx -mno-sum-in-toc @@ -6844,6 +7104,10 @@ On embedded PowerPC systems, assume that the startup module is called On System V.4 and embedded PowerPC systems, specify that you are compiling for a VxWorks system. +@item -mwindiss +@opindex mwindiss +Specify that you are compiling for the WindISS simulation environment. + @item -memb @opindex memb On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags @@ -6928,6 +7192,24 @@ All modules should be compiled with the same @option{-G @var{num}} value. On System V.4 and embedded PowerPC systems do (do not) emit register names in the assembly language output using symbolic forms. +@item -mlongcall +@itemx -mno-longcall +@opindex mlongcall +@opindex mno-longcall +Default to making all function calls via pointers, so that functions +which reside further than 64 megabytes (67,108,864 bytes) from the +current location can be called. This setting can be overridden by the +@code{shortcall} function attribute, or by @code{#pragma longcall(0)}. + +Some linkers are capable of detecting out-of-range calls and generating +glue code on the fly. On these systems, long calls are unnecessary and +generate slower code. As of this writing, the AIX linker can do this, +as can the GNU linker for PowerPC/64. It is planned to add this feature +to the GNU linker for 32-bit PowerPC systems as well. + +In the future, we may cause GCC to ignore all longcall specifications +when the linker is known to generate glue. + @item -pthread @opindex pthread Adds support for multithreading with the @dfn{pthreads} library. @@ -6935,6 +7217,157 @@ This option sets flags for both the preprocessor and linker. @end table +@node Darwin Options +@subsection Darwin Options +@cindex Darwin options + +These options are defined for all architectures running the Darwin operating +system. These are useful for compatibility with other Mac OS compilers. + +@table @gcctabopt +@item -all_load +@opindex all_load +Loads all members of static archive libraries. +See man ld(1) for more information. + +@item -arch_errors_fatal +@opindex arch_errors_fatal +Cause the errors having to do with files that have the wrong architecture +to be fatal. + +@item -bind_at_load +@opindex bind_at_load +Causes the output file to be marked such that the dynamic linker will +bind all undefined references when the file is loaded or launched. + +@item -bundle +@opindex bundle +Produce a Mach-o bundle format file. +See man ld(1) for more information. + +@item -bundle_loader @var{executable} +@opindex bundle_loader +This specifies the @var{executable} that will be loading the build +output file being linked. See man ld(1) for more information. + +@item -allowable_client @var{client_name} +@item -arch_only + +@item -client_name +@item -compatibility_version +@item -current_version +@item -dependency-file +@item -dylib_file +@item -dylinker_install_name +@item -dynamic +@item -dynamiclib +@item -exported_symbols_list +@item -filelist +@item -flat_namespace +@item -force_cpusubtype_ALL +@item -force_flat_namespace +@item -headerpad_max_install_names +@item -image_base +@item -init +@item -install_name +@item -keep_private_externs +@item -multi_module +@item -multiply_defined +@item -multiply_defined_unused +@item -noall_load +@item -nomultidefs +@item -noprebind +@item -noseglinkedit +@item -pagezero_size +@item -prebind +@item -prebind_all_twolevel_modules +@item -private_bundle +@item -read_only_relocs +@item -sectalign +@item -sectobjectsymbols +@item -whyload +@item -seg1addr +@item -sectcreate +@item -sectobjectsymbols +@item -sectorder +@item -seg_addr_table +@item -seg_addr_table_filename +@item -seglinkedit +@item -segprot +@item -segs_read_only_addr +@item -segs_read_write_addr +@item -single_module +@item -static +@item -sub_library +@item -sub_umbrella +@item -twolevel_namespace +@item -umbrella +@item -undefined +@item -unexported_symbols_list +@item -weak_reference_mismatches +@item -whatsloaded + +@opindex allowable_client +@opindex arch_only +@opindex client_name +@opindex compatibility_version +@opindex current_version +@opindex dependency-file +@opindex dylib_file +@opindex dylinker_install_name +@opindex dynamic +@opindex dynamiclib +@opindex exported_symbols_list +@opindex filelist +@opindex flat_namespace +@opindex force_cpusubtype_ALL +@opindex force_flat_namespace +@opindex headerpad_max_install_names +@opindex image_base +@opindex init +@opindex install_name +@opindex keep_private_externs +@opindex multi_module +@opindex multiply_defined +@opindex multiply_defined_unused +@opindex noall_load +@opindex nomultidefs +@opindex noprebind +@opindex noseglinkedit +@opindex pagezero_size +@opindex prebind +@opindex prebind_all_twolevel_modules +@opindex private_bundle +@opindex read_only_relocs +@opindex sectalign +@opindex sectobjectsymbols +@opindex whyload +@opindex seg1addr +@opindex sectcreate +@opindex sectobjectsymbols +@opindex sectorder +@opindex seg_addr_table +@opindex seg_addr_table_filename +@opindex seglinkedit +@opindex segprot +@opindex segs_read_only_addr +@opindex segs_read_write_addr +@opindex single_module +@opindex static +@opindex sub_library +@opindex sub_umbrella +@opindex twolevel_namespace +@opindex umbrella +@opindex undefined +@opindex unexported_symbols_list +@opindex weak_reference_mismatches +@opindex whatsloaded + +This options are available for Darwin linker. Darwin linker man page +describes them in detail. +@end table + + @node RT Options @subsection IBM RT Options @cindex RT options @@ -6963,14 +7396,13 @@ Do not include extra scratch space in floating point data blocks. This results in smaller code, but slower execution, since scratch space must be allocated dynamically. -@cindex @file{varargs.h} and RT PC @cindex @file{stdarg.h} and RT PC @item -mfp-arg-in-fpregs @opindex mfp-arg-in-fpregs Use a calling sequence incompatible with the IBM calling convention in which floating point arguments are passed in floating point registers. -Note that @code{varargs.h} and @code{stdarg.h} will not work with -floating point operands if this option is specified. +Note that @code{stdarg.h} will not work with floating point operands +if this option is specified. @item -mfp-arg-in-gregs @opindex mfp-arg-in-gregs @@ -7000,65 +7432,77 @@ These @samp{-m} options are defined for the MIPS family of computers: @table @gcctabopt -@item -march=@var{cpu-type} +@item -march=@var{arch} @opindex march -Assume the defaults for the machine type @var{cpu-type} when generating -instructions. The choices for @var{cpu-type} are @samp{r2000}, @samp{r3000}, -@samp{r3900}, @samp{r4000}, @samp{r4100}, @samp{r4300}, @samp{r4400}, -@samp{r4600}, @samp{r4650}, @samp{r5000}, @samp{r6000}, @samp{r8000}, -and @samp{orion}. Additionally, the @samp{r2000}, @samp{r3000}, -@samp{r4000}, @samp{r5000}, and @samp{r6000} can be abbreviated as -@samp{r2k} (or @samp{r2K}), @samp{r3k}, etc. - -@item -mtune=@var{cpu-type} +Generate code that will run on @var{arch}, which can be the name of a +generic MIPS ISA, or the name of a particular processor. The ISA names +are: @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4}, @samp{mips32} +and @samp{mips64}. The processor names are: @samp{r2000}, +@samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{vr4100}, @samp{vr4300}, +@samp{r4400}, @samp{r4600}, @samp{r4650}, @samp{vr5000}, @samp{r6000}, +@samp{r8000}, @samp{4kc}, @samp{4kp}, @samp{5kc}, @samp{20kc}, +@samp{orion}, and @samp{sb1}. The special value @samp{from-abi} selects the +most compatible architecture for the selected ABI (that is, +@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@. + +In processor names, a final @samp{000} can be abbreviated as @samp{k} +(for example, @samp{-march=r2k}). Prefixes are optional, and +@samp{vr} may be written @samp{r}. + +GCC defines two macros based on the value of this option. The first +is @samp{_MIPS_ARCH}, which gives the name of target architecture, as +a string. The second has the form @samp{_MIPS_ARCH_@var{foo}}, +where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@. +For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH} +to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}. + +Note that the @samp{_MIPS_ARCH} macro uses the processor names given +above. In other words, it will have the full prefix and will not +abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi}, +the macro names the resolved architecture (either @samp{"mips1"} or +@samp{"mips3"}). It names the default architecture when no +@option{-march} option is given. + +@item -mtune=@var{arch} @opindex mtune -Assume the defaults for the machine type @var{cpu-type} when scheduling -instructions. The choices for @var{cpu-type} are @samp{r2000}, @samp{r3000}, -@samp{r3900}, @samp{r4000}, @samp{r4100}, @samp{r4300}, @samp{r4400}, -@samp{r4600}, @samp{r4650}, @samp{r5000}, @samp{r6000}, @samp{r8000}, -and @samp{orion}. Additionally, the @samp{r2000}, @samp{r3000}, -@samp{r4000}, @samp{r5000}, and @samp{r6000} can be abbreviated as -@samp{r2k} (or @samp{r2K}), @samp{r3k}, etc. While picking a specific -@var{cpu-type} will schedule things appropriately for that particular -chip, the compiler will not generate any code that does not meet level 1 -of the MIPS ISA (instruction set architecture) without a @option{-mipsX} -or @option{-mabi} switch being used. +Optimize for @var{arch}. Among other things, this option controls +the way instructions are scheduled, and the perceived cost of arithmetic +operations. The list of @var{arch} values is the same as for +@option{-march}. -@item -mcpu=@var{cpu-type} -@opindex mcpu -This is identical to specifying both @option{-march} and @option{-mtune}. +When this option is not used, GCC will optimize for the processor +specified by @option{-march}. By using @option{-march} and +@option{-mtune} together, it is possible to generate code that will +run on a family of processors, but optimize the code for one +particular member of that family. + +@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and +@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the +@samp{-march} ones described above. @item -mips1 @opindex mips1 -Issue instructions from level 1 of the MIPS ISA@. This is the default. -@samp{r3000} is the default @var{cpu-type} at this ISA level. +Equivalent to @samp{-march=mips1}. @item -mips2 @opindex mips2 -Issue instructions from level 2 of the MIPS ISA (branch likely, square -root instructions). @samp{r6000} is the default @var{cpu-type} at this -ISA level. +Equivalent to @samp{-march=mips2}. @item -mips3 @opindex mips3 -Issue instructions from level 3 of the MIPS ISA (64-bit instructions). -@samp{r4000} is the default @var{cpu-type} at this ISA level. +Equivalent to @samp{-march=mips3}. @item -mips4 @opindex mips4 -Issue instructions from level 4 of the MIPS ISA (conditional move, -prefetch, enhanced FPU instructions). @samp{r8000} is the default -@var{cpu-type} at this ISA level. +Equivalent to @samp{-march=mips4}. -@item -mfp32 -@opindex mfp32 -Assume that 32 32-bit floating point registers are available. This is -the default. +@item -mips32 +@opindex mips32 +Equivalent to @samp{-march=mips32}. -@item -mfp64 -@opindex mfp64 -Assume that 32 64-bit floating point registers are available. This is -the default when the @option{-mips3} option is used. +@item -mips64 +@opindex mips64 +Equivalent to @samp{-march=mips64}. @item -mfused-madd @itemx -mno-fused-madd @@ -7072,15 +7516,21 @@ in the mode where denormals are rounded to zero where denormals generated by multiply and accumulate instructions cause exceptions anyway. +@item -mfp32 +@opindex mfp32 +Assume that floating point registers are 32 bits wide. + +@item -mfp64 +@opindex mfp64 +Assume that floating point registers are 64 bits wide. + @item -mgp32 @opindex mgp32 -Assume that 32 32-bit general purpose registers are available. This is -the default. +Assume that general purpose registers are 32 bits wide. @item -mgp64 @opindex mgp64 -Assume that 32 64-bit general purpose registers are available. This is -the default when the @option{-mips3} option is used. +Assume that general purpose registers are 64 bits wide. @item -mint64 @opindex mint64 @@ -7096,31 +7546,32 @@ explanation of the default, and the width of pointers. @opindex mlong32 Force long, int, and pointer types to be 32 bits wide. -If none of @option{-mlong32}, @option{-mlong64}, or @option{-mint64} are set, -the size of ints, longs, and pointers depends on the ABI and ISA chosen. -For @option{-mabi=32}, and @option{-mabi=n32}, ints and longs are 32 bits -wide. For @option{-mabi=64}, ints are 32 bits, and longs are 64 bits wide. -For @option{-mabi=eabi} and either @option{-mips1} or @option{-mips2}, ints -and longs are 32 bits wide. For @option{-mabi=eabi} and higher ISAs, ints -are 32 bits, and longs are 64 bits wide. The width of pointer types is -the smaller of the width of longs or the width of general purpose -registers (which in turn depends on the ISA)@. +The default size of ints, longs and pointers depends on the ABI@. All +the supported ABIs use 32-bit ints. The n64 ABI uses 64-bit longs, as +does the 64-bit Cygnus EABI; the others use 32-bit longs. Pointers +are the same size as longs, or the same size as integer registers, +whichever is smaller. @item -mabi=32 @itemx -mabi=o64 @itemx -mabi=n32 @itemx -mabi=64 @itemx -mabi=eabi +@itemx -mabi=meabi @opindex mabi=32 @opindex mabi=o64 @opindex mabi=n32 @opindex mabi=64 @opindex mabi=eabi -Generate code for the indicated ABI@. The default instruction level is -@option{-mips1} for @samp{32}, @option{-mips3} for @samp{n32}, and -@option{-mips4} otherwise. Conversely, with @option{-mips1} or -@option{-mips2}, the default ABI is @samp{32}; otherwise, the default ABI -is @samp{64}. +@opindex mabi=meabi +Generate code for the given ABI@. + +Note that there are two embedded ABIs: @option{-mabi=eabi} +selects the one defined by Cygnus while @option{-meabi=meabi} +selects the one defined by MIPS@. Both these ABIs have +32-bit and 64-bit variants. Normally, GCC will generate +64-bit code when you select a 64-bit architecture, but you +can use @option{-mgp32} to get 32-bit code instead. @item -mmips-as @opindex mmips-as @@ -7343,12 +7794,19 @@ memory range for which the cache is being flushed, the size of the memory range, and the number 3 (to flush both caches). The default depends on the target gcc was configured for, but commonly is either @samp{_flush_func} or @samp{__cpu_flush}. -@end table -These options are defined by the macro -@code{TARGET_SWITCHES} in the machine description. The default for the -options is also defined by that macro, which enables you to change the -defaults. +@item -mbranch-likely +@itemx -mno-branch-likely +@opindex mbranch-likely +@opindex mno-branch-likely +Enable or disable use of Branch Likely instructions, regardless of the +default for the selected architecture. By default, Branch Likely +instructions may be generated if they are supported by the selected +architecture. An exception is for the MIPS32 and MIPS64 architectures +and processors which implement those architectures; for those, Branch +Likely instructions will not be generated by default because the MIPS32 +and MIPS64 architectures specifically deprecate their use. +@end table @node i386 and x86-64 Options @subsection Intel 386 and AMD x86-64 Options @@ -7368,8 +7826,8 @@ for the ABI and the set of available instructions. The choices for @var{cpu-type} are @samp{i386}, @samp{i486}, @samp{i586}, @samp{i686}, @samp{pentium}, @samp{pentium-mmx}, @samp{pentiumpro}, @samp{pentium2}, @samp{pentium3}, @samp{pentium4}, @samp{k6}, @samp{k6-2}, @samp{k6-3}, -@samp{athlon}, @samp{athlon-tbird}, @samp{athlon-4}, @samp{athlon-xp} -and @samp{athlon-mp}. +@samp{athlon}, @samp{athlon-tbird}, @samp{athlon-4}, @samp{athlon-xp}, +@samp{athlon-mp}, @samp{winchip-c6}, @samp{winchip2} and @samp{c3}. While picking a specific @var{cpu-type} will schedule things appropriately for that particular chip, the compiler will not generate any code that @@ -7405,7 +7863,7 @@ for @var{unit} are: @item 387 Use the standard 387 floating point coprocessor present majority of chips and emulated otherwise. Code compiled with this option will run almost everywhere. -The temporary results are computed in 80bit precesion instead of precision +The temporary results are computed in 80bit precision instead of precision specified by the type resulting in slightly different results compared to most of other chips. See @option{-ffloat-store} for more detailed description. @@ -7431,7 +7889,7 @@ code that expects temporaries to be 80bit. This is the default choice for x86-64 compiler. @item sse,387 -Attempt to utilize both instruction sets at once. This effectivly double the +Attempt to utilize both instruction sets at once. This effectively double the amount of available registers and on chips with separate execution units for 387 and SSE the execution resources too. Use this option with care, as it is still experimental, because gcc register allocator does not model separate @@ -7614,8 +8072,8 @@ direct access to the MMX, SSE and 3Dnow extensions of the instruction set. @xref{X86 Built-in Functions}, for details of the functions enabled and disabled by these switches. -To have SSE/SSE2 instructions generated automatically from floating-point code, -see @option{-mfpmath=sse}. +To have SSE/SSE2 instructions generated automatically from floating-point +code, see @option{-mfpmath=sse}. @item -mpush-args @itemx -mno-push-args @@ -7799,15 +8257,16 @@ Enable the use of assembler directives only GAS understands. @opindex mschedule Schedule code according to the constraints for the machine type @var{cpu-type}. The choices for @var{cpu-type} are @samp{700} -@samp{7100}, @samp{7100LC}, @samp{7200}, and @samp{8000}. Refer to -@file{/usr/lib/sched.models} on an HP-UX system to determine the -proper scheduling option for your machine. +@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer +to @file{/usr/lib/sched.models} on an HP-UX system to determine the +proper scheduling option for your machine. The default scheduling is +@samp{8000}. @item -mlinker-opt @opindex mlinker-opt -Enable the optimization pass in the HPUX linker. Note this makes symbolic -debugging impossible. It also triggers a bug in the HPUX 8 and HPUX 9 linkers -in which they give bogus error messages when linking some programs. +Enable the optimization pass in the HP-UX linker. Note this makes symbolic +debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9 +linkers in which they give bogus error messages when linking some programs. @item -msoft-float @opindex msoft-float @@ -7824,6 +8283,88 @@ therefore, it is only useful if you compile @emph{all} of a program with this option. In particular, you need to compile @file{libgcc.a}, the library that comes with GCC, with @option{-msoft-float} in order for this to work. + +@item -msio +@opindex msio +Generate the predefine, @code{_SIO}, for server IO. The default is +@option{-mwsio}. This generates the predefines, @code{__hp9000s700}, +@code{__hp9000s700__} and @code{_WSIO}, for workstation IO. These +options are available under HP-UX and HI-UX. + +@item -mgnu-ld +@opindex gnu-ld +Use GNU ld specific options. This passes @option{-shared} to ld when +building a shared library. It is the default when GCC is configured, +explicitly or implicitly, with the GNU linker. This option does not +have any affect on which ld is called, it only changes what parameters +are passed to that ld. The ld that is called is determined by the +@option{--with-ld} configure option, gcc's program search path, and +finally by the user's @env{PATH}. The linker used by GCC can be printed +using @samp{which `gcc -print-prog-name=ld`}. + +@item -mhp-ld +@opindex hp-ld +Use HP ld specific options. This passes @option{-b} to ld when building +a shared library and passes @option{+Accept TypeMismatch} to ld on all +links. It is the default when GCC is configured, explicitly or +implicitly, with the HP linker. This option does not have any affect on +which ld is called, it only changes what parameters are passed to that +ld. The ld that is called is determined by the @option{--with-ld} +configure option, gcc's program search path, and finally by the user's +@env{PATH}. The linker used by GCC can be printed using @samp{which +`gcc -print-prog-name=ld`}. + +@item -mlong-calls +@opindex mno-long-calls +Generate code that uses long call sequences. This ensures that a call +is always able to reach linker generated stubs. The default is to generate +long calls only when the distance from the call site to the beginning +of the function or translation unit, as the case may be, exceeds a +predefined limit set by the branch type being used. The limits for +normal calls are 7,600,000 and 240,000 bytes, respectively for the +PA 2.0 and PA 1.X architectures. Sibcalls are always limited at +240,000 bytes. + +Distances are measured from the beginning of functions when using the +@option{-ffunction-sections} option, or when using the @option{-mgas} +and @option{-mno-portable-runtime} options together under HP-UX with +the SOM linker. + +It is normally not desirable to use this option as it will degrade +performance. However, it may be useful in large applications, +particularly when partial linking is used to build the application. + +The types of long calls used depends on the capabilities of the +assembler and linker, and the type of code being generated. The +impact on systems that support long absolute calls, and long pic +symbol-difference or pc-relative calls should be relatively small. +However, an indirect call is used on 32-bit ELF systems in pic code +and it is quite long. + +@item -nolibdld +@opindex nolibdld +Suppress the generation of link options to search libdld.sl when the +@option{-static} option is specified on HP-UX 10 and later. + +@item -static +@opindex static +The HP-UX implementation of setlocale in libc has a dependency on +libdld.sl. There isn't an archive version of libdld.sl. Thus, +when the @option{-static} option is specified, special link options +are needed to resolve this dependency. + +On HP-UX 10 and later, the GCC driver adds the necessary options to +link with libdld.sl when the @option{-static} option is specified. +This causes the resulting binary to be dynamic. On the 64-bit port, +the linkers generate dynamic binaries by default in any case. The +@option{-nolibdld} option can be used to prevent the GCC driver from +adding these link options. + +@item -threads +@opindex threads +Add support for multithreading with the @dfn{dce thread} library +under HP-UX. This option sets flags for both the preprocessor and +linker. @end table @node Intel 960 Options @@ -8143,7 +8684,7 @@ arithmetic instead of IEEE single and double precision. @opindex mno-explicit-relocs Older Alpha assemblers provided no way to generate symbol relocations except via assembler macros. Use of these macros does not allow -optimial instruction scheduling. GNU binutils as of version 2.12 +optimal instruction scheduling. GNU binutils as of version 2.12 supports a new syntax that allows the compiler to explicitly mark which relocations should apply to which instructions. This option is mostly useful for debugging, as GCC detects the capabilities of @@ -8251,22 +8792,6 @@ Return VMS condition codes from main. The default is to return POSIX style condition (e.g.@ error) codes. @end table -@node Clipper Options -@subsection Clipper Options - -These @samp{-m} options are defined for the Clipper implementations: - -@table @gcctabopt -@item -mc300 -@opindex mc300 -Produce code for a C300 Clipper processor. This is the default. - -@item -mc400 -@opindex mc400 -Produce code for a C400 Clipper processor, i.e.@: use floating point -registers f8--f15. -@end table - @node H8/300 Options @subsection H8/300 Options @@ -8285,11 +8810,16 @@ Generate code for the H8/300H@. @item -ms @opindex ms -Generate code for the H8/S@. +Generate code for the H8S@. + +@item -mn +@opindex mn +Generate code for the H8S and H8/300H in the normal mode. This switch +must be used either with -mh or -ms. @item -ms2600 @opindex ms2600 -Generate code for the H8/S2600. This switch must be used with @option{-ms}. +Generate code for the H8S/2600. This switch must be used with @option{-ms}. @item -mint32 @opindex mint32 @@ -8297,8 +8827,8 @@ Make @code{int} data 32 bits by default. @item -malign-300 @opindex malign-300 -On the H8/300H and H8/S, use the same alignment rules as for the H8/300. -The default for the H8/300H and H8/S is to align longs and floats on 4 +On the H8/300H and H8S, use the same alignment rules as for the H8/300. +The default for the H8/300H and H8S is to align longs and floats on 4 byte boundaries. @option{-malign-300} causes them to be aligned on 2 byte boundaries. This option has no effect on the H8/300. @@ -8374,7 +8904,7 @@ Enable the use of the instruction @code{fmovd}. @item -mhitachi @opindex mhitachi -Comply with the calling conventions defined by Hitachi. +Comply with the calling conventions defined by Renesas. @item -mnomacsave @opindex mnomacsave @@ -8493,10 +9023,10 @@ DBcond(D), instructions. This is enabled by default for the C4x. To be on the safe side, this is disabled for the C3x, since the maximum iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than @math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so -that it can utilise the decrement and branch instruction, but will give +that it can utilize the decrement and branch instruction, but will give up if there is more than one memory reference in the loop. Thus a loop where the loop counter is decremented can generate slightly more -efficient code, in cases where the RPTB instruction cannot be utilised. +efficient code, in cases where the RPTB instruction cannot be utilized. @item -mdp-isr-reload @itemx -mparanoid @@ -8663,6 +9193,34 @@ Specify that the target processor is the V850. Generate code suitable for big switch tables. Use this option only if the assembler/linker complain about out of range branches within a switch table. + +@item -mapp-regs +@opindex mapp-regs +This option will cause r2 and r5 to be used in the code generated by +the compiler. This setting is the default. + +@item -mno-app-regs +@opindex mno-app-regs +This option will cause r2 and r5 to be treated as fixed registers. + +@item -mv850e +@opindex mv850e +Specify that the target processor is the V850E. The preprocessor +constant @samp{__v850e__} will be defined if this option is used. + +If neither @option{-mv850} nor @option{-mv850e} are defined +then a default target processor will be chosen and the relevant +@samp{__v850*__} preprocessor constant will be defined. + +The preprocessor constants @samp{__v850} and @samp{__v851__} are always +defined, regardless of which processor variant is the target. + +@item -mdisable-callt +@opindex mdisable-callt +This option will suppress generation of the CALLT instruction for the +v850e flavors of the v850 architecture. The default is +@option{-mno-disable-callt} which allows the CALLT instruction to be used. + @end table @node ARC Options @@ -8769,6 +9327,15 @@ Do not try and generate multiply-add floating point instructions Generate output containing library calls for floating point. @strong{Warning:} the requisite libraries may not be available. +@item -mieee-compare +@itemx -mno-ieee-compare +@opindex mieee-compare +@opindex mno-ieee-compare +Control whether or not the compiler uses IEEE floating point +comparisons. These handle correctly the case where the result of a +comparison is unordered. +@strong{Warning:} the requisite kernel support may not be available. + @item -mnobitfield @opindex mnobitfield Do not use the bit-field instructions. On some machines it is faster to @@ -8910,75 +9477,57 @@ processors. @table @gcctabopt @item -mhardlit -@itemx -mhardlit @itemx -mno-hardlit @opindex mhardlit -@opindex mhardlit @opindex mno-hardlit Inline constants into the code stream if it can be done in two instructions or less. @item -mdiv -@itemx -mdiv @itemx -mno-div @opindex mdiv -@opindex mdiv @opindex mno-div Use the divide instruction. (Enabled by default). @item -mrelax-immediate -@itemx -mrelax-immediate @itemx -mno-relax-immediate @opindex mrelax-immediate -@opindex mrelax-immediate @opindex mno-relax-immediate Allow arbitrary sized immediates in bit operations. @item -mwide-bitfields -@itemx -mwide-bitfields @itemx -mno-wide-bitfields @opindex mwide-bitfields -@opindex mwide-bitfields @opindex mno-wide-bitfields Always treat bit-fields as int-sized. @item -m4byte-functions -@itemx -m4byte-functions @itemx -mno-4byte-functions @opindex m4byte-functions -@opindex m4byte-functions @opindex mno-4byte-functions Force all functions to be aligned to a four byte boundary. @item -mcallgraph-data -@itemx -mcallgraph-data @itemx -mno-callgraph-data @opindex mcallgraph-data -@opindex mcallgraph-data @opindex mno-callgraph-data Emit callgraph information. @item -mslow-bytes -@itemx -mslow-bytes @itemx -mno-slow-bytes @opindex mslow-bytes -@opindex mslow-bytes @opindex mno-slow-bytes Prefer word access when reading byte quantities. @item -mlittle-endian -@itemx -mlittle-endian @itemx -mbig-endian @opindex mlittle-endian -@opindex mlittle-endian @opindex mbig-endian Generate code for a little endian target. @item -m210 -@itemx -m210 @itemx -m340 @opindex m210 -@opindex m210 @opindex m340 Generate code for the 210 processor. @end table @@ -8992,7 +9541,7 @@ These are the @samp{-m} options defined for the Intel IA-64 architecture. @table @gcctabopt @item -mbig-endian @opindex mbig-endian -Generate code for a big endian target. This is the default for HPUX@. +Generate code for a big endian target. This is the default for HP-UX@. @item -mlittle-endian @opindex mlittle-endian @@ -9055,13 +9604,25 @@ useful when compiling kernel code. Generate code that is self-relocatable. This implies @option{-mconstant-gp}. This is useful when compiling firmware code. -@item -minline-divide-min-latency -@opindex minline-divide-min-latency -Generate code for inline divides using the minimum latency algorithm. +@item -minline-float-divide-min-latency +@opindex minline-float-divide-min-latency +Generate code for inline divides of floating point values +using the minimum latency algorithm. + +@item -minline-float-divide-max-throughput +@opindex minline-float-divide-max-throughput +Generate code for inline divides of floating point values +using the maximum throughput algorithm. -@item -minline-divide-max-throughput -@opindex minline-divide-max-throughput -Generate code for inline divides using the maximum throughput algorithm. +@item -minline-int-divide-min-latency +@opindex minline-int-divide-min-latency +Generate code for inline divides of integer values +using the minimum latency algorithm. + +@item -minline-int-divide-max-throughput +@opindex minline-int-divide-max-throughput +Generate code for inline divides of integer values +using the maximum throughput algorithm. @item -mno-dwarf2-asm @itemx -mdwarf2-asm @@ -9175,7 +9736,7 @@ targets default to @option{-m64}. @opindex mmvcle @opindex mno-mvcle Generate (or do not generate) code using the @code{mvcle} instruction -to perform block moves. When @option{-mno-mvcle} is specifed, +to perform block moves. When @option{-mno-mvcle} is specified, use a @code{mvc} loop instead. This is the default. @item -mdebug @@ -9401,6 +9962,13 @@ to 255 from the value held in the register. The generally leads to short and fast code, but the number of different data items that can be addressed is limited. This means that a program that uses lots of static data may require @option{-mno-base-addresses}. + +@item -msingle-exit +@itemx -mno-single-exit +@opindex msingle-exit +@opindex mno-single-exit +Force (do not force) generated code to have a single exit point in each +function. @end table @node PDP-11 Options @@ -9520,6 +10088,233 @@ These options are defined for Xstormy16: Choose startup files and linker script suitable for the simulator. @end table +@node FRV Options +@subsection FRV Options +@cindex FRV Options + +@table @gcctabopt +@item -mgpr-32 +@opindex mgpr-32 + +Only use the first 32 general purpose registers. + +@item -mgpr-64 +@opindex mgpr-64 + +Use all 64 general purpose registers. + +@item -mfpr-32 +@opindex mfpr-32 + +Use only the first 32 floating point registers. + +@item -mfpr-64 +@opindex mfpr-64 + +Use all 64 floating point registers + +@item -mhard-float +@opindex mhard-float + +Use hardware instructions for floating point operations. + +@item -msoft-float +@opindex msoft-float + +Use library routines for floating point operations. + +@item -malloc-cc +@opindex malloc-cc + +Dynamically allocate condition code registers. + +@item -mfixed-cc +@opindex mfixed-cc + +Do not try to dynamically allocate condition code registers, only +use @code{icc0} and @code{fcc0}. + +@item -mdword +@opindex mdword + +Change ABI to use double word insns. + +@item -mno-dword +@opindex mno-dword + +Do not use double word instructions. + +@item -mdouble +@opindex mdouble + +Use floating point double instructions. + +@item -mno-double +@opindex mno-double + +Do not use floating point double instructions. + +@item -mmedia +@opindex mmedia + +Use media instructions. + +@item -mno-media +@opindex mno-media + +Do not use media instructions. + +@item -mmuladd +@opindex mmuladd + +Use multiply and add/subtract instructions. + +@item -mno-muladd +@opindex mno-muladd + +Do not use multiply and add/subtract instructions. + +@item -mlibrary-pic +@opindex mlibrary-pic + +Enable PIC support for building libraries + +@item -macc-4 +@opindex macc-4 + +Use only the first four media accumulator registers. + +@item -macc-8 +@opindex macc-8 + +Use all eight media accumulator registers. + +@item -mpack +@opindex mpack + +Pack VLIW instructions. + +@item -mno-pack +@opindex mno-pack + +Do not pack VLIW instructions. + +@item -mno-eflags +@opindex mno-eflags + +Do not mark ABI switches in e_flags. + +@item -mcond-move +@opindex mcond-move + +Enable the use of conditional-move instructions (default). + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mno-cond-move +@opindex mno-cond-move + +Disable the use of conditional-move instructions. + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mscc +@opindex mscc + +Enable the use of conditional set instructions (default). + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mno-scc +@opindex mno-scc + +Disable the use of conditional set instructions. + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mcond-exec +@opindex mcond-exec + +Enable the use of conditional execution (default). + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mno-cond-exec +@opindex mno-cond-exec + +Disable the use of conditional execution. + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mvliw-branch +@opindex mvliw-branch + +Run a pass to pack branches into VLIW instructions (default). + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mno-vliw-branch +@opindex mno-vliw-branch + +Do not run a pass to pack branches into VLIW instructions. + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mmulti-cond-exec +@opindex mmulti-cond-exec + +Enable optimization of @code{&&} and @code{||} in conditional execution +(default). + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mno-multi-cond-exec +@opindex mno-multi-cond-exec + +Disable optimization of @code{&&} and @code{||} in conditional execution. + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mnested-cond-exec +@opindex mnested-cond-exec + +Enable nested conditional execution optimizations (default). + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mno-nested-cond-exec +@opindex mno-nested-cond-exec + +Disable nested conditional execution optimizations. + +This switch is mainly for debugging the compiler and will likely be removed +in a future version. + +@item -mtomcat-stats +@opindex mtomcat-stats + +Cause gas to print out tomcat statistics. + +@item -mcpu=@var{cpu} +@opindex mcpu + +Select the processor type for which to generate code. Possible values are +@samp{simple}, @samp{tomcat}, @samp{fr500}, @samp{fr400}, @samp{fr300}, +@samp{frv}. + +@end table + @node Xtensa Options @subsection Xtensa Options @cindex Xtensa Options @@ -9709,6 +10504,18 @@ can figure out the other form by either removing @samp{no-} or adding it. @table @gcctabopt +@item -fbounds-check +@opindex fbounds-check +For front-ends that support it, generate additional code to check that +indices used to access arrays are within the declared range. This is +currently only supported by the Java and Fortran 77 front-ends, where +this option defaults to true and false respectively. + +@item -ftrapv +@opindex ftrapv +This option generates traps for signed overflow on addition, subtraction, +multiplication operations. + @item -fexceptions @opindex fexceptions Enable exception handling. Generates extra code needed to propagate @@ -9887,7 +10694,7 @@ loader is not part of GCC; it is part of the operating system). If the GOT size for the linked executable exceeds a machine-specific maximum size, you get an error message from the linker indicating that @option{-fpic} does not work; in that case, recompile with @option{-fPIC} -instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k +instead. (These maximums are 16k on the m88k, 8k on the SPARC, and 32k on the m68k and RS/6000. The 386 has no such limit.) Position-independent code requires special support, and therefore works @@ -9900,7 +10707,7 @@ position-independent. If supported for the target machine, emit position-independent code, suitable for dynamic linking and avoiding any limit on the size of the global offset table. This option makes a difference on the m68k, m88k, -and the Sparc. +and the SPARC. Position-independent code requires special support, and therefore works only on certain machines. @@ -9955,7 +10762,7 @@ Pack all structure members together without holes. @strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate code that is not binary compatible with code generated without that switch. -Additionally, it makes the code suboptimial. +Additionally, it makes the code suboptimal. Use it to conform to a non-default application binary interface. @item -finstrument-functions @@ -10057,6 +10864,14 @@ is to help link with legacy assembly code. generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface. Not all targets provide complete support for this switch. + +@item -ftls-model=@var{model} +Alter the thread-local storage model to be used (@pxref{Thread-Local}). +The @var{model} argument should be one of @code{global-dynamic}, +@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. + +The default without @option{-fpic} is @code{initial-exec}; with +@option{-fpic} the default is @code{global-dynamic}. @end table @c man end @@ -10066,7 +10881,6 @@ Not all targets provide complete support for this switch. @cindex environment variables @c man begin ENVIRONMENT - This section describes several environment variables that affect how GCC operates. Some of them work by specifying directories or prefixes to use when searching for various kinds of files. Some are used to specify other @@ -10275,16 +11089,16 @@ prototype information about standard system functions. This option applies only to @code{protoize}. @item -c @var{compilation-options} -Use @var{compilation-options} as the options when running @code{gcc} to +Use @var{compilation-options} as the options when running @command{gcc} to produce the @samp{.X} files. The special option @option{-aux-info} is -always passed in addition, to tell @code{gcc} to write a @samp{.X} file. +always passed in addition, to tell @command{gcc} to write a @samp{.X} file. Note that the compilation options must be given as a single argument to @code{protoize} or @code{unprotoize}. If you want to specify several -@code{gcc} options, you must quote the entire set of compilation options +@command{gcc} options, you must quote the entire set of compilation options to make them a single word in the shell. -There are certain @code{gcc} arguments that you cannot use, because they +There are certain @command{gcc} arguments that you cannot use, because they would produce the wrong kind of output. These include @option{-g}, @option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in the @var{compilation-options}, they are ignored. @@ -10337,12 +11151,12 @@ Use the program @var{program} as the compiler. Normally, the name Work quietly. Most warnings are suppressed. @item -v -Print the version number, just like @option{-v} for @code{gcc}. +Print the version number, just like @option{-v} for @command{gcc}. @end table If you need special compiler options to compile one of your program's source files, then you should generate that file's @samp{.X} file -specially, by running @code{gcc} on that source file with the +specially, by running @command{gcc} on that source file with the appropriate options and the option @option{-aux-info}. Then run @code{protoize} on the entire set of files. @code{protoize} will use the existing @samp{.X} file because it is newer than the source file. diff --git a/contrib/gcc/doc/makefile.texi b/contrib/gcc/doc/makefile.texi index 6d6b025..1e64c5e 100644 --- a/contrib/gcc/doc/makefile.texi +++ b/contrib/gcc/doc/makefile.texi @@ -13,18 +13,18 @@ This is the default target. Depending on what your build/host/target configuration is, it coordinates all the things that need to be built. @item doc -Produce info-formatted documentation. Also, @code{make dvi} is -available for DVI-formatted documentation, and @code{make +Produce info-formatted documentation. Also, @samp{make dvi} is +available for DVI-formatted documentation, and @samp{make generated-manpages} to generate man pages. @item mostlyclean Delete the files made while building the compiler. @item clean -That, and all the other files built by @code{make all}. +That, and all the other files built by @samp{make all}. @item distclean -That, and all the files created by @code{configure}. +That, and all the files created by @command{configure}. @item extraclean That, and any temporary or intermediate files, like emacs backup files. @@ -43,7 +43,7 @@ Deletes installed files. @item check Run the testsuite. This creates a @file{testsuite} subdirectory that has various @file{.sum} and @file{.log} files containing the results of -the testing. You can run subsets with, for example, @code{make check-gcc}. +the testing. You can run subsets with, for example, @samp{make check-gcc}. You can specify specific tests by setting RUNTESTFLAGS to be the name of the @file{.exp} file, optionally followed by (for some tests) an equals and a file wildcard, like: @@ -59,7 +59,7 @@ installed, such as TCL or dejagnu. Builds gcc three times---once with the native compiler, once with the native-built compiler it just built, and once with the compiler it built the second time. In theory, the last two should produce the same -results, which @code{make compare} can check. Each step of this process +results, which @samp{make compare} can check. Each step of this process is called a ``stage'', and the results of each stage @var{N} (@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}. @@ -81,7 +81,7 @@ special invocation, using this target means you don't have to keep track of which stage you're on or what invocation that stage needs. @item cleanstrap -Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}). +Removed everything (@samp{make clean}) and rebuilds (@samp{make bootstrap}). @item stage@var{N} (@var{N} = 1@dots{}4) For each stage, moves the appropriate files to the @file{stage@var{N}} diff --git a/contrib/gcc/doc/md.texi b/contrib/gcc/doc/md.texi index b38ef5e..6184fc3 100644 --- a/contrib/gcc/doc/md.texi +++ b/contrib/gcc/doc/md.texi @@ -845,8 +845,8 @@ that of the host machine (on which the compiler is running). @cindex @samp{F} in constraint @item @samp{F} -An immediate floating operand (expression code @code{const_double}) is -allowed. +An immediate floating operand (expression code @code{const_double} or +@code{const_vector}) is allowed. @cindex @samp{G} in constraint @cindex @samp{H} in constraint @@ -898,7 +898,7 @@ digit is used together with letters within the same alternative, the digit should come last. This number is allowed to be more than a single digit. If multiple -digits are encountered consecutavely, they are interpreted as a single +digits are encountered consecutively, they are interpreted as a single decimal integer. There is scant chance for ambiguity, since to-date it has never been desirable that @samp{10} be interpreted as matching either operand 1 @emph{or} operand 0. Should this be desired, one @@ -965,7 +965,7 @@ The machine description macro @code{REG_CLASS_FROM_LETTER} has first cut at the otherwise unused letters. If it evaluates to @code{NO_REGS}, then @code{EXTRA_CONSTRAINT} is evaluated. -A typical use for @code{EXTRA_CONSTRANT} would be to distinguish certain +A typical use for @code{EXTRA_CONSTRAINT} would be to distinguish certain types of memory references that affect other insn operands. @end ifset @end table @@ -1256,6 +1256,8 @@ instruction is defined: @dots{}) @end smallexample @end ifset +GCC can only handle one commutative pair in an asm; if you use more, +the compiler may fail. @cindex @samp{#} in constraint @item # @@ -1374,60 +1376,6 @@ An item in the constant pool A symbol in the text segment of the current file @end table -@item AMD 29000 family---@file{a29k.h} -@table @code -@item l -Local register 0 - -@item b -Byte Pointer (@samp{BP}) register - -@item q -@samp{Q} register - -@item h -Special purpose register - -@item A -First accumulator register - -@item a -Other accumulator register - -@item f -Floating point register - -@item I -Constant greater than 0, less than 0x100 - -@item J -Constant greater than 0, less than 0x10000 - -@item K -Constant whose high 24 bits are on (1) - -@item L -16-bit constant whose high 8 bits are on (1) - -@item M -32-bit constant whose high 16 bits are on (1) - -@item N -32-bit negative constant that fits in 8 bits - -@item O -The constant 0x80000000 or, on the 29050, any 32-bit constant -whose low 16 bits are 0. - -@item P -16-bit negative constant that fits in 8 bits - -@item G -@itemx H -A floating point constant (in @code{asm} statements, use the machine -independent @samp{E} or @samp{F} instead) -@end table - @item AVR family---@file{avr.h} @table @code @item l @@ -1606,6 +1554,10 @@ Second floating point register @item c @samp{c} register +@item C +Specifies constant that can be easily constructed in SSE register without +loading it from memory. + @item d @samp{d} register @@ -1681,6 +1633,232 @@ Floating point 0 Floating point 1 @end table +@item Intel IA-64---@file{ia64.h} +@table @code +@item a +General register @code{r0} to @code{r3} for @code{addl} instruction + +@item b +Branch register + +@item c +Predicate register (@samp{c} as in ``conditional'') + +@item d +Application register residing in M-unit + +@item e +Application register residing in I-unit + +@item f +Floating-point register + +@item m +Memory operand. +Remember that @samp{m} allows postincrement and postdecrement which +require printing with @samp{%Pn} on IA-64. +Use @samp{S} to disallow postincrement and postdecrement. + +@item G +Floating-point constant 0.0 or 1.0 + +@item I +14-bit signed integer constant + +@item J +22-bit signed integer constant + +@item K +8-bit signed integer constant for logical instructions + +@item L +8-bit adjusted signed integer constant for compare pseudo-ops + +@item M +6-bit unsigned integer constant for shift counts + +@item N +9-bit signed integer constant for load and store postincrements + +@item O +The constant zero + +@item P +0 or -1 for @code{dep} instruction + +@item Q +Non-volatile memory for floating-point loads and stores + +@item R +Integer constant in the range 1 to 4 for @code{shladd} instruction + +@item S +Memory operand except postincrement and postdecrement +@end table + +@item FRV---@file{frv.h} +@table @code +@item a +Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}). + +@item b +Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}). + +@item c +Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and +@code{icc0} to @code{icc3}). + +@item d +Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}). + +@item e +Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}). +Odd registers are excluded not in the class but through the use of a machine +mode larger than 4 bytes. + +@item f +Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}). + +@item h +Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}). +Odd registers are excluded not in the class but through the use of a machine +mode larger than 4 bytes. + +@item l +Register in the class @code{LR_REG} (the @code{lr} register). + +@item q +Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}). +Register numbers not divisible by 4 are excluded not in the class but through +the use of a machine mode larger than 8 bytes. + +@item t +Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}). + +@item u +Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}). + +@item v +Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}). + +@item w +Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}). + +@item x +Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}). +Register numbers not divisible by 4 are excluded not in the class but through +the use of a machine mode larger than 8 bytes. + +@item z +Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}). + +@item A +Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}). + +@item B +Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}). + +@item C +Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}). + +@item G +Floating point constant zero + +@item I +6-bit signed integer constant + +@item J +10-bit signed integer constant + +@item L +16-bit signed integer constant + +@item M +16-bit unsigned integer constant + +@item N +12-bit signed integer constant that is negative---i.e.@: in the +range of @minus{}2048 to @minus{}1 + +@item O +Constant zero + +@item P +12-bit signed integer constant that is greater than zero---i.e.@: in the +range of 1 to 2047. + +@end table + +@item IP2K---@file{ip2k.h} +@table @code +@item a +@samp{DP} or @samp{IP} registers (general address) + +@item f +@samp{IP} register + +@item j +@samp{IPL} register + +@item k +@samp{IPH} register + +@item b +@samp{DP} register + +@item y +@samp{DPH} register + +@item z +@samp{DPL} register + +@item q +@samp{SP} register + +@item c +@samp{DP} or @samp{SP} registers (offsettable address) + +@item d +Non-pointer registers (not @samp{SP}, @samp{DP}, @samp{IP}) + +@item u +Non-SP registers (everything except @samp{SP}) + +@item R +Indirect thru @samp{IP} - Avoid this except for @code{QImode}, since we +can't access extra bytes + +@item S +Indirect thru @samp{SP} or @samp{DP} with short displacement (0..127) + +@item T +Data-section immediate value + +@item I +Integers from @minus{}255 to @minus{}1 + +@item J +Integers from 0 to 7---valid bit number in a register + +@item K +Integers from 0 to 127---valid displacement for addressing mode + +@item L +Integers from 1 to 127 + +@item M +Integer @minus{}1 + +@item N +Integer 1 + +@item O +Zero + +@item P +Integers from 0 to 255 +@end table + @item MIPS---@file{mips.h} @table @code @item d @@ -1846,10 +2024,27 @@ Constants in the range @minus{}8 to 2 @item SPARC---@file{sparc.h} @table @code @item f -Floating-point register that can hold 32- or 64-bit values. +Floating-point register on the SPARC-V8 architecture and +lower floating-point register on the SPARC-V9 architecture. @item e -Floating-point register that can hold 64- or 128-bit values. +Floating-point register. It is equivalent to @samp{f} on the +SPARC-V8 architecture and contains both lower and upper +floating-point registers on the SPARC-V9 architecture. + +@item c +Floating-point condition code register. + +@item d +Lower floating-point register. It is only valid on the SPARC-V9 +architecture when the Visual Instruction Set is available. + +@item b +Floating-point register. It is only valid on the SPARC-V9 architecture +when the Visual Instruction Set is available. + +@item h +64-bit global or out register for the SPARC-V8+ architecture. @item I Signed 13-bit constant @@ -1872,6 +2067,9 @@ Same as @samp{K}, except that it verifies that bits that are not in the lower 32-bit range are all zero. Must be used instead of @samp{K} for modes wider than @code{SImode} +@item O +The constant 4096 + @item G Floating-point zero @@ -2074,7 +2272,7 @@ A memory reference that is a stack push. A memory reference that is a stack pop. @item S -A memory reference that refers to an constant address of known value. +A memory reference that refers to a constant address of known value. @item T The register indicated by Rx (not implemented yet). @@ -2262,8 +2460,7 @@ Write the generated insn as a @code{parallel} with elements being a @code{set} of one register from the appropriate memory location (you may also need @code{use} or @code{clobber} elements). Use a @code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See -@file{a29k.md} and @file{rs6000.md} for examples of the use of this insn -pattern. +@file{rs6000.md} for examples of the use of this insn pattern. @cindex @samp{store_multiple} instruction pattern @item @samp{store_multiple} @@ -2274,7 +2471,7 @@ operand 2 is a constant: the number of consecutive registers. @cindex @code{push@var{m}} instruction pattern @item @samp{push@var{m}} -Output an push instruction. Operand 0 is value to push. Used only when +Output a push instruction. Operand 0 is value to push. Used only when @code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be missing and in such case an @code{mov} expander is used instead, with a @code{MEM} expression forming the push operation. The @code{mov} expander @@ -2390,7 +2587,45 @@ Store the absolute value of operand 1 into operand 0. Store the square root of operand 1 into operand 0. The @code{sqrt} built-in function of C always uses the mode which -corresponds to the C data type @code{double}. +corresponds to the C data type @code{double} and the @code{sqrtf} +built-in function uses the mode which corresponds to the C data +type @code{float}. + +@cindex @code{cos@var{m}2} instruction pattern +@item @samp{cos@var{m}2} +Store the cosine of operand 1 into operand 0. + +The @code{cos} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{cosf} +built-in function uses the mode which corresponds to the C data +type @code{float}. + +@cindex @code{sin@var{m}2} instruction pattern +@item @samp{sin@var{m}2} +Store the sine of operand 1 into operand 0. + +The @code{sin} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{sinf} +built-in function uses the mode which corresponds to the C data +type @code{float}. + +@cindex @code{exp@var{m}2} instruction pattern +@item @samp{exp@var{m}2} +Store the exponential of operand 1 into operand 0. + +The @code{exp} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{expf} +built-in function uses the mode which corresponds to the C data +type @code{float}. + +@cindex @code{log@var{m}2} instruction pattern +@item @samp{log@var{m}2} +Store the natural logarithm of operand 1 into operand 0. + +The @code{log} built-in function of C always uses the mode which +corresponds to the C data type @code{double} and the @code{logf} +built-in function uses the mode which corresponds to the C data +type @code{float}. @cindex @code{ffs@var{m}2} instruction pattern @item @samp{ffs@var{m}2} @@ -3139,14 +3374,6 @@ respectively, a low or moderate degree of temporal locality. Targets that do not support write prefetches or locality hints can ignore the values of operands 1 and 2. -@cindex @code{cycle_display} instruction pattern -@item @samp{cycle_display} - -This pattern, if present, will be emitted by the instruction scheduler at -the beginning of each new clock cycle. This can be used for annotating the -assembler output with cycle counts. Operand 0 is a @code{const_int} that -holds the clock cycle. - @end table @node Pattern Ordering @@ -3317,7 +3544,7 @@ multiple condition registers, use a pseudo register. @findex next_cc0_user On some machines, the type of branch instruction generated may depend on the way the condition code was produced; for example, on the 68k and -Sparc, setting the condition code directly from an add or subtract +SPARC, setting the condition code directly from an add or subtract instruction does not clear the overflow bit the way that a test instruction does, so a different branch instruction must be used for some conditional branches. For machines that use @code{(cc0)}, the set @@ -3336,7 +3563,7 @@ different formats of the condition code register. Registers used to store the condition code value should have a mode that is in class @code{MODE_CC}. Normally, it will be @code{CCmode}. If additional modes are required (as for the add example mentioned above in -the Sparc), define the macro @code{EXTRA_CC_MODES} to list the +the SPARC), define the macro @code{EXTRA_CC_MODES} to list the additional modes required (@pxref{Condition Code}). Also define @code{SELECT_CC_MODE} to choose a mode given an operand of a compare. @@ -3348,7 +3575,7 @@ be specified at that time. If the cases that require different modes would be made by instruction combination, the macro @code{SELECT_CC_MODE} determines which machine mode should be used for the comparison result. The patterns should be -written using that mode. To support the case of the add on the Sparc +written using that mode. To support the case of the add on the SPARC discussed above, we have the pattern @smallexample @@ -3362,7 +3589,7 @@ discussed above, we have the pattern "@dots{}") @end smallexample -The @code{SELECT_CC_MODE} macro on the Sparc returns @code{CC_NOOVmode} +The @code{SELECT_CC_MODE} macro on the SPARC returns @code{CC_NOOVmode} for comparisons whose argument is a @code{plus}. @node Looping Patterns @@ -3370,7 +3597,7 @@ for comparisons whose argument is a @code{plus}. @cindex looping instruction patterns @cindex defining looping instruction patterns -Some machines have special jump instructions that can be utilised to +Some machines have special jump instructions that can be utilized to make loops more efficient. A common example is the 68000 @samp{dbra} instruction which performs a decrement of a register and a branch if the result was greater than zero. Other machines, in particular digital @@ -3501,6 +3728,14 @@ For these operators, if only one operand is a @code{neg}, @code{not}, @code{mult}, @code{plus}, or @code{minus} expression, it will be the first operand. +@item +In combinations of @code{neg}, @code{mult}, @code{plus}, and +@code{minus}, the @code{neg} operations (if any) will be moved inside +the operations as far as possible. For instance, +@code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but +@code{(plus (mult (neg A) B) C)} is canonicalized as +@code{(minus A (mult B C))}. + @cindex @code{compare}, canonicalization of @item For the @code{compare} operator, a constant is always the second operand @@ -3810,13 +4045,14 @@ in the compiler. @cindex instruction splitting @cindex splitting instructions -There are two cases where you should specify how to split a pattern into -multiple insns. On machines that have instructions requiring delay -slots (@pxref{Delay Slots}) or that have instructions whose output is -not available for multiple cycles (@pxref{Function Units}), the compiler -phases that optimize these cases need to be able to move insns into -one-instruction delay slots. However, some insns may generate more than one -machine instruction. These insns cannot be placed into a delay slot. +There are two cases where you should specify how to split a pattern +into multiple insns. On machines that have instructions requiring +delay slots (@pxref{Delay Slots}) or that have instructions whose +output is not available for multiple cycles (@pxref{Processor pipeline +description}), the compiler phases that optimize these cases need to +be able to move insns into one-instruction delay slots. However, some +insns may generate more than one machine instruction. These insns +cannot be placed into a delay slot. Often you can rewrite the single insn as a list of individual insns, each corresponding to one machine instruction. The disadvantage of @@ -3978,7 +4214,7 @@ instruction is always valid, as compiler expect identical behavior of new jump. When new sequence contains multiple jump instructions or new labels, more assistance is needed. Splitter is required to create only unconditional jumps, or simple conditional jump instructions. Additionally it must attach a -@code{REG_BR_PROB} note to each conditional jump. An global variable +@code{REG_BR_PROB} note to each conditional jump. A global variable @code{split_branch_probability} hold the probability of original branch in case it was an simple conditional jump, @minus{}1 otherwise. To simplify recomputing of edge frequencies, new sequence is required to have only @@ -4061,7 +4297,7 @@ For example: @end smallexample -Where @var{pathname} is a string that specifies the the location of the file, +Where @var{pathname} is a string that specifies the location of the file, specifies the include file to be in @file{gcc/config/target/filestuff}. The directory @file{gcc/config/target} is regarded as the default directory. @@ -4436,7 +4672,7 @@ to track the condition codes. * Insn Lengths:: Computing the length of insns. * Constant Attributes:: Defining attributes that are constant. * Delay Slots:: Defining delay slots required for a machine. -* Function Units:: Specifying information for insn scheduling. +* Processor pipeline description:: Specifying information for insn scheduling. @end menu @node Defining Attributes @@ -5066,14 +5302,101 @@ branch is true, we might represent this as follows: @end smallexample @c the above is *still* too long. --mew 4feb93 -@node Function Units -@subsection Specifying Function Units +@node Processor pipeline description +@subsection Specifying processor pipeline description +@cindex processor pipeline description +@cindex processor functional units +@cindex instruction latency time +@cindex interlock delays +@cindex data dependence delays +@cindex reservation delays +@cindex pipeline hazard recognizer +@cindex automaton based pipeline description +@cindex regular expressions +@cindex deterministic finite state automaton +@cindex automaton based scheduler +@cindex RISC +@cindex VLIW + +To achieve better performance, most modern processors +(super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW} +processors) have many @dfn{functional units} on which several +instructions can be executed simultaneously. An instruction starts +execution if its issue conditions are satisfied. If not, the +instruction is stalled until its conditions are satisfied. Such +@dfn{interlock (pipeline) delay} causes interruption of the fetching +of successor instructions (or demands nop instructions, e.g. for some +MIPS processors). + +There are two major kinds of interlock delays in modern processors. +The first one is a data dependence delay determining @dfn{instruction +latency time}. The instruction execution is not started until all +source data have been evaluated by prior instructions (there are more +complex cases when the instruction execution starts even when the data +are not available but will be ready in given time after the +instruction execution start). Taking the data dependence delays into +account is simple. The data dependence (true, output, and +anti-dependence) delay between two instructions is given by a +constant. In most cases this approach is adequate. The second kind +of interlock delays is a reservation delay. The reservation delay +means that two instructions under execution will be in need of shared +processors resources, i.e. buses, internal registers, and/or +functional units, which are reserved for some time. Taking this kind +of delay into account is complex especially for modern @acronym{RISC} +processors. + +The task of exploiting more processor parallelism is solved by an +instruction scheduler. For a better solution to this problem, the +instruction scheduler has to have an adequate description of the +processor parallelism (or @dfn{pipeline description}). Currently GCC +provides two alternative ways to describe processor parallelism, +both described below. The first method is outlined in the next section; +it was once the only method provided by GCC, and thus is used in a number +of exiting ports. The second, and preferred method, specifies functional +unit reservations for groups of instructions with the aid of @dfn{regular +expressions}. This is called the @dfn{automaton based description}. + +The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to +figure out the possibility of the instruction issue by the processor +on a given simulated processor cycle. The pipeline hazard recognizer is +automatically generated from the processor pipeline description. The +pipeline hazard recognizer generated from the automaton based +description is more sophisticated and based on a deterministic finite +state automaton (@acronym{DFA}) and therefore faster than one +generated from the old description. Furthermore, its speed is not dependent +on processor complexity. The instruction issue is possible if there is +a transition from one automaton state to another one. + +You can use any model to describe processor pipeline characteristics +or even a mix of them. You could use the old description for some +processor submodels and the @acronym{DFA}-based one for the rest +processor submodels. + +In general, the usage of the automaton based description is more +preferable. Its model is more rich. It permits to describe more +accurately pipeline characteristics of processors which results in +improving code quality (although sometimes only on several percent +fractions). It will be also used as an infrastructure to implement +sophisticated and practical insn scheduling which will try many +instruction sequences to choose the best one. + + +@menu +* Old pipeline description:: Specifying information for insn scheduling. +* Automaton pipeline description:: Describing insn pipeline characteristics. +* Comparison of the two descriptions:: Drawbacks of the old pipeline description +@end menu + +@node Old pipeline description +@subsubsection Specifying Function Units +@cindex old pipeline description @cindex function units, for scheduling -On most RISC machines, there are instructions whose results are not -available for a specific number of cycles. Common cases are instructions -that load data from memory. On many machines, a pipeline stall will result -if the data is referenced too soon after the load instruction. +On most @acronym{RISC} machines, there are instructions whose results +are not available for a specific number of cycles. Common cases are +instructions that load data from memory. On many machines, a pipeline +stall will result if the data is referenced too soon after the load +instruction. In addition, many newer microprocessors have multiple function units, usually one for integer and one for floating point, and often will incur pipeline @@ -5087,13 +5410,14 @@ due to function unit conflicts. For the purposes of the specifications in this section, a machine is divided into @dfn{function units}, each of which execute a specific -class of instructions in first-in-first-out order. Function units that -accept one instruction each cycle and allow a result to be used in the -succeeding instruction (usually via forwarding) need not be specified. -Classic RISC microprocessors will normally have a single function unit, -which we can call @samp{memory}. The newer ``superscalar'' processors -will often have function units for floating point operations, usually at -least a floating point adder and multiplier. +class of instructions in first-in-first-out order. Function units +that accept one instruction each cycle and allow a result to be used +in the succeeding instruction (usually via forwarding) need not be +specified. Classic @acronym{RISC} microprocessors will normally have +a single function unit, which we can call @samp{memory}. The newer +``superscalar'' processors will often have function units for floating +point operations, usually at least a floating point adder and +multiplier. @findex define_function_unit Each usage of a function units by a class of insns is specified with a @@ -5156,10 +5480,10 @@ Typical uses of this vector are where a floating point function unit can pipeline either single- or double-precision operations, but not both, or where a memory unit can pipeline loads, but not stores, etc. -As an example, consider a classic RISC machine where the result of a -load instruction is not available for two cycles (a single ``delay'' -instruction is required) and where only one load instruction can be executed -simultaneously. This would be specified as: +As an example, consider a classic @acronym{RISC} machine where the +result of a load instruction is not available for two cycles (a single +``delay'' instruction is required) and where only one load instruction +can be executed simultaneously. This would be specified as: @smallexample (define_function_unit "memory" 1 1 (eq_attr "type" "load") 2 0) @@ -5185,6 +5509,405 @@ used during their execution and there is no way of representing that conflict. We welcome any examples of how function unit conflicts work in such processors and suggestions for their representation. +@node Automaton pipeline description +@subsubsection Describing instruction pipeline characteristics +@cindex automaton based pipeline description + +This section describes constructions of the automaton based processor +pipeline description. The order of all mentioned below constructions +in the machine description file is not important. + +@findex define_automaton +@cindex pipeline hazard recognizer +The following optional construction describes names of automata +generated and used for the pipeline hazards recognition. Sometimes +the generated finite state automaton used by the pipeline hazard +recognizer is large. If we use more than one automaton and bind functional +units to the automata, the summary size of the automata usually is +less than the size of the single automaton. If there is no one such +construction, only one finite state automaton is generated. + +@smallexample +(define_automaton @var{automata-names}) +@end smallexample + +@var{automata-names} is a string giving names of the automata. The +names are separated by commas. All the automata should have unique names. +The automaton name is used in construction @code{define_cpu_unit} and +@code{define_query_cpu_unit}. + +@findex define_cpu_unit +@cindex processor functional units +Each processor functional unit used in description of instruction +reservations should be described by the following construction. + +@smallexample +(define_cpu_unit @var{unit-names} [@var{automaton-name}]) +@end smallexample + +@var{unit-names} is a string giving the names of the functional units +separated by commas. Don't use name @samp{nothing}, it is reserved +for other goals. + +@var{automaton-name} is a string giving the name of the automaton with +which the unit is bound. The automaton should be described in +construction @code{define_automaton}. You should give +@dfn{automaton-name}, if there is a defined automaton. + +@findex define_query_cpu_unit +@cindex querying function unit reservations +The following construction describes CPU functional units analogously +to @code{define_cpu_unit}. If we use automata without their +minimization, the reservation of such units can be queried for an +automaton state. The instruction scheduler never queries reservation +of functional units for given automaton state. So as a rule, you +don't need this construction. This construction could be used for +future code generation goals (e.g. to generate @acronym{VLIW} insn +templates). + +@smallexample +(define_query_cpu_unit @var{unit-names} [@var{automaton-name}]) +@end smallexample + +@var{unit-names} is a string giving names of the functional units +separated by commas. + +@var{automaton-name} is a string giving the name of the automaton with +which the unit is bound. + +@findex define_insn_reservation +@cindex instruction latency time +@cindex regular expressions +@cindex data bypass +The following construction is the major one to describe pipeline +characteristics of an instruction. + +@smallexample +(define_insn_reservation @var{insn-name} @var{default_latency} + @var{condition} @var{regexp}) +@end smallexample + +@var{default_latency} is a number giving latency time of the +instruction. There is an important difference between the old +description and the automaton based pipeline description. The latency +time is used for all dependencies when we use the old description. In +the automaton based pipeline description, the given latency time is only +used for true dependencies. The cost of anti-dependencies is always +zero and the cost of output dependencies is the difference between +latency times of the producing and consuming insns (if the difference +is negative, the cost is considered to be zero). You can always +change the default costs for any description by using the target hook +@code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}). + +@var{insn-names} is a string giving the internal name of the insn. The +internal names are used in constructions @code{define_bypass} and in +the automaton description file generated for debugging. The internal +name has nothing in common with the names in @code{define_insn}. It is a +good practice to use insn classes described in the processor manual. + +@var{condition} defines what RTL insns are described by this +construction. You should remember that you will be in trouble if +@var{condition} for two or more different +@code{define_insn_reservation} constructions is TRUE for an insn. In +this case what reservation will be used for the insn is not defined. +Such cases are not checked during generation of the pipeline hazards +recognizer because in general recognizing that two conditions may have +the same value is quite difficult (especially if the conditions +contain @code{symbol_ref}). It is also not checked during the +pipeline hazard recognizer work because it would slow down the +recognizer considerably. + +@var{regexp} is a string describing the reservation of the cpu's functional +units by the instruction. The reservations are described by a regular +expression according to the following syntax: + +@smallexample + regexp = regexp "," oneof + | oneof + + oneof = oneof "|" allof + | allof + + allof = allof "+" repeat + | repeat + + repeat = element "*" number + | element + + element = cpu_function_unit_name + | reservation_name + | result_name + | "nothing" + | "(" regexp ")" +@end smallexample + +@itemize @bullet +@item +@samp{,} is used for describing the start of the next cycle in +the reservation. + +@item +@samp{|} is used for describing a reservation described by the first +regular expression @strong{or} a reservation described by the second +regular expression @strong{or} etc. + +@item +@samp{+} is used for describing a reservation described by the first +regular expression @strong{and} a reservation described by the +second regular expression @strong{and} etc. + +@item +@samp{*} is used for convenience and simply means a sequence in which +the regular expression are repeated @var{number} times with cycle +advancing (see @samp{,}). + +@item +@samp{cpu_function_unit_name} denotes reservation of the named +functional unit. + +@item +@samp{reservation_name} --- see description of construction +@samp{define_reservation}. + +@item +@samp{nothing} denotes no unit reservations. +@end itemize + +@findex define_reservation +Sometimes unit reservations for different insns contain common parts. +In such case, you can simplify the pipeline description by describing +the common part by the following construction + +@smallexample +(define_reservation @var{reservation-name} @var{regexp}) +@end smallexample + +@var{reservation-name} is a string giving name of @var{regexp}. +Functional unit names and reservation names are in the same name +space. So the reservation names should be different from the +functional unit names and can not be reserved name @samp{nothing}. + +@findex define_bypass +@cindex instruction latency time +@cindex data bypass +The following construction is used to describe exceptions in the +latency time for given instruction pair. This is so called bypasses. + +@smallexample +(define_bypass @var{number} @var{out_insn_names} @var{in_insn_names} + [@var{guard}]) +@end smallexample + +@var{number} defines when the result generated by the instructions +given in string @var{out_insn_names} will be ready for the +instructions given in string @var{in_insn_names}. The instructions in +the string are separated by commas. + +@var{guard} is an optional string giving the name of a C function which +defines an additional guard for the bypass. The function will get the +two insns as parameters. If the function returns zero the bypass will +be ignored for this case. The additional guard is necessary to +recognize complicated bypasses, e.g. when the consumer is only an address +of insn @samp{store} (not a stored value). + +@findex exclusion_set +@findex presence_set +@findex absence_set +@cindex VLIW +@cindex RISC +Usually the following three constructions are used to describe +@acronym{VLIW} processors (more correctly to describe a placement of +small insns into @acronym{VLIW} insn slots). Although they can be +used for @acronym{RISC} processors too. + +@smallexample +(exclusion_set @var{unit-names} @var{unit-names}) +(presence_set @var{unit-names} @var{unit-names}) +(absence_set @var{unit-names} @var{unit-names}) +@end smallexample + +@var{unit-names} is a string giving names of functional units +separated by commas. + +The first construction (@samp{exclusion_set}) means that each +functional unit in the first string can not be reserved simultaneously +with a unit whose name is in the second string and vice versa. For +example, the construction is useful for describing processors +(e.g. some SPARC processors) with a fully pipelined floating point +functional unit which can execute simultaneously only single floating +point insns or only double floating point insns. + +The second construction (@samp{presence_set}) means that each +functional unit in the first string can not be reserved unless at +least one of units whose names are in the second string is reserved. +This is an asymmetric relation. For example, it is useful for +description that @acronym{VLIW} @samp{slot1} is reserved after +@samp{slot0} reservation. + +The third construction (@samp{absence_set}) means that each functional +unit in the first string can be reserved only if each unit whose name +is in the second string is not reserved. This is an asymmetric +relation (actually @samp{exclusion_set} is analogous to this one but +it is symmetric). For example, it is useful for description that +@acronym{VLIW} @samp{slot0} can not be reserved after @samp{slot1} or +@samp{slot2} reservation. + +All functional units mentioned in a set should belong to the same +automaton. + +@findex automata_option +@cindex deterministic finite state automaton +@cindex nondeterministic finite state automaton +@cindex finite state automaton minimization +You can control the generator of the pipeline hazard recognizer with +the following construction. + +@smallexample +(automata_option @var{options}) +@end smallexample + +@var{options} is a string giving options which affect the generated +code. Currently there are the following options: + +@itemize @bullet +@item +@dfn{no-minimization} makes no minimization of the automaton. This is +only worth to do when we are going to query CPU functional unit +reservations in an automaton state. + +@item +@dfn{time} means printing additional time statistics about +generation of automata. + +@item +@dfn{v} means a generation of the file describing the result automata. +The file has suffix @samp{.dfa} and can be used for the description +verification and debugging. + +@item +@dfn{w} means a generation of warning instead of error for +non-critical errors. + +@item +@dfn{ndfa} makes nondeterministic finite state automata. This affects +the treatment of operator @samp{|} in the regular expressions. The +usual treatment of the operator is to try the first alternative and, +if the reservation is not possible, the second alternative. The +nondeterministic treatment means trying all alternatives, some of them +may be rejected by reservations in the subsequent insns. You can not +query functional unit reservations in nondeterministic automaton +states. +@end itemize + +As an example, consider a superscalar @acronym{RISC} machine which can +issue three insns (two integer insns and one floating point insn) on +the cycle but can finish only two insns. To describe this, we define +the following functional units. + +@smallexample +(define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline") +(define_cpu_unit "port0, port1") +@end smallexample + +All simple integer insns can be executed in any integer pipeline and +their result is ready in two cycles. The simple integer insns are +issued into the first pipeline unless it is reserved, otherwise they +are issued into the second pipeline. Integer division and +multiplication insns can be executed only in the second integer +pipeline and their results are ready correspondingly in 8 and 4 +cycles. The integer division is not pipelined, i.e. the subsequent +integer division insn can not be issued until the current division +insn finished. Floating point insns are fully pipelined and their +results are ready in 3 cycles. Where the result of a floating point +insn is used by an integer insn, an additional delay of one cycle is +incurred. To describe all of this we could specify + +@smallexample +(define_cpu_unit "div") + +(define_insn_reservation "simple" 2 (eq_attr "type" "int") + "(i0_pipeline | i1_pipeline), (port0 | port1)") + +(define_insn_reservation "mult" 4 (eq_attr "type" "mult") + "i1_pipeline, nothing*2, (port0 | port1)") + +(define_insn_reservation "div" 8 (eq_attr "type" "div") + "i1_pipeline, div*7, div + (port0 | port1)") + +(define_insn_reservation "float" 3 (eq_attr "type" "float") + "f_pipeline, nothing, (port0 | port1)) + +(define_bypass 4 "float" "simple,mult,div") +@end smallexample + +To simplify the description we could describe the following reservation + +@smallexample +(define_reservation "finish" "port0|port1") +@end smallexample + +and use it in all @code{define_insn_reservation} as in the following +construction + +@smallexample +(define_insn_reservation "simple" 2 (eq_attr "type" "int") + "(i0_pipeline | i1_pipeline), finish") +@end smallexample + + +@node Comparison of the two descriptions +@subsubsection Drawbacks of the old pipeline description +@cindex old pipeline description +@cindex automaton based pipeline description +@cindex processor functional units +@cindex interlock delays +@cindex instruction latency time +@cindex pipeline hazard recognizer +@cindex data bypass + +The old instruction level parallelism description and the pipeline +hazards recognizer based on it have the following drawbacks in +comparison with the @acronym{DFA}-based ones: + +@itemize @bullet +@item +Each functional unit is believed to be reserved at the instruction +execution start. This is a very inaccurate model for modern +processors. + +@item +An inadequate description of instruction latency times. The latency +time is bound with a functional unit reserved by an instruction not +with the instruction itself. In other words, the description is +oriented to describe at most one unit reservation by each instruction. +It also does not permit to describe special bypasses between +instruction pairs. + +@item +The implementation of the pipeline hazard recognizer interface has +constraints on number of functional units. This is a number of bits +in integer on the host machine. + +@item +The interface to the pipeline hazard recognizer is more complex than +one to the automaton based pipeline recognizer. + +@item +An unnatural description when you write a unit and a condition which +selects instructions using the unit. Writing all unit reservations +for an instruction (an instruction class) is more natural. + +@item +The recognition of the interlock delays has a slow implementation. The GCC +scheduler supports structures which describe the unit reservations. +The more functional units a processor has, the slower its pipeline hazard +recognizer will be. Such an implementation would become even slower when we +allowed to +reserve functional units not only at the instruction execution start. +In an automaton based pipeline hazard recognizer, speed is not dependent +on processor complexity. +@end itemize + @node Conditional Execution @section Conditional Execution @cindex conditional execution diff --git a/contrib/gcc/doc/objc.texi b/contrib/gcc/doc/objc.texi index d3fd775..a0c40f7 100644 --- a/contrib/gcc/doc/objc.texi +++ b/contrib/gcc/doc/objc.texi @@ -25,7 +25,6 @@ comments about this document to Ovidiu Predescu @node Executing code before main, Type encoding, Objective-C, Objective-C @section @code{+load}: Executing code before main - The GNU Objective-C runtime provides a way that allows you to execute code before the execution of the program enters the @code{main} function. The code is executed on a per-class and a per-category basis, @@ -396,7 +395,7 @@ prefixing a C constant string with the character @samp{@@}: id myString = @@"this is a constant string object"; @end example -The constant string objects are usually instances of the +The constant string objects are by default instances of the @code{NXConstantString} class which is provided by the GNU Objective-C runtime. To get the definition of this class you must include the @file{objc/NXConstStr.h} header file. @@ -409,8 +408,9 @@ as @code{NXConstantString}'s structure: @example -@@interface NXConstantString : Object +@@interface MyConstantStringClass @{ + Class isa; char *c_string; unsigned int len; @} @@ -418,15 +418,31 @@ as @code{NXConstantString}'s structure: @end example -User class libraries may choose to inherit the customized constant -string class from a different class than @code{Object}. There is no -requirement in the methods the constant string class has to implement. - -When a file is compiled with the @option{-fconstant-string-class} option, -all the constant string objects will be instances of the class specified -as argument to this option. It is possible to have multiple compilation -units referring to different constant string classes, neither the -compiler nor the linker impose any restrictions in doing this. +@code{NXConstantString} inherits from @code{Object}; user class +libraries may choose to inherit the customized constant string class +from a different class than @code{Object}. There is no requirement in +the methods the constant string class has to implement, but the final +ivar layout of the class must be the compatible with the given +structure. + +When the compiler creates the statically allocated constant string +object, the @code{c_string} field will be filled by the compiler with +the string; the @code{length} field will be filled by the compiler with +the string length; the @code{isa} pointer will be filled with +@code{NULL} by the compiler, and it will later be fixed up automatically +at runtime by the GNU Objective-C runtime library to point to the class +which was set by the @option{-fconstant-string-class} option when the +object file is loaded (if you wonder how it works behind the scenes, the +name of the class to use, and the list of static objects to fixup, are +stored by the compiler in the object file in a place where the GNU +runtime library will find them at runtime). + +As a result, when a file is compiled with the +@option{-fconstant-string-class} option, all the constant string objects +will be instances of the class specified as argument to this option. It +is possible to have multiple compilation units referring to different +constant string classes, neither the compiler nor the linker impose any +restrictions in doing this. @c ========================================================================= @node compatibility_alias diff --git a/contrib/gcc/doc/passes.texi b/contrib/gcc/doc/passes.texi index 1a5f8b0..9a1941b 100644 --- a/contrib/gcc/doc/passes.texi +++ b/contrib/gcc/doc/passes.texi @@ -109,6 +109,7 @@ The files @file{c-common.c}, @file{c-common.def}, @file{c-format.c}, +@file{c-opts.c}, @file{c-pragma.c}, @file{c-semantics.c}, and @@ -116,7 +117,6 @@ and along with header files @file{c-common.h}, @file{c-dump.h}, -@file{c-lex.h}, and @file{c-pragma.h}, are also used for all of the above languages. @@ -206,7 +206,7 @@ the input file name. @cindex sibling call optimization @item -Sibiling call optimization. This pass performs tail recursion +Sibling call optimization. This pass performs tail recursion elimination, and tail and sibling call optimizations. The purpose of these optimizations is to reduce the overhead of function calls, whenever possible. @@ -458,13 +458,20 @@ The option @option{-dS} causes a debugging dump of the RTL code after this pass is run for the first time. The dump file's name is made by appending @samp{.sched} to the input file name. +@cindex register allocation +@item +Register allocation. These passes make sure that all occurrences of pseudo +registers are eliminated, either by allocating them to a hard register, +replacing them by an equivalent expression (e.g.@: a constant) or by placing +them on the stack. This is done in several subpasses: + +@itemize @bullet @cindex register class preference pass @item Register class preferencing. The RTL code is scanned to find out which register class is best for each pseudo register. The source file is @file{regclass.c}. -@cindex register allocation @cindex local register allocation @item Local register allocation (@file{local-alloc.c}). This pass allocates @@ -483,6 +490,17 @@ Global register allocation (@file{global.c}). This pass allocates hard registers for the remaining pseudo registers (those whose life spans are not contained in one basic block). +@cindex graph coloring register allocation +@opindex fnew-ra +@opindex dl +@item +Graph coloring register allocator. The files @file{ra.c}, @file{ra-build.c}, +@file{ra-colorize.c}, @file{ra-debug.c}, @file{ra-rewrite.c} together with +the header @file{ra.h} contain another register allocator, which is used +when the option @option{-fnew-ra} is given. In that case it is run instead +of the above mentioned local and global register allocation passes, and the +option @option{-dl} causes a debugging dump of its work. + @cindex reloading @item Reloading. This pass renumbers pseudo registers with the hardware @@ -504,6 +522,7 @@ Source files are @file{reload.c} and @file{reload1.c}, plus the header The option @option{-dg} causes a debugging dump of the RTL code after this pass. This dump file's name is made by appending @samp{.greg} to the input file name. +@end itemize @cindex instruction scheduling @cindex scheduling, instruction @@ -531,17 +550,6 @@ The option @option{-dB} causes a debugging dump of the RTL code after this pass. This dump file's name is made by appending @samp{.bbro} to the input file name. -@cindex cross-jumping -@cindex no-op move instructions -@item -Jump optimization is repeated, this time including cross-jumping -and deletion of no-op move instructions. - -@opindex dJ -The option @option{-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. - @cindex delayed branch scheduling @cindex scheduling, delayed branch @item @@ -653,6 +661,8 @@ Several passes use instruction attributes. A definition of the attributes defined for a particular machine is in file @file{insn-attr.h}, which is generated from the machine description by the program @file{genattr}. The file @file{insn-attrtab.c} contains -subroutines to obtain the attribute values for insns. It is generated -from the machine description by the program @file{genattrtab}. +subroutines to obtain the attribute values for insns and information +about processor pipeline characteristics for the instruction +scheduler. It is generated from the machine description by the +program @file{genattrtab}. @end itemize diff --git a/contrib/gcc/doc/rtl.texi b/contrib/gcc/doc/rtl.texi index 56a02d3..302957c 100644 --- a/contrib/gcc/doc/rtl.texi +++ b/contrib/gcc/doc/rtl.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002 +@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002, 2003 @c Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -243,6 +243,9 @@ core, @samp{V} is equivalent to @samp{E}, but when the object is read from an @samp{md} file, the vector value of this operand may be omitted. An omitted vector is effectively the same as a vector of no elements. +@item B +@samp{B} indicates a pointer to basic block structure. + @item 0 @samp{0} means a slot whose contents do not fit any normal category. @samp{0} slots are not printed at all in dumps, and are often used in @@ -371,7 +374,7 @@ to access them. RTL expressions contain several flags (one-bit bit-fields) that are used in certain types of expression. Most often they -are accessed with the following macros, which expand into lvalues: +are accessed with the following macros, which expand into lvalues. @table @code @findex CONSTANT_POOL_ADDRESS_P @@ -395,13 +398,15 @@ indicates that the insn represents a call to a const or pure function. Stored in the @code{unchanging} field and printed as @samp{/u}. @findex INSN_ANNULLED_BRANCH_P +@cindex @code{jump_insn} and @samp{/u} +@cindex @code{call_insn} and @samp{/u} @cindex @code{insn} and @samp{/u} -@cindex @code{unchanging}, in @code{insn} +@cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn} @item INSN_ANNULLED_BRANCH_P (@var{x}) -In an @code{insn} in the delay slot of a branch insn, indicates that an -annulling branch should be used. See the discussion under -@code{sequence} below. Stored in the @code{unchanging} field and printed -as @samp{/u}. +In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates +that the branch is an annulling one. See the discussion under +@code{sequence} below. Stored in the @code{unchanging} field and +printed as @samp{/u}. @findex INSN_DEAD_CODE_P @cindex @code{insn} and @samp{/s} @@ -413,16 +418,26 @@ Stored in the @code{in_struct} field and printed as @samp{/s}. @findex INSN_DELETED_P @cindex @code{insn} and @samp{/v} -@cindex @code{volatil}, in @code{insn} +@cindex @code{call_insn} and @samp{/v} +@cindex @code{jump_insn} and @samp{/v} +@cindex @code{code_label} and @samp{/v} +@cindex @code{barrier} and @samp{/v} +@cindex @code{note} and @samp{/v} +@cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{barrier}, and @code{note} @item INSN_DELETED_P (@var{x}) -In an @code{insn}, nonzero if the insn has been deleted. Stored in the +In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, +@code{barrier}, or @code{note}, +nonzero if the insn has been deleted. Stored in the @code{volatil} field and printed as @samp{/v}. @findex INSN_FROM_TARGET_P @cindex @code{insn} and @samp{/s} -@cindex @code{in_struct}, in @code{insn} +@cindex @code{jump_insn} and @samp{/s} +@cindex @code{call_insn} and @samp{/s} +@cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn} @item INSN_FROM_TARGET_P (@var{x}) -In an @code{insn} in a delay slot of a branch, indicates that the insn +In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay +slot of a branch, indicates that the insn is from the target of the branch. If the branch insn has @code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if the branch is taken. For annulled branches with @@ -441,39 +456,23 @@ label. Stored in the @code{in_struct} field and printed as @samp{/s}. @findex LABEL_PRESERVE_P @cindex @code{code_label} and @samp{/i} -@cindex @code{in_struct}, in @code{code_label} +@cindex @code{note} and @samp{/i} +@cindex @code{in_struct}, in @code{code_label} and @code{note} @item LABEL_PRESERVE_P (@var{x}) -In a @code{code_label}, indicates that the label is referenced by +In a @code{code_label} or @code{note}, indicates that the label is referenced by code or data not visible to the RTL of a given function. Labels referenced by a non-local goto will have this bit set. Stored in the @code{in_struct} field and printed as @samp{/s}. @findex LABEL_REF_NONLOCAL_P @cindex @code{label_ref} and @samp{/v} -@cindex @code{volatil}, in @code{label_ref} +@cindex @code{reg_label} and @samp{/v} +@cindex @code{volatil}, in @code{label_ref} and @code{reg_label} @item LABEL_REF_NONLOCAL_P (@var{x}) In @code{label_ref} and @code{reg_label} expressions, nonzero if this is a reference to a non-local label. Stored in the @code{volatil} field and printed as @samp{/v}. -@findex LINK_COST_FREE -@cindex @code{insn_list} and @samp{/c} -@cindex @code{call}, in @code{insn_list} -@item LINK_COST_FREE (@var{x}) -In the @code{LOG_LINKS} @code{insn_list} during scheduling, nonzero when -the cost of executing an instruction through the link is zero, i.e., the -link makes the cost free. Stored in the @code{call} field and printed -as @samp{/c}. - -@findex LINK_COST_ZERO -@cindex @code{insn_list} and @samp{/j} -@cindex @code{jump}, in @code{insn_list} -@item LINK_COST_ZERO (@var{x}) -In the @code{LOG_LINKS} @code{insn_list} during scheduling, nonzero when -the cost of executing an instruction through the link varies and is -unchanged, i.e., the link has zero additional cost. -Stored in the @code{jump} field and printed as @samp{/j}. - @findex MEM_IN_STRUCT_P @cindex @code{mem} and @samp{/s} @cindex @code{in_struct}, in @code{mem} @@ -508,10 +507,12 @@ Stored in the @code{frame_related} field and printed as @samp{/f}. @findex MEM_VOLATILE_P @cindex @code{mem} and @samp{/v} -@cindex @code{volatil}, in @code{mem} +@cindex @code{asm_input} and @samp{/v} +@cindex @code{asm_operands} and @samp{/v} +@cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input} @item MEM_VOLATILE_P (@var{x}) -In @code{mem} and @code{asm_operands} expressions, nonzero for volatile -memory references. +In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions, +nonzero for volatile memory references. Stored in the @code{volatil} field and printed as @samp{/v}. @findex REG_FUNCTION_VALUE_P @@ -553,9 +554,14 @@ in this kind of use. @findex RTX_FRAME_RELATED_P @cindex @code{insn} and @samp{/f} -@cindex @code{frame_related}, in @code{insn} +@cindex @code{call_insn} and @samp{/f} +@cindex @code{jump_insn} and @samp{/f} +@cindex @code{barrier} and @samp{/f} +@cindex @code{set} and @samp{/f} +@cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set} @item RTX_FRAME_RELATED_P (@var{x}) -Nonzero in an @code{insn} or @code{set} which is part of a function prologue +Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn}, +@code{barrier}, or @code{set} which is part of a function prologue and sets the stack pointer, sets the frame pointer, or saves a register. This flag should also be set on an instruction that sets up a temporary register to use in place of the frame pointer. @@ -582,26 +588,39 @@ prologues. @findex RTX_INTEGRATED_P @cindex @code{insn} and @samp{/i} -@cindex @code{integrated}, in @code{insn} +@cindex @code{call_insn} and @samp{/i} +@cindex @code{jump_insn} and @samp{/i} +@cindex @code{barrier} and @samp{/i} +@cindex @code{code_label} and @samp{/i} +@cindex @code{insn_list} and @samp{/i} +@cindex @code{const} and @samp{/i} +@cindex @code{note} and @samp{/i} +@cindex @code{integrated}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, @code{code_label}, @code{insn_list}, @code{const}, and @code{note} @item RTX_INTEGRATED_P (@var{x}) -Nonzero in an @code{insn}, @code{insn_list}, or @code{const} if it +Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, +@code{code_label}, @code{insn_list}, @code{const}, or @code{note} if it resulted from an in-line function call. Stored in the @code{integrated} field and printed as @samp{/i}. @findex RTX_UNCHANGING_P @cindex @code{reg} and @samp{/u} @cindex @code{mem} and @samp{/u} +@cindex @code{concat} and @samp{/u} @cindex @code{unchanging}, in @code{reg} and @code{mem} @item RTX_UNCHANGING_P (@var{x}) -Nonzero in a @code{reg} or @code{mem} if the memory is set at most once, +Nonzero in a @code{reg}, @code{mem}, or @code{concat} if the memory +is set at most once, anywhere. This does not mean that it is function invariant. Stored in the @code{unchanging} field and printed as @samp{/u}. @findex SCHED_GROUP_P -@cindex @code{insn} and @samp{/i} -@cindex @code{in_struct}, in @code{insn} +@cindex @code{insn} and @samp{/s} +@cindex @code{call_insn} and @samp{/s} +@cindex @code{jump_insn} and @samp{/s} +@cindex @code{in_struct}, in @code{insn}, @code{jump_insn} and @code{call_insn} @item SCHED_GROUP_P (@var{x}) -During instruction scheduling, in an @code{insn}, indicates that the +During instruction scheduling, in an @code{insn}, @code{call_insn} or +@code{jump_insn}, indicates that the previous insn must be scheduled together with this insn. This is used to ensure that certain groups of instructions will not be split up by the instruction scheduling pass, for example, @code{use} insns before @@ -631,13 +650,29 @@ string constant pool. Stored in the @code{frame_related} field and printed as @samp{/f}. @findex SUBREG_PROMOTED_UNSIGNED_P -@cindex @code{subreg} and @samp{/u} +@cindex @code{subreg} and @samp{/u} and @samp{/v} @cindex @code{unchanging}, in @code{subreg} +@cindex @code{volatil}, in @code{subreg} @item SUBREG_PROMOTED_UNSIGNED_P (@var{x}) -Nonzero in a @code{subreg} that has @code{SUBREG_PROMOTED_VAR_P} nonzero -if the object being referenced is kept zero-extended and zero if it -is kept sign-extended. Stored in the @code{unchanging} field and -printed as @samp{/u}. +Returns a value greater then zero for a @code{subreg} that has +@code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept +zero-extended, zero if it is kept sign-extended, and less then zero if it is +extended some other way via the @code{ptr_extend} instruction. +Stored in the @code{unchanging} +field and @code{volatil} field, printed as @samp{/u} and @samp{/v}. +This macro may only be used to get the value it may not be used to change +the value. Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value. + +@findex SUBREG_PROMOTED_UNSIGNED_SET +@cindex @code{subreg} and @samp{/u} +@cindex @code{unchanging}, in @code{subreg} +@cindex @code{volatil}, in @code{subreg} +@item SUBREG_PROMOTED_UNSIGNED_SET (@var{x}) +Set the @code{unchanging} and @code{volatil} fields in a @code{subreg} +to reflect zero, sign, or other extension. If @code{volatil} is +zero, then @code{unchanging} as nonzero means zero extension and as +zero means sign extension. If @code{volatil} is nonzero then some +other type of extension was done via the @code{ptr_extend} instruction. @findex SUBREG_PROMOTED_VAR_P @cindex @code{subreg} and @samp{/s} @@ -680,8 +715,7 @@ These are the fields to which the above macros refer: @findex call @cindex @samp{/c} in RTL dump @item call -In the @code{LOG_LINKS} of an @code{insn_list} during scheduling, 1 means that -the cost of executing an instruction through the link is zero. +This flag is currently unused. In an RTL dump, this flag is represented as @samp{/c}. @@ -729,7 +763,8 @@ label that would have been deleted is replaced with a @code{note} of type In an @code{insn} during dead-code elimination, 1 means that the insn is dead code. -In an @code{insn} during reorg for an insn in the delay slot of a branch, +In an @code{insn} or @code{jump_insn} during reorg for an insn in the +delay slot of a branch, 1 means that this insn is from the target of the branch. In an @code{insn} during instruction scheduling, 1 means that this insn @@ -763,9 +798,6 @@ In a @code{set}, 1 means it is for a return. In a @code{call_insn}, 1 means it is a sibling call. -In the @code{LOG_LINKS} of an @code{insn_list} during scheduling, 1 means the -cost of executing an instruction through the link varies and is unchanging. - In an RTL dump, this flag is represented as @samp{/j}. @findex unchanging @@ -777,7 +809,8 @@ that the value of the expression never changes. In @code{subreg} expressions, it is 1 if the @code{subreg} references an unsigned object whose mode has been promoted to a wider mode. -In an @code{insn}, 1 means that this is an annulling branch. +In an @code{insn} or @code{jump_insn} in the delay slot of a branch +instruction, 1 means an annulling branch should be used. In a @code{symbol_ref} expression, 1 means that this symbol addresses something in the per-function constant pool. @@ -805,7 +838,8 @@ the symbol has already been written. @cindex @samp{/v} in RTL dump @item volatil @cindex volatile memory references -In a @code{mem} or @code{asm_operands} expression, it is 1 if the memory +In a @code{mem}, @code{asm_operands}, or @code{asm_input} +expression, it is 1 if the memory reference is volatile. Volatile memory references may not be deleted, reordered or combined. @@ -1188,7 +1222,7 @@ If @var{m} is @code{VOIDmode}, the bits of the value are stored in If the constant is floating point (regardless of its precision), then the number of integers used to store the value depends on the size of -@code{REAL_VALUE_TYPE} (@pxref{Cross-compilation}). The integers +@code{REAL_VALUE_TYPE} (@pxref{Floating Point}). The integers represent a floating point number, but not precisely in the target machine's or host machine's floating point format. To convert them to the precise bit pattern used by the target machine, use the macro @@ -1511,7 +1545,7 @@ preferable approach if only a small subset of instructions modify the condition code. Other machines store condition codes in general registers; in such cases a pseudo register should be used. -Some machines, such as the Sparc and RS/6000, have two sets of +Some machines, such as the SPARC and RS/6000, have two sets of arithmetic instructions, one that sets and one that does not set the condition code. This is best handled by normally generating the instruction that does not set the condition code, and making a pattern @@ -1542,6 +1576,10 @@ a unit of memory is accessed. @var{alias} specifies an alias set for the reference. In general two items are in different alias sets if they cannot reference the same memory address. +The construct @code{(mem:BLK (scratch))} is considered to alias all +other memories. Thus it may be used as a memory barrier in epilogue +stack deallocation patterns. + @findex addressof @item (addressof:@var{m} @var{reg}) This RTX represents a request for the address of register @var{reg}. Its mode @@ -1816,14 +1854,14 @@ valid. Comparison operators test a relation on two operands and are considered to represent a machine-dependent nonzero value described by, but not necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc}) -if the relation holds, or zero if it does not. The mode of the -comparison operation is independent of the mode of the data being -compared. If the comparison operation is being tested (e.g., the first -operand of an @code{if_then_else}), the mode must be @code{VOIDmode}. -If the comparison operation is producing data to be stored in some -variable, the mode must be in class @code{MODE_INT}. All comparison -operations producing data must use the same mode, which is -machine-specific. +if the relation holds, or zero if it does not, for comparison operators +whose results have a `MODE_INT' mode, and +@code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or +zero if it does not, for comparison operators that return floating-point +values. The mode of the comparison operation is independent of the mode +of the data being compared. If the comparison operation is being tested +(e.g., the first operand of an @code{if_then_else}), the mode must be +@code{VOIDmode}. @cindex condition codes There are two ways that comparison operations may be used. The @@ -2256,7 +2294,8 @@ trouble to describe the values that are stored, but it is essential to inform the compiler that the registers will be altered, lest it attempt to keep data in them across the string instruction. -If @var{x} is @code{(mem:BLK (const_int 0))}, it means that all memory +If @var{x} is @code{(mem:BLK (const_int 0))} or +@code{(mem:BLK (scratch))}, it means that all memory locations must be presumed clobbered. If @var{x} is a @code{parallel}, it has the same meaning as a @code{parallel} in a @code{set} expression. @@ -2538,9 +2577,6 @@ Represents the side effect of setting @var{x} to @var{y} and represents @var{x} before @var{x} is modified. @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. Note that this is not currently implemented. The expression @var{y} must be one of three forms: @table @code @@ -2560,7 +2596,7 @@ Here is an example of its use: This says to modify pseudo register 42 by adding the contents of pseudo register 48 to it, after the use of what ever 42 points to. -@findex post_modify +@findex pre_modify @item (pre_modify:@var{m} @var{x} @var{expr}) Similar except side effects happen before the use. @end table @@ -2792,13 +2828,32 @@ Besides as a @code{code_label}, a label can also be represented as a @findex LABEL_NUSES The field @code{LABEL_NUSES} is only defined once the jump optimization -phase is completed and contains the number of times this label is +phase is completed. It contains the number of times this label is referenced in the current function. -@findex LABEL_ALTERNATE_NAME -The field @code{LABEL_ALTERNATE_NAME} is used to associate a name with -a @code{code_label}. If this field is defined, the alternate name will -be emitted instead of an internally generated label name. +@findex LABEL_KIND +@findex SET_LABEL_KIND +@findex LABEL_ALT_ENTRY_P +@cindex alternate entry points +The field @code{LABEL_KIND} differentiates four different types of +labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY}, +@code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}. The only labels +that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry +points} to the current function. These may be static (visible only in +the containing translation unit), global (exposed to all translation +units), or weak (global, but can be overridden by another symbol with the +same name). + +Much of the compiler treats all four kinds of label identically. Some +of it needs to know whether or not a label is an alternate entry point; +for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided. It is +equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}. +The only place that cares about the distinction between static, global, +and weak alternate entry points, besides the front-end code that creates +them, is the function @code{output_alternate_entry_point}, in +@file{final.c}. + +To set the kind of a label, use the @code{SET_LABEL_KIND} macro. @findex barrier @item barrier @@ -3199,12 +3254,6 @@ are stored in the @code{REG_NOTES} field of an insn as an @code{expr_list}. @table @code -@findex REG_EXEC_COUNT -@item REG_EXEC_COUNT -This is used to indicate the number of times a basic block was executed -according to the profile data. The note is attached to the first insn in -the basic block. - @findex REG_BR_PROB @item REG_BR_PROB This is used to specify the ratio of branches to non-branches of a diff --git a/contrib/gcc/doc/service.texi b/contrib/gcc/doc/service.texi index 8637744..4cc2b70 100644 --- a/contrib/gcc/doc/service.texi +++ b/contrib/gcc/doc/service.texi @@ -1,5 +1,5 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001 Free Software Foundation, Inc. +@c 1999, 2000, 2001, 2002 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -24,7 +24,5 @@ The service directory is found at @uref{http://www.gnu.org/prep/service.html}. @end itemize -@c For further information, see -@c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}. -@c FIXME: this URL may be too volatile, this FAQ entry needs to move to -@c the regular web pages before we can uncomment the reference. +For further information, see +@uref{http://gcc.gnu.org/faq.html#support}. diff --git a/contrib/gcc/doc/sourcebuild.texi b/contrib/gcc/doc/sourcebuild.texi index 8977869..c60dcfa 100644 --- a/contrib/gcc/doc/sourcebuild.texi +++ b/contrib/gcc/doc/sourcebuild.texi @@ -124,7 +124,7 @@ the files in these directories. @item config Configuration files for supported architectures and operating systems. @xref{Back End, , Anatomy of a Target Back End}, for -details of the files in thie directory. +details of the files in this directory. @item doc Texinfo documentation for GCC, together with automatically generated @@ -155,7 +155,7 @@ various languages, @file{@var{language}.po}. This directory also contains @file{gcc.pot}, the template for these message catalogues, @file{exgettext}, a wrapper around @command{gettext} to extract the messages from the GCC sources and create @file{gcc.pot}, which is run -by @command{make gcc.pot}, and @file{EXCLUDES}, a list of files from +by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from which messages should not be extracted. @item testsuite @@ -246,8 +246,8 @@ libraries are also installed by GCC; these are not documented here. Several of the headers GCC installs are in the @file{ginclude} directory. These headers, @file{iso646.h}, -@file{stdarg.h}, @file{stdbool.h}, @file{stddef.h} and -@file{varargs.h}, are installed in @file{@var{libsubdir}/include}, +@file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h}, +are installed in @file{@var{libsubdir}/include}, unless the target Makefile fragment (@pxref{Target Fragment}) overrides this by setting @code{USER_H}. @@ -255,12 +255,13 @@ In addition to these headers and those generated by fixing system headers to work with GCC, some other headers may also be installed in @file{@var{libsubdir}/include}. @file{config.gcc} may set @code{extra_headers}; this specifies additional headers under -@file{config} to be installed on some systems. GCC normally installs -a @code{<float.h>} file; these are kept as -@file{config/float-@var{format}.h}, where @var{format} is specified by -a @code{float_format} setting in @file{config.gcc}, and a setting -@samp{float_format=none} disables installation of this header. GCC -also installs its own version of @code{<limits.h>}; this is generated +@file{config} to be installed on some systems. + +GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}. +This is done to cope with command-line options that change the +representation of floating point numbers. + +GCC also installs its own version of @code{<limits.h>}; this is generated from @file{glimits.h}, together with @file{limitx.h} and @file{limity.h} if the system also has its own version of @code{<limits.h>}. (GCC provides its own header because it is @@ -277,7 +278,7 @@ needs fixing, @file{syslimits.h} is the fixed copy. The main GCC documentation is in the form of manuals in Texinfo format. These are installed in Info format, and DVI versions may be -generated by @command{make dvi}. In addition, some man pages are +generated by @samp{make dvi}. In addition, some man pages are generated from the Texinfo manuals, there are some other text files with miscellaneous documentation, and runtime libraries have their own documentation outside the @file{gcc} directory. FIXME: document the @@ -311,9 +312,9 @@ The GNU General Public License. A copy of @file{texinfo.tex} known to work with the GCC manuals. @end table -DVI formatted manuals are generated by @command{make dvi}, which uses +DVI formatted manuals are generated by @samp{make dvi}, which uses @command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info -manuals are generated by @command{make info} (which is run as part of +manuals are generated by @samp{make info} (which is run as part of a bootstrap); this generates the manuals in the source directory, using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)}, and they are included in release distributions. @@ -329,7 +330,7 @@ not themselves the root files of manuals, may have names that appear more than once in the source tree.) The manual file @file{@var{name}.texi} should only include other files in its own directory or in @file{doc/include}. HTML manuals will be generated by -@command{makeinfo --html} and PostScript manuals by @command{texi2dvi} +@samp{makeinfo --html} and PostScript manuals by @command{texi2dvi} and @command{dvips}. All Texinfo files that are parts of manuals must be checked into CVS, even if they are generated files, for the generation of online manuals to work. @@ -492,6 +493,9 @@ inclusion in GCC, should be made available on the GCC FTP site @item The release and snapshot script @file{maintainer-scripts/gcc_release} should be updated to generate appropriate tarballs for this front end. +The associated @file{maintainer-scripts/snapshot-README} and +@file{maintainer-scripts/snapshot-index.html} files should be updated +to list the tarballs and diffs for this front end. @item If this front end includes its own version files that include the current date, @file{maintainer-scripts/update_version} should be @@ -537,7 +541,7 @@ deprecated). FIXME: exactly what goes in each of these targets? @item info Build info documentation for the front end, in the source directory. -This target is only called by @command{make bootstrap} if a suitable +This target is only called by @samp{make bootstrap} if a suitable version of @command{makeinfo} is available, so does not need to check for this, and should fail if an error occurs. @item dvi @@ -607,9 +611,10 @@ codes. @node Front End Config @subsubsection The Front End @file{config-lang.in} File -Each language subdirectory contains a @file{config-lang.in} file. -This file is a shell script that may define some variables describing -the language: +Each language subdirectory contains a @file{config-lang.in} file. In +addition the main directory contains @file{c-config-lang.in}, which +contains limited information for the C language. This file is a shell +script that may define some variables describing the language: @table @code @item language @@ -652,6 +657,12 @@ by @file{configure} substituting values in them. This mechanism can be used to create a file @file{@var{language}/Makefile} from @file{@var{language}/Makefile.in}, but this is deprecated, building everything from the single @file{gcc/Makefile} is preferred. +@item gtfiles +If defined, a space-separated list of files that should be scanned by +gengtype.c to generate the garbage collection tables and routines for +this language. This excludes the files that are common to all front +ends. @xref{Type Information}. + @end table @node Back End @@ -671,6 +682,10 @@ possibly a target Makefile fragment @file{t-@var{machine}} some other files. The names of these files may be changed from the defaults given by explicit specifications in @file{config.gcc}. @item +If necessary, a file @file{@var{machine}-modes.def} in the +@file{@var{machine}} directory, containing additional machine modes to +represent condition codes. @xref{Condition Code}, for further details. +@item Entries in @file{config.gcc} (@pxref{System Config, , The @file{config.gcc} File}) for the systems with this target architecture. @@ -736,9 +751,12 @@ suites. Currently only the C language test suites are documented here; FIXME: document the others. @menu -* Test Idioms:: Idioms used in test suite code. -* C Tests:: The C language test suites. -* libgcj Tests:: The Java library test suites. +* Test Idioms:: Idioms used in test suite code. +* C Tests:: The C language test suites. +* libgcj Tests:: The Java library test suites. +* gcov Testing:: Support for testing gcov. +* profopt Testing:: Support for testing profile-directed optimizations. +* compat Testing:: Support for testing binary compatibility. @end menu @node Test Idioms @@ -810,6 +828,10 @@ the function should remain, that function may be defined as @code{static} to call @code{abort ()} (although redeclaring a function as static may not work on all targets). +All testcases must be portable. Target-specific testcases must have +appropriate code to avoid causing failures on unsupported systems; +unfortunately, the mechanisms for this differ by directory. + FIXME: discuss non-C test suites here. @node C Tests @@ -819,6 +841,42 @@ GCC contains the following C language test suites, in the @file{gcc/testsuite} directory: @table @file +@item gcc.dg +This contains tests of particular features of the C compiler, using the +more modern @samp{dg} harness. Correctness tests for various compiler +features should go here if possible. + +Magic comments determine whether the file +is preprocessed, compiled, linked or run. In these tests, error and warning +message texts are compared against expected texts or regular expressions +given in comments. These tests are run with the options @samp{-ansi -pedantic} +unless other options are given in the test. Except as noted below they +are not run with multiple optimization options. +@item gcc.dg/cpp +This subdirectory contains tests of the preprocessor. +@item gcc.dg/debug +This subdirectory contains tests for debug formats. Tests in this +subdirectory are run for each debug format that the compiler supports. +@item gcc.dg/format +This subdirectory contains tests of the @option{-Wformat} format +checking. Tests in this directory are run with and without +@option{-DWIDE}. +@item gcc.dg/noncompile +This subdirectory contains tests of code that should not compile and +does not need any special compilation options. They are run with +multiple optimization options, since sometimes invalid code crashes +the compiler with optimization. +@item gcc.dg/special +FIXME: describe this. + +@item gcc.c-torture +This contains particular code fragments which have historically broken easily. +These tests are run with multiple optimization options, so tests for features +which only break at some optimization levels belong here. This also contains +tests to check that certain optimizations occur. It might be worthwhile to +separate the correctness tests cleanly from the code quality tests, but +it hasn't been done yet. + @item gcc.c-torture/compat FIXME: describe this. @@ -836,37 +894,35 @@ such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used. @item gcc.c-torture/execute This test suite contains test cases that should compile, link and run; otherwise the same comments as for @file{gcc.c-torture/compile} apply. +@item gcc.c-torture/execute/ieee +This contains tests which are specific to IEEE floating point. @item gcc.c-torture/unsorted FIXME: describe this. This directory should probably not be used for new tests. -@item gcc.dg -This test suite contains tests using the more modern @samp{dg} harness. -Magic comments determine whether the file is preprocessed, compiled, -linked or run. In these tests, error and warning message texts are -compared against expected texts or regular expressions given in -comments. These tests are run with the options @samp{-ansi -pedantic} -unless other options are given in the test. Except as noted below they -are not run with multiple optimization options. -@item gcc.dg/cpp -This subdirectory contains tests of the preprocessor. -@item gcc.dg/debug -This subdirectory contains tests for debug formats. Tests in this -subdirectory are run for each debug format that the compiler supports. -@item gcc.dg/format -This subdirectory contains tests of the @option{-Wformat} format -checking. Tests in this directory are run with and without -@option{-DWIDE}. -@item gcc.dg/noncompile -This subdirectory contains tests of code that should not compile and -does not need any special compilation options. They are run with -multiple optimization options, since sometimes invalid code crashes -the compiler with optimization. -@item gcc.dg/special -FIXME: describe this. @item gcc.c-torture/misc-tests -FIXME: describe this, when it should be used for new tests and when it -shouldn't. +This directory contains C tests that require special handling. Some +of these tests have individual expect files, and others share +special-purpose expect files: + +@table @file +@item @code{bprob*.c} +Test @option{-fbranch-probabilities} using @file{bprob.exp}, which +in turn uses the generic, language-independent framework +(@pxref{profopt Testing, , Support for testing profile-directed +optimizations}). + +@item @code{dg-*.c} +Test the testsuite itself using @file{dg-test.exp}. + +@item @code{gcov*.c} +Test @command{gcov} output using @file{gcov.exp}, which in turn uses the +language-independent support (@pxref{gcov Testing, , Support for testing gcov}). + +@item @code{i386-pf-*.c} +Test i386-specific support for data prefetch using @file{i386-prefetch.exp}. +@end table + @end table FIXME: merge in @file{testsuite/README.gcc} and discuss the format of @@ -882,12 +938,208 @@ tests can be checked into this testsuite. Regression testing of the core packages in libgcj is also covered by the Mauve test suite. The @uref{http://sources.redhat.com/mauve/,,Mauve Project} develops tests for the Java Class Libraries. These tests are run as part -of libgcj testing by specifying the location of the Mauve tree when invoking -@samp{make}, as in @samp{make MAUVEDIR=~/mauve check}. +of libgcj testing by placing the Mauve tree within the libjava testsuite +sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying +the location of that tree when invoking @samp{make}, as in +@samp{make MAUVEDIR=~/mauve check}. + +To detect regressions, a mechanism in @file{mauve.exp} compares the +failures for a test run against the list of expected failures in +@file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy. +Update this file when adding new failing tests to Mauve, or when fixing +bugs in libgcj that had caused Mauve test failures. The @uref{http://oss.software.ibm.com/developerworks/opensource/jacks/,, Jacks} project provides a test suite for Java compilers that can be used -to test changes that affect the GCJ front end. There is no automated -mechanism to run the Jacks suite as part of GCJ testing. +to test changes that affect the GCJ front end. This test suite is run as +part of Java testing by placing the Jacks tree within the the libjava +testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}. We encourage developers to contribute test cases to Mauve and Jacks. + +@node gcov Testing +@subsection Support for testing @command{gcov} + +Language-independent support for testing @command{gcov}, and for checking +that branch profiling produces expected values, is provided by the +expect file @file{gcov.exp}. @command{gcov} tests also rely on procedures +in @file{gcc.dg.exp} to compile and run the test program. A typical +@command{gcov} test contains the following DejaGNU commands within comments: + +@smallexample +@{ dg-options "-fprofile-arcs -ftest-coverage" @} +@{ dg-do run @{ target native @} @} +@{ dg-final @{ run-gcov sourcefile @} @} +@end smallexample + +Checks of @command{gcov} output can include line counts, branch percentages, +and call return percentages. All of these checks are requested via +commands that appear in comments in the test's source file. +Commands to check line counts are processed by default. +Commands to check branch percentages and call return percentages are +processed if there is a file with the same basename as the source +file and a suffix @file{.x} that contains a line +@code{set gcov_verify_branches 1} or @code{set gcov_verify_calls 1}, +respectively. + +A line count command appears within a comment on the source line +that is expected to get the specified count and has the form +@code{count(@var{cnt})}. A test should only check line counts for +lines that will get the same count for any architecture. + +Commands to check branch percentages (@code{branch}) and call +return percentages (@code{returns}) are very similar to each other. +A beginning command appears on or before the first of a range of +lines that will report the percentage, and the ending command +follows that range of lines. The beginning command can include a +list of percentages, all of which are expected to be found within +the range. A range is terminated by the next command of the same +kind. A command @code{branch(end)} or @code{returns(end)} marks +the end of a range without starting a new one. For example: + +@smallexample +if (i > 10 && j > i && j < 20) /* branch(27 50 75) */ + /* branch(end) */ + foo (i, j); +@end smallexample + +For a call return percentage, the value specified is the +percentage of calls reported to return. For a branch percentage, +the value is either the expected percentage or 100 minus that +value, since the direction of a branch can differ depending on the +target or the optimization level. + +Not all branches and calls need to be checked. A test should not +check for branches that might be optimized away or replaced with +predicated instructions. Don't check for calls inserted by the +compiler or ones that might be inlined or optimized away. + +A single test can check for combinations of line counts, branch +percentages, and call return percentages. The command to check a +line count must appear on the line that will report that count, but +commands to check branch percentages and call return percentages can +bracket the lines that report them. + +@node profopt Testing +@subsection Support for testing profile-directed optimizations + +The file @file{profopt.exp} provides language-independent support for +checking correct execution of a test built with profile-directed +optimization. This testing requires that a test program be built and +executed twice. The first time it is compiled to generate profile +data, and the second time it is compiled to use the data that was +generated during the first execution. The second execution is to +verify that the test produces the expected results. + +To check that the optimization actually generated better code, a +test can be built and run a third time with normal optimizations to +verify that the performance is better with the profile-directed +optimizations. @file{profopt.exp} has the beginnings of this kind +of support. + +@file{profopt.exp} provides generic support for profile-directed +optimizations. Each set of tests that uses it provides information +about a specific optimization: + +@table @code +@item tool +tool being tested, e.g., gcc + +@item profile_option +options used to generate profile data + +@item feedback_option +options used to optimize using that profile data + +@item prof_ext +suffix of profile data files + +@item PROFOPT_OPTIONS +list of options with which to run each test, similar to the lists for +torture tests +@end table + +@node compat Testing +@subsection Support for testing binary compatibility + +The file @file{compat.exp} provides language-independent support for +binary compatibility testing. It supports testing interoperability +of two compilers that follow the same ABI, or of multiple sets of +compiler options that should not affect binary compatibility. +It is intended to be used for test suites that complement ABI test +suites. + +A test supported by this framework has three parts, each in a +separate source file: a main program and two pieces that interact +with each other to split up the functionality being tested. + +@table @file +@item @var{testname}_main.@var{suffix} +Contains the main program, which calls a function in file +@file{@var{testname}_x.@var{suffix}}. + +@item @var{testname}_x.@var{suffix} +Contains at least one call to a function in +@file{@var{testname}_y.@var{suffix}}. + +@item @var{testname}_y.@var{suffix} +Shares data with, or gets arguments from, +@file{@var{testname}_x.@var{suffix}}. +@end table + +Within each test, the main program and one functional piece are +compiled by the GCC under test. The other piece can be compiled by +an alternate compiler. If no alternate compiler is specified, +then all three source files are all compiled by the GCC under test. +It's also possible to specify a pair of lists of compiler options, +one list for each compiler, so that each test will be compiled with +each pair of options. + +@file{compat.exp} defines default pairs of compiler options. +These can be overridden by defining the environment variable +@env{COMPAT_OPTIONS} as: + +@smallexample +COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}] + ...[list @{@var{tstn}@} @{@var{altn}@}]]" +@end smallexample + +where @var{tsti} and @var{alti} are lists of options, with @var{tsti} +used by the compiler under test and @var{alti} used by the alternate +compiler. For example, with +@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]}, +the test is first built with @code{-g -O0} by the compiler under +test and with @code{-O3} by the alternate compiler. The test is +built a second time using @code{-fpic} by the compiler under test +and @code{-fPIC -O2} by the alternate compiler. + +An alternate compiler is specified by defining an environment +variable; for C++ define @env{ALT_CXX_UNDER_TEST} to be the full +pathname of an installed compiler. That will be written to the +@file{site.exp} file used by DejaGNU. The default is to build each +test with the compiler under test using the first of each pair of +compiler options from @env{COMPAT_OPTIONS}. When +@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using +the compiler under test but with combinations of the options from +@env{COMPAT_OPTIONS}. + +To run only the C++ compatibility suite using the compiler under test +and another version of GCC using specific compiler options, do the +following from @file{@var{objdir}/gcc}: + +@smallexample +rm site.exp +make -k \ + ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \ + COMPAT_OPTIONS="lists as shown above" \ + check-c++ \ + RUNTESTFLAGS="compat.exp" +@end smallexample + +A test that fails when the source files are compiled with different +compilers, but passes when the files are compiled with the same +compiler, demonstrates incompatibility of the generated code or +runtime support. A test that fails for the alternate compiler but +passes for the compiler under test probably tests for a bug that was +fixed in the compiler under test but is present in the alternate +compiler. diff --git a/contrib/gcc/doc/standards.texi b/contrib/gcc/doc/standards.texi index b3e8b18..c939498 100644 --- a/contrib/gcc/doc/standards.texi +++ b/contrib/gcc/doc/standards.texi @@ -14,7 +14,6 @@ @cindex X3.159-1989 @cindex ISO C standard @cindex ISO C -@cindex ISO C89 @cindex ISO C90 @cindex ISO/IEC 9899 @cindex ISO 9899 @@ -80,7 +79,7 @@ as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or A new edition of the ISO C standard was published in 1999 as ISO/IEC 9899:1999, and is commonly known as @dfn{C99}. GCC has incomplete support for this standard version; see -@uref{http://gcc.gnu.org/gcc-3.1/c99status.html} for details. To select this +@uref{http://gcc.gnu.org/gcc-3.3/c99status.html} for details. To select this standard, use @option{-std=c99} or @option{-std=iso9899:1999}. (While in development, drafts of this standard version were referred to as @dfn{C9X}.) @@ -89,13 +88,6 @@ Errors in the 1999 ISO C standard were corrected in a Technical Corrigendum published in 2001. GCC does not support the uncorrected version. -@opindex traditional -GCC also has some limited support for traditional (pre-ISO) C with the -@option{-traditional} option. This support may be of use for compiling -some very old programs that have not been updated to ISO C, but should -not be used for new programs. It will not work with some modern C -libraries such as the GNU C library. - By default, GCC provides some extensions to the C language that on rare occasions conflict with the C standard. @xref{C Extensions,,Extensions to the C Language Family}. Use of the @@ -182,6 +174,13 @@ is an older example has additional useful information @end itemize +@cindex treelang +There is no standard for treelang, which is a sample language front end +for GCC. Its only purpose is as a sample for people wishing to write a +new language for GCC. The language is documented in +@file{gcc/treelang/treelang.texi} which can be turned into info or +HTML format. + @xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, GNAT Reference Manual}, for information on standard conformance and compatibility of the Ada compiler. @@ -190,4 +189,4 @@ conformance and compatibility of the Ada compiler. Fortran}, for details of the Fortran language supported by GCC@. @xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj}, -for details of compatibility between @code{gcj} and the Java Platform. +for details of compatibility between @command{gcj} and the Java Platform. diff --git a/contrib/gcc/doc/tm.texi b/contrib/gcc/doc/tm.texi index 4b29d52..21c7c2a 100644 --- a/contrib/gcc/doc/tm.texi +++ b/contrib/gcc/doc/tm.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002 +@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002,2003 @c Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -46,9 +46,10 @@ through the macros defined in the @file{.h} file. * PIC:: Macros for position independent code. * Assembler Format:: Defining how to write insns and pseudo-ops to output. * Debugging Info:: Defining the format of debugging output. -* Cross-compilation:: Handling floating point for cross-compilers. +* Floating Point:: Handling floating point for cross-compilers. * Mode Switching:: Insertion of mode-switching instructions. * Target Attributes:: Defining target-specific uses of @code{__attribute__}. +* MIPS Coprocessors:: MIPS coprocessor support and how to customize it. * Misc:: Everything else. @end menu @@ -162,6 +163,23 @@ multilibs. Example nonsensical definition, where @code{-malt-abi}, @{ "-compat", "-EB -malign=4 -mspoo" @} @end smallexample +@findex DRIVER_SELF_SPECS +@item DRIVER_SELF_SPECS +A list of specs for the driver itself. It should be a suitable +initializer for an array of strings, with no surrounding braces. + +The driver applies these specs to its own command line before choosing +the multilib directory or running any subcommands. It applies them in +the order given, so each spec can depend on the options added by +earlier ones. It is also possible to remove options using +@samp{%<@var{option}} in the usual way. + +This macro can be useful when a port has several interdependent target +options. It provides a way of standardizing the command line so +that the other specs are easier to write. + +Do not define this macro if it does not need to do anything. + @findex CPP_SPEC @item CPP_SPEC A C string constant that tells the GCC driver program options to @@ -176,46 +194,6 @@ This macro is just like @code{CPP_SPEC}, but is used for C++, rather than C@. If you do not define this macro, then the value of @code{CPP_SPEC} (if any) will be used instead. -@findex NO_BUILTIN_SIZE_TYPE -@item NO_BUILTIN_SIZE_TYPE -If this macro is defined, the preprocessor will not define the built-in macro -@code{__SIZE_TYPE__}. The macro @code{__SIZE_TYPE__} must then be defined -by @code{CPP_SPEC} instead. - -This should be defined if @code{SIZE_TYPE} depends on target dependent flags -which are not accessible to the preprocessor. Otherwise, it should not -be defined. - -@findex NO_BUILTIN_PTRDIFF_TYPE -@item NO_BUILTIN_PTRDIFF_TYPE -If this macro is defined, the preprocessor will not define the built-in macro -@code{__PTRDIFF_TYPE__}. The macro @code{__PTRDIFF_TYPE__} must then be -defined by @code{CPP_SPEC} instead. - -This should be defined if @code{PTRDIFF_TYPE} depends on target dependent flags -which are not accessible to the preprocessor. Otherwise, it should not -be defined. - -@findex NO_BUILTIN_WCHAR_TYPE -@item NO_BUILTIN_WCHAR_TYPE -If this macro is defined, the preprocessor will not define the built-in macro -@code{__WCHAR_TYPE__}. The macro @code{__WCHAR_TYPE__} must then be -defined by @code{CPP_SPEC} instead. - -This should be defined if @code{WCHAR_TYPE} depends on target dependent flags -which are not accessible to the preprocessor. Otherwise, it should not -be defined. - -@findex NO_BUILTIN_WINT_TYPE -@item NO_BUILTIN_WINT_TYPE -If this macro is defined, the preprocessor will not define the built-in macro -@code{__WINT_TYPE__}. The macro @code{__WINT_TYPE__} must then be -defined by @code{CPP_SPEC} instead. - -This should be defined if @code{WINT_TYPE} depends on target dependent flags -which are not accessible to the preprocessor. Otherwise, it should not -be defined. - @findex CC1_SPEC @item CC1_SPEC A C string constant that tells the GCC driver program options to @@ -412,7 +390,7 @@ the target makefile fragment or if none of the options listed in @findex RELATIVE_PREFIX_NOT_LINKDIR @item RELATIVE_PREFIX_NOT_LINKDIR -Define this macro to tell @code{gcc} that it should only translate +Define this macro to tell @command{gcc} that it should only translate a @option{-B} prefix into a @option{-L} linker option if the prefix indicates an absolute file name. @@ -622,6 +600,53 @@ The macro @code{STANDARD_STARTFILE_PREFIX}. Here are run-time target specifications. @table @code +@findex TARGET_CPU_CPP_BUILTINS +@item TARGET_CPU_CPP_BUILTINS() +This function-like macro expands to a block of code that defines +built-in preprocessor macros and assertions for the target cpu, using +the functions @code{builtin_define}, @code{builtin_define_std} and +@code{builtin_assert} defined in @file{c-common.c}. When the front end +calls this macro it provides a trailing semicolon, and since it has +finished command line option processing your code can use those +results freely. + +@code{builtin_assert} takes a string in the form you pass to the +command-line option @option{-A}, such as @code{cpu=mips}, and creates +the assertion. @code{builtin_define} takes a string in the form +accepted by option @option{-D} and unconditionally defines the macro. + +@code{builtin_define_std} takes a string representing the name of an +object-like macro. If it doesn't lie in the user's namespace, +@code{builtin_define_std} defines it unconditionally. Otherwise, it +defines a version with two leading underscores, and another version +with two leading and trailing underscores, and defines the original +only if an ISO standard was not requested on the command line. For +example, passing @code{unix} defines @code{__unix}, @code{__unix__} +and possibly @code{unix}; passing @code{_mips} defines @code{__mips}, +@code{__mips__} and possibly @code{_mips}, and passing @code{_ABI64} +defines only @code{_ABI64}. + +You can also test for the C dialect being compiled. The variable +@code{c_language} is set to one of @code{clk_c}, @code{clk_cplusplus} +or @code{clk_objective_c}. Note that if we are preprocessing +assembler, this variable will be @code{clk_c} but the function-like +macro @code{preprocessing_asm_p()} will return true, so you might want +to check for that first. If you need to check for strict ANSI, the +variable @code{flag_iso} can be used. The function-like macro +@code{preprocessing_trad_p()} can be used to check for traditional +preprocessing. + +With @code{TARGET_OS_CPP_BUILTINS} this macro obsoletes the +@code{CPP_PREDEFINES} target macro. + +@findex TARGET_OS_CPP_BUILTINS +@item TARGET_OS_CPP_BUILTINS() +Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional +and is used for the target operating system instead. + +With @code{TARGET_CPU_CPP_BUILTINS} this macro obsoletes the +@code{CPP_PREDEFINES} target macro. + @findex CPP_PREDEFINES @item CPP_PREDEFINES Define this to be a string constant containing @option{-D} options to @@ -819,11 +844,9 @@ structure contains a field called @code{machine} whose type is to their own specific data. If a target needs per-function specific data it should define the type -@code{struct machine_function} and also the macro -@code{INIT_EXPANDERS}. This macro should be used to initialize some or -all of the function pointers @code{init_machine_status}, -@code{free_machine_status} and @code{mark_machine_status}. These -pointers are explained below. +@code{struct machine_function} and also the macro @code{INIT_EXPANDERS}. +This macro should be used to initialize the function pointer +@code{init_machine_status}. This pointer is explained below. One typical use of per-function, target specific data is to create an RTX to hold the register containing the function's return address. This @@ -859,19 +882,9 @@ specific initialization of the @code{struct function} structure. It is intended that this would be used to initialize the @code{machine} of that structure. -@findex free_machine_status -@item free_machine_status -This is a @code{void (*)(struct function *)} function pointer. If this -pointer is non-@code{NULL} it will be called once per function, after the -function has been compiled, in order to allow any memory allocated -during the @code{init_machine_status} function call to be freed. - -@findex mark_machine_status -@item mark_machine_status -This is a @code{void (*)(struct function *)} function pointer. If this -pointer is non-@code{NULL} it will be called once per function in order to mark -any data items in the @code{struct machine_function} structure which -need garbage collection. +@code{struct machine_function} structures are expected to be freed by GC. +Generally, any memory that they reference must be allocated by using +@code{ggc_alloc}, including the structure itself. @end table @@ -930,11 +943,12 @@ multi-word integers. @findex BITS_PER_UNIT @item BITS_PER_UNIT Define this macro to be the number of bits in an addressable storage -unit (byte); normally 8. +unit (byte). If you do not define this macro the default is 8. @findex BITS_PER_WORD @item BITS_PER_WORD -Number of bits in a word; normally 32. +Number of bits in a word. If you do not define this macro, the default +is @code{BITS_PER_UNIT * UNITS_PER_WORD}. @findex MAX_BITS_PER_WORD @item MAX_BITS_PER_WORD @@ -956,7 +970,8 @@ smallest value that @code{UNITS_PER_WORD} can have at run-time. @item POINTER_SIZE Width of a pointer, in bits. You must specify a value no wider than the width of @code{Pmode}. If it is not equal to the width of @code{Pmode}, -you must define @code{POINTERS_EXTEND_UNSIGNED}. +you must define @code{POINTERS_EXTEND_UNSIGNED}. If you do not specify +a value the default is @code{BITS_PER_WORD}. @findex POINTERS_EXTEND_UNSIGNED @item POINTERS_EXTEND_UNSIGNED @@ -1219,10 +1234,15 @@ Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited to aligning a bit-field within the structure. @findex MEMBER_TYPE_FORCES_BLK -@item MEMBER_TYPE_FORCES_BLK (@var{field}) +@item MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode}) Return 1 if a structure or array containing @var{field} should be accessed using @code{BLKMODE}. +If @var{field} is the only field in the structure, @var{mode} is its +mode, otherwise @var{mode} is VOIDmode. @var{mode} is provided in the +case where structures of one field would require the structure's mode to +retain the field's mode. + Normally, this is not needed. See the file @file{c4x.h} for an example of how to use this macro to prevent a structure having a floating point field from being accessed in an integer mode. @@ -1290,22 +1310,6 @@ You need not define this macro if it always returns @code{word_mode}. You would most commonly define this macro if the @code{allocate_stack} pattern needs to support both a 32- and a 64-bit mode. -@findex CHECK_FLOAT_VALUE -@item CHECK_FLOAT_VALUE (@var{mode}, @var{value}, @var{overflow}) -A C statement to validate the value @var{value} (of type -@code{double}) for mode @var{mode}. This means that you check whether -@var{value} fits within the possible range of values for mode -@var{mode} on this target machine. The mode @var{mode} is always -a mode of class @code{MODE_FLOAT}. @var{overflow} is nonzero if -the value is already known to be out of range. - -If @var{value} is not valid or if @var{overflow} is nonzero, you should -set @var{overflow} to 1 and then assign some valid value to @var{value}. -Allowing an invalid value to go through the compiler can produce -incorrect assembler code which may even cause Unix assemblers to crash. - -This macro need not be defined if there is no work for it to do. - @findex TARGET_FLOAT_FORMAT @item TARGET_FLOAT_FORMAT A code distinguishing the floating point format of the target machine. @@ -1319,7 +1323,8 @@ need to define this macro when the format is IEEE@. @findex VAX_FLOAT_FORMAT @item VAX_FLOAT_FORMAT -This code indicates the ``D float'' format used on the VAX@. +This code indicates the ``F float'' (for @code{float}) and ``D float'' +or ``G float'' formats (for @code{double}) used on the VAX and PDP-11@. @findex IBM_FLOAT_FORMAT @item IBM_FLOAT_FORMAT @@ -1334,15 +1339,101 @@ This code indicates the format used on the TMS320C3x/C4x. This code indicates any other format. @end table -The value of this macro is compared with @code{HOST_FLOAT_FORMAT}, which -is defined by the @command{configure} script, to determine whether the -target machine has the same format as the host machine. If any other +If any other formats are actually in use on supported machines, new codes should be defined for them. The ordering of the component words of floating point values stored in memory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN}. +@findex MODE_HAS_NANS +@item MODE_HAS_NANS (@var{mode}) +When defined, this macro should be true if @var{mode} has a NaN +representation. The compiler assumes that NaNs are not equal to +anything (including themselves) and that addition, subtraction, +multiplication and division all return NaNs when one operand is +NaN@. + +By default, this macro is true if @var{mode} is a floating-point +mode and the target floating-point format is IEEE@. + +@findex MODE_HAS_INFINITIES +@item MODE_HAS_INFINITIES (@var{mode}) +This macro should be true if @var{mode} can represent infinity. At +present, the compiler uses this macro to decide whether @samp{x - x} +is always defined. By default, the macro is true when @var{mode} +is a floating-point mode and the target format is IEEE@. + +@findex MODE_HAS_SIGNED_ZEROS +@item MODE_HAS_SIGNED_ZEROS (@var{mode}) +True if @var{mode} distinguishes between positive and negative zero. +The rules are expected to follow the IEEE standard: + +@itemize @bullet +@item +@samp{x + x} has the same sign as @samp{x}. + +@item +If the sum of two values with opposite sign is zero, the result is +positive for all rounding modes expect towards @minus{}infinity, for +which it is negative. + +@item +The sign of a product or quotient is negative when exactly one +of the operands is negative. +@end itemize + +The default definition is true if @var{mode} is a floating-point +mode and the target format is IEEE@. + +@findex MODE_HAS_SIGN_DEPENDENT_ROUNDING +@item MODE_HAS_SIGN_DEPENDENT_ROUNDING (@var{mode}) +If defined, this macro should be true for @var{mode} if it has at +least one rounding mode in which @samp{x} and @samp{-x} can be +rounded to numbers of different magnitude. Two such modes are +towards @minus{}infinity and towards +infinity. + +The default definition of this macro is true if @var{mode} is +a floating-point mode and the target format is IEEE@. + +@findex ROUND_TOWARDS_ZERO +@item ROUND_TOWARDS_ZERO +If defined, this macro should be true if the prevailing rounding +mode is towards zero. A true value has the following effects: + +@itemize @bullet +@item +@code{MODE_HAS_SIGN_DEPENDENT_ROUNDING} will be false for all modes. + +@item +@file{libgcc.a}'s floating-point emulator will round towards zero +rather than towards nearest. + +@item +The compiler's floating-point emulator will round towards zero after +doing arithmetic, and when converting from the internal float format to +the target format. +@end itemize + +The macro does not affect the parsing of string literals. When the +primary rounding mode is towards zero, library functions like +@code{strtod} might still round towards nearest, and the compiler's +parser should behave like the target's @code{strtod} where possible. + +Not defining this macro is equivalent to returning zero. + +@findex LARGEST_EXPONENT_IS_NORMAL +@item LARGEST_EXPONENT_IS_NORMAL (@var{size}) +This macro should return true if floats with @var{size} +bits do not have a NaN or infinity representation, but use the largest +exponent for normal numbers instead. + +Defining this macro to true for @var{size} causes @code{MODE_HAS_NANS} +and @code{MODE_HAS_INFINITIES} to be false for @var{size}-bit modes. +It also affects the way @file{libgcc.a} and @file{real.c} emulate +floating-point arithmetic. + +The default definition of this macro returns false for all sizes. @end table @deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (tree @var{record_type}) @@ -1355,8 +1446,22 @@ alignment of the underlying types of itself and of the previous bit-field; (ii) a zero-sized bit-field will affect the alignment of the whole enclosing structure, even if it is unnamed; except that (iii) a zero-sized bit-field will be disregarded unless it follows -another bit-field of non-zero size. If this hook returns @code{true}, +another bit-field of nonzero size. If this hook returns @code{true}, other macros that control bit-field layout are ignored. + +When a bit-field is inserted into a packed record, the whole size +of the underlying type is used by one or more same-size adjacent +bit-fields (that is, if its long:3, 32 bits is used in the record, +and any additional adjacent long bit-fields are packed into the same +chunk of 32 bits. However, if the size changes, a new field of that +size is allocated). In an unpacked record, this is the same as using +alignment, but not equivalent when packing. + +If both MS bit-fields and @samp{__attribute__((packed))} are used, +the latter will take precedence. If @samp{__attribute__((packed))} is +used on a single field when MS bit-fields are in use, it will take +precedence for that field, but the alignment of the rest of the structure +may affect its placement. @end deftypefn @node Type Layout @@ -1414,14 +1519,6 @@ 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 @code{BITS_PER_UNIT}. -@findex MAX_CHAR_TYPE_SIZE -@item MAX_CHAR_TYPE_SIZE -Maximum number for the size in bits of the type @code{char} on the -target machine. If this is undefined, the default is -@code{CHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the -largest value that @code{CHAR_TYPE_SIZE} can have at run-time. This is -used in @code{cpp}. - @findex BOOL_TYPE_SIZE @item BOOL_TYPE_SIZE A C expression for the size in bits of the C++ type @code{bool} and @@ -1452,9 +1549,12 @@ target machine. If this is undefined, the default is the largest value that @code{LONG_DOUBLE_TYPE_SIZE} can have at run-time. This is used in @code{cpp}. -@findex INTEL_EXTENDED_IEEE_FORMAT -Define this macro to be 1 if the target machine uses 80-bit floating-point -values with 128-bit size and alignment. This is used in @file{real.c}. +@findex TARGET_FLT_EVAL_METHOD +@item TARGET_FLT_EVAL_METHOD +A C expression for the value for @code{FLT_EVAL_METHOD} in @file{float.h}, +assuming, if applicable, that the floating-point control word is in its +default state. If you do not define this macro the value of +@code{FLT_EVAL_METHOD} will be zero. @findex WIDEST_HARDWARE_FP_SIZE @item WIDEST_HARDWARE_FP_SIZE @@ -1620,6 +1720,20 @@ pointer to which the function's data is relative. If vtables are used, the value of this macro should be the number of words that the function descriptor occupies. + +@findex TARGET_VTABLE_ENTRY_ALIGN +@item TARGET_VTABLE_ENTRY_ALIGN +By default, the vtable entries are void pointers, the so the alignment +is the same as pointer alignment. The value of this macro specifies +the alignment of the vtable entry in bits. It should be defined only +when special alignment is necessary. */ + +@findex TARGET_VTABLE_DATA_ENTRY_DISTANCE +@item TARGET_VTABLE_DATA_ENTRY_DISTANCE +There are a few non-descriptor entries in the vtable at offsets below +zero. If these entries must be padded (say, to preserve the alignment +specified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number +of words in each data entry. @end table @node Escape Sequences @@ -2190,7 +2304,7 @@ which is the register value plus a displacement. @findex MODE_BASE_REG_CLASS @item MODE_BASE_REG_CLASS (@var{mode}) This is a variation of the @code{BASE_REG_CLASS} macro which allows -the selection of a base register in a mode depenedent manner. If +the selection of a base register in a mode dependent manner. If @var{mode} is VOIDmode then it should return the same value as @code{BASE_REG_CLASS}. @@ -2299,7 +2413,7 @@ from memory or even from other types of registers. An example is the from general registers, but not memory. Some machines allow copying all registers to and from memory, but require a scratch register for stores to some memory locations (e.g., those with symbolic address on the RT, -and those with certain symbolic address on the Sparc when compiling +and those with certain symbolic address on the SPARC when compiling PIC)@. In some cases, both an intermediate and a scratch register are required. @@ -2447,25 +2561,22 @@ should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, This macro helps control the handling of multiple-word values in the reload pass. -@item CLASS_CANNOT_CHANGE_MODE -If defined, a C expression for a class that contains registers for -which the compiler may not change modes arbitrarily. - -@item CLASS_CANNOT_CHANGE_MODE_P(@var{from}, @var{to}) -A C expression that is true if, for a register in -@code{CLASS_CANNOT_CHANGE_MODE}, the requested mode punning is invalid. +@item CANNOT_CHANGE_MODE_CLASS(@var{from}, @var{to}, @var{class}) +If defined, a C expression that returns nonzero for a @var{class} for which +a change from mode @var{from} to mode @var{to} is invalid. For the example, loading 32-bit integer or floating-point objects into floating-point registers on the Alpha extends them to 64 bits. Therefore loading a 64-bit object and then storing it as a 32-bit object does not store the low-order 32 bits, as would be the case for a normal -register. Therefore, @file{alpha.h} defines @code{CLASS_CANNOT_CHANGE_MODE} -as @code{FLOAT_REGS} and @code{CLASS_CANNOT_CHANGE_MODE_P} restricts -mode changes to same-size modes. +register. Therefore, @file{alpha.h} defines @code{CANNOT_CHANGE_MODE_CLASS} +as below: -Compare this to IA-64, which extends floating-point values to 82 bits, -and stores 64-bit integers in a different format than 64-bit doubles. -Therefore @code{CLASS_CANNOT_CHANGE_MODE_P} is always true. +@example +#define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \ + (GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \ + ? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0) +@end example @end table Three other special macros describe which operands fit which constraint @@ -2518,6 +2629,44 @@ letter @samp{Q} is defined as representing a memory address that does a @samp{Q} constraint on the input and @samp{r} on the output. The next alternative specifies @samp{m} on the input and a register class that does not include r0 on the output. + +@findex EXTRA_MEMORY_CONSTRAINT +@item EXTRA_MEMORY_CONSTRAINT (@var{c}) +A C expression that defines the optional machine-dependent constraint +letters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should +be treated like memory constraints by the reload pass. + +It should return 1 if the operand type represented by the constraint +letter @var{c} comprises a subset of all memory references including +all those whose address is simply a base register. This allows the reload +pass to reload an operand, if it does not directly correspond to the operand +type of @var{c}, by copying its address into a base register. + +For example, on the S/390, some instructions do not accept arbitrary +memory references, but only those that do not make use of an index +register. The constraint letter @samp{Q} is defined via +@code{EXTRA_CONSTRAINT} as representing a memory address of this type. +If the letter @samp{Q} is marked as @code{EXTRA_MEMORY_CONSTRAINT}, +a @samp{Q} constraint can handle any memory operand, because the +reload pass knows it can be reloaded by copying the memory address +into a base register if required. This is analogous to the way +a @samp{o} constraint can handle any memory operand. + +@findex EXTRA_ADDRESS_CONSTRAINT +@item EXTRA_ADDRESS_CONSTRAINT (@var{c}) +A C expression that defines the optional machine-dependent constraint +letters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should +be treated like address constraints by the reload pass. + +It should return 1 if the operand type represented by the constraint +letter @var{c} comprises a subset of all memory addresses including +all those that consist of just a base register. This allows the reload +pass to reload an operand, if it does not directly correspond to the operand +type of @var{c}, by copying it into a base register. + +Any constraint marked as @code{EXTRA_ADDRESS_CONSTRAINT} can only +be used with the @code{address_operand} predicate. It is treated +analogously to the @samp{p} constraint. @end table @node Stack and Calling @@ -2566,7 +2715,7 @@ definition used does not matter. This macro defines the operation used when something is pushed on the stack. In RTL, a push operation will be -@code{(set (mem (STACK_PUSH_CODE (reg sp))) ...)} +@code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})} The choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC}, and @code{POST_INC}. Which of these is correct depends on @@ -2641,7 +2790,7 @@ address of the stack word that points to the previous frame. @item SETUP_FRAME_ADDRESSES If defined, a C expression that produces the machine-specific code to setup the stack so that arbitrary frames can be accessed. For example, -on the Sparc, we must flush all of the register windows to the stack +on the SPARC, we must flush all of the register windows to the stack before we can access arbitrary stack frames. You will seldom need to define this macro. @@ -2750,8 +2899,12 @@ It will be assigned zero on code paths that return normally. Typically this is a call-clobbered hard register that is otherwise untouched by the epilogue, but could also be a stack slot. -You must define this macro if you want to support call frame exception -handling like that provided by DWARF 2. +Do not define this macro if the stack pointer is saved and restored +by the regular prolog and epilog code in the call frame itself; in +this case, the exception handling library routines will update the +stack location to be restored in place. Otherwise, you must define +this macro if you want to support call frame exception handling like +that provided by DWARF 2. @findex EH_RETURN_HANDLER_RTX @item EH_RETURN_HANDLER_RTX @@ -2763,8 +2916,9 @@ Typically this is the location in the call frame at which the normal return address is stored. For targets that return by popping an address off the stack, this might be a memory address just below the @emph{target} call frame rather than inside the current call -frame. @code{EH_RETURN_STACKADJ_RTX} will have already been assigned, -so it may be used to calculate the location of the target call frame. +frame. If defined, @code{EH_RETURN_STACKADJ_RTX} will have already +been assigned, so it may be used to calculate the location of the +target call frame. Some targets have more complex requirements than storing to an address calculable during initial code generation. In that case @@ -3434,14 +3588,6 @@ nonzero, the caller does not make a copy. Instead, it passes a pointer to the determined that the value won't be modified, it need not make a copy; otherwise a copy must be made. -@findex FUNCTION_ARG_REG_LITTLE_ENDIAN -@item FUNCTION_ARG_REG_LITTLE_ENDIAN -If defined TRUE on a big-endian system then structure arguments passed -(and returned) in registers are passed in a little-endian manner instead of -the big-endian manner. On the HP-UX IA64 and PA64 platforms structures are -aligned differently then integral values and setting this value to true will -allow for the special handling of structure arguments and return values. - @findex CUMULATIVE_ARGS @item CUMULATIVE_ARGS A C type for declaring a variable that is used as the first argument of @@ -3567,11 +3713,6 @@ This section discusses the macros that control returning scalars as values---values that can fit in registers. @table @code -@findex TRADITIONAL_RETURN_FLOAT -@item TRADITIONAL_RETURN_FLOAT -Define this macro if @option{-traditional} should not cause functions -declared to return @code{float} to convert the value to @code{double}. - @findex FUNCTION_VALUE @item FUNCTION_VALUE (@var{valtype}, @var{func}) A C expression to create an RTX representing the place where a @@ -3916,7 +4057,7 @@ arguments. But usually, on such machines, nothing else has been pushed yet, because the function prologue itself does all the pushing.) This region is used on machines where an argument may be passed partly in registers and partly in memory, and, in some cases to support the -features in @code{<varargs.h>} and @code{<stdarg.h>}. +features in @code{<stdarg.h>}. @item An area of memory used to save certain registers used by the function. @@ -4003,9 +4144,11 @@ outputting the insns in this list, usually by calling You need not define this macro if you did not define @code{DELAY_SLOTS_FOR_EPILOGUE}. -@findex ASM_OUTPUT_MI_THUNK -@item ASM_OUTPUT_MI_THUNK (@var{file}, @var{thunk_fndecl}, @var{delta}, @var{function}) -A C compound statement that outputs the assembler code for a thunk +@end table + +@findex TARGET_ASM_OUTPUT_MI_THUNK +@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_MI_THUNK (FILE *@var{file}, tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, tree @var{function}) +A function that outputs the assembler code for a thunk function, used to implement C++ virtual function calls with multiple inheritance. The thunk acts as a wrapper around a virtual function, adjusting the implicit object parameter before handing control off to @@ -4036,7 +4179,24 @@ If you do not define this macro, the target-independent code in the C++ front end will generate a less efficient heavyweight thunk that calls @var{function} instead of jumping to it. The generic approach does not support varargs. -@end table +@end deftypefn + +@findex TARGET_ASM_OUTPUT_MI_VCALL_THUNK +@deftypefn {Target Hook} void TARGET_ASM_OUTPUT_MI_VCALL_THUNK (FILE *@var{file}, tree @var{thunk_fndecl}, HOST_WIDE_INT @var{delta}, int @var{vcall_offset}, tree @var{function}) +A function like @code{TARGET_ASM_OUTPUT_MI_THUNK}, except that if +@var{vcall_offset} is nonzero, an additional adjustment should be made +after adding @code{delta}. In particular, if @var{p} is the +adjusted pointer, the following adjustment should be made: + +@example +p += (*((ptrdiff_t **)p))[vcall_offset/sizeof(ptrdiff_t)] +@end example + +@noindent +If this function is defined, it will always be used in place of +@code{TARGET_ASM_OUTPUT_MI_THUNK}. + +@end deftypefn @node Profiling @subsection Generating Code for Profiling @@ -4078,22 +4238,6 @@ must not use the @var{labelno} argument to @code{FUNCTION_PROFILER}. @item PROFILE_BEFORE_PROLOGUE Define this macro if the code for function profiling should come before the function prologue. Normally, the profiling code comes after. - - -@findex TARGET_ALLOWS_PROFILING_WITHOUT_FRAME_POINTER -@item TARGET_ALLOWS_PROFILING_WITHOUT_FRAME_POINTER -On some targets, it is impossible to use profiling when the frame -pointer has been omitted. For example, on x86 GNU/Linux systems, -the @code{mcount} routine provided by the GNU C Library finds the -address of the routine that called the routine that called @code{mcount} -by looking in the immediate caller's stack frame. If the immediate -caller has no frame pointer, this lookup will fail. - -By default, GCC assumes that the target does allow profiling when the -frame pointer is omitted. This macro should be defined to a C -expression that evaluates to @code{false} if the target does not allow -profiling when the frame pointer is omitted. - @end table @node Tail Calls @@ -4524,6 +4668,13 @@ 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{__umoddi3}, a function defined in @file{libgcc.a}. +@findex DECLARE_LIBRARY_RENAMES +@item DECLARE_LIBRARY_RENAMES +This macro, if defined, should expand to a piece of C code that will get +expanded when compiling functions for libgcc.a. It can be used to +provide alternate names for gcc's internal library functions if there +are ABI-mandated names that the compiler should provide. + @findex INIT_TARGET_OPTABS @item INIT_TARGET_OPTABS Define this macro as a C statement that declares additional library @@ -4692,11 +4843,11 @@ sums that are not marked with @code{const}. It assumes that a naked naked constant sums as illegitimate addresses, so that none of them will be given to @code{PRINT_OPERAND_ADDRESS}. -@cindex @code{ENCODE_SECTION_INFO} and address validation +@cindex @code{TARGET_ENCODE_SECTION_INFO} and address validation On some machines, whether a symbolic address is legitimate depends on the section that the address refers to. On these machines, define the -macro @code{ENCODE_SECTION_INFO} to store the information into the -@code{symbol_ref}, and then check for it here. When you see a +target hook @code{TARGET_ENCODE_SECTION_INFO} to store the information +into the @code{symbol_ref}, and then check for it here. When you see a @code{const}, you will have to look inside it to find the @code{symbol_ref} in order to determine the section. @xref{Assembler Format}. @@ -4706,8 +4857,8 @@ The best way to modify the name string is by adding text to the beginning, with suitable punctuation to prevent any ambiguity. Allocate the new name in @code{saveable_obstack}. You will have to modify @code{ASM_OUTPUT_LABELREF} to remove and decode the added text and -output the name accordingly, and define @code{STRIP_NAME_ENCODING} to -access the original name string. +output the name accordingly, and define @code{TARGET_STRIP_NAME_ENCODING} +to access the original name string. You can check the information stored here into the @code{symbol_ref} in the definitions of the macros @code{GO_IF_LEGITIMATE_ADDRESS} and @@ -4931,29 +5082,34 @@ two places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. @findex EXTRA_CC_MODES @item EXTRA_CC_MODES -A list of additional modes for condition code values in registers -(@pxref{Jump Patterns}). This macro should expand to a sequence of -calls of the macro @code{CC} separated by white space. @code{CC} takes -two arguments. The first is the enumeration name of the mode, which -should begin with @samp{CC} and end with @samp{mode}. The second is a C -string giving the printable name of the mode; it should be the same as -the first argument, but with the trailing @samp{mode} removed. +Condition codes are represented in registers by machine modes of class +@code{MODE_CC}. By default, there is just one mode, @code{CCmode}, with +this class. If you need more such modes, create a file named +@file{@var{machine}-modes.def} in your @file{config/@var{machine}} +directory (@pxref{Back End, , Anatomy of a Target Back End}), containing +a list of these modes. Each entry in the list should be a call to the +macro @code{CC}. This macro takes one argument, which is the name of +the mode: it should begin with @samp{CC}. Do not put quotation marks +around the name, or include the trailing @samp{mode}; these are +automatically added. There should not be anything else in the file +except comments. + +A sample @file{@var{machine}-modes.def} file might look like this: -You should only define this macro if additional modes are required. - -A sample definition of @code{EXTRA_CC_MODES} is: @smallexample -#define EXTRA_CC_MODES \ - CC(CC_NOOVmode, "CC_NOOV") \ - CC(CCFPmode, "CCFP") \ - CC(CCFPEmode, "CCFPE") +CC (CC_NOOV) /* @r{Comparison only valid if there was no overflow.} */ +CC (CCFP) /* @r{Floating point comparison that cannot trap.} */ +CC (CCFPE) /* @r{Floating point comparison that may trap.} */ @end smallexample +When you create this file, the macro @code{EXTRA_CC_MODES} is +automatically defined by @command{configure}, with value @samp{1}. + @findex SELECT_CC_MODE @item SELECT_CC_MODE (@var{op}, @var{x}, @var{y}) Returns a mode from class @code{MODE_CC} to be used when comparison operation code @var{op} is applied to rtx @var{x} and @var{y}. For -example, on the Sparc, @code{SELECT_CC_MODE} is defined as (see +example, on the SPARC, @code{SELECT_CC_MODE} is defined as (see @pxref{Jump Patterns} for a description of the reason for this definition) @@ -4997,7 +5153,7 @@ then @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero. You need not define this macro if it would always returns zero or if the floating-point format is anything other than @code{IEEE_FLOAT_FORMAT}. -For example, here is the definition used on the Sparc, where floating-point +For example, here is the definition used on the SPARC, where floating-point inequality comparisons are always given @code{CCFPEmode}: @smallexample @@ -5246,6 +5402,22 @@ than @code{MOVE_RATIO}. A C expression used by @code{move_by_pieces} to determine the largest unit a load or store used to copy memory is. Defaults to @code{MOVE_MAX}. +@findex CLEAR_RATIO +@item CLEAR_RATIO +The threshold of number of scalar move insns, @emph{below} which a sequence +of insns should be generated to clear memory instead of a string clear insn +or a library call. Increasing the value will always make code faster, but +eventually incurs high cost in increased code size. + +If you don't define this, a reasonable default is used. + +@findex CLEAR_BY_PIECES_P +@item CLEAR_BY_PIECES_P (@var{size}, @var{alignment}) +A C expression used to determine whether @code{clear_by_pieces} will be used +to clear a chunk of memory, or whether some other block clear mechanism +will be used. Defaults to 1 if @code{move_by_pieces_ninsns} returns less +than @code{CLEAR_RATIO}. + @findex USE_LOAD_POST_INCREMENT @item USE_LOAD_POST_INCREMENT (@var{mode}) A C expression used to determine whether a load postincrement is a good @@ -5315,11 +5487,18 @@ hooks for this purpose. It is usually enough to define just a few of them: try the first ones in this list first. @deftypefn {Target Hook} int TARGET_SCHED_ISSUE_RATE (void) -This hook returns the maximum number of instructions that can ever issue -at the same time on the target machine. The default is one. This value -must be constant over the entire compilation. If you need it to vary -depending on what the instructions are, you must use +This hook returns the maximum number of instructions that can ever +issue at the same time on the target machine. The default is one. +Although the insn scheduler can define itself the possibility of issue +an insn on the same cycle, the value can serve as an additional +constraint to issue insns on the same simulated processor cycle (see +hooks @samp{TARGET_SCHED_REORDER} and @samp{TARGET_SCHED_REORDER2}). +This value must be constant over the entire compilation. If you need +it to vary depending on what the instructions are, you must use @samp{TARGET_SCHED_VARIABLE_ISSUE}. + +For the automaton based pipeline interface, you could define this hook +to return the value of the macro @code{MAX_DFA_ISSUE_RATE}. @end deftypefn @deftypefn {Target Hook} int TARGET_SCHED_VARIABLE_ISSUE (FILE *@var{file}, int @var{verbose}, rtx @var{insn}, int @var{more}) @@ -5335,12 +5514,18 @@ instruction that was scheduled. @end deftypefn @deftypefn {Target Hook} int TARGET_SCHED_ADJUST_COST (rtx @var{insn}, rtx @var{link}, rtx @var{dep_insn}, int @var{cost}) -This function corrects the value of @var{cost} based on the relationship -between @var{insn} and @var{dep_insn} through the dependence @var{link}. -It should return the new value. The default is to make no adjustment to -@var{cost}. This can be used for example to specify to the scheduler +This function corrects the value of @var{cost} based on the +relationship between @var{insn} and @var{dep_insn} through the +dependence @var{link}. It should return the new value. The default +is to make no adjustment to @var{cost}. This can be used for example +to specify to the scheduler using the traditional pipeline description that an output- or anti-dependence does not incur the same cost as a -data-dependence. +data-dependence. If the scheduler using the automaton based pipeline +description, the cost of anti-dependence is zero and the cost of +output-dependence is maximum of one and the difference of latency +times of the first and the second insns. If these values are not +acceptable, you could use the hook to modify them too. See also +@pxref{Automaton pipeline description}. @end deftypefn @deftypefn {Target Hook} int TARGET_SCHED_ADJUST_PRIORITY (rtx @var{insn}, int @var{priority}) @@ -5398,14 +5583,140 @@ to. @var{verbose} is the verbose level provided by @option{-fsched-verbose-@var{n}}. @end deftypefn -@deftypefn {Target Hook} rtx TARGET_SCHED_CYCLE_DISPLAY (int @var{clock}, rtx @var{last}) -This hook is called in verbose mode only, at the beginning of each pass -over a basic block. It should insert an insn into the chain after -@var{last}, which has no effect, but records the value @var{clock} in -RTL dumps and assembly output. Define this hook only if you need this -level of detail about what the scheduler is doing. +@deftypefn {Target Hook} int TARGET_SCHED_USE_DFA_PIPELINE_INTERFACE (void) +This hook is called many times during insn scheduling. If the hook +returns nonzero, the automaton based pipeline description is used for +insn scheduling. Otherwise the traditional pipeline description is +used. The default is usage of the traditional pipeline description. + +You should also remember that to simplify the insn scheduler sources +an empty traditional pipeline description interface is generated even +if there is no a traditional pipeline description in the @file{.md} +file. The same is true for the automaton based pipeline description. +That means that you should be accurate in defining the hook. +@end deftypefn + +@deftypefn {Target Hook} int TARGET_SCHED_DFA_PRE_CYCLE_INSN (void) +The hook returns an RTL insn. The automaton state used in the +pipeline hazard recognizer is changed as if the insn were scheduled +when the new simulated processor cycle starts. Usage of the hook may +simplify the automaton pipeline description for some @acronym{VLIW} +processors. If the hook is defined, it is used only for the automaton +based pipeline description. The default is not to change the state +when the new simulated processor cycle starts. +@end deftypefn + +@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN (void) +The hook can be used to initialize data used by the previous hook. +@end deftypefn + +@deftypefn {Target Hook} int TARGET_SCHED_DFA_POST_CYCLE_INSN (void) +The hook is analogous to @samp{TARGET_SCHED_DFA_PRE_CYCLE_INSN} but used +to changed the state as if the insn were scheduled when the new +simulated processor cycle finishes. @end deftypefn +@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_POST_CYCLE_INSN (void) +The hook is analogous to @samp{TARGET_SCHED_INIT_DFA_PRE_CYCLE_INSN} but +used to initialize data used by the previous hook. +@end deftypefn + +@deftypefn {Target Hook} int TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD (void) +This hook controls better choosing an insn from the ready insn queue +for the @acronym{DFA}-based insn scheduler. Usually the scheduler +chooses the first insn from the queue. If the hook returns a positive +value, an additional scheduler code tries all permutations of +@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD ()} +subsequent ready insns to choose an insn whose issue will result in +maximal number of issued insns on the same cycle. For the +@acronym{VLIW} processor, the code could actually solve the problem of +packing simple insns into the @acronym{VLIW} insn. Of course, if the +rules of @acronym{VLIW} packing are described in the automaton. + +This code also could be used for superscalar @acronym{RISC} +processors. Let us consider a superscalar @acronym{RISC} processor +with 3 pipelines. Some insns can be executed in pipelines @var{A} or +@var{B}, some insns can be executed only in pipelines @var{B} or +@var{C}, and one insn can be executed in pipeline @var{B}. The +processor may issue the 1st insn into @var{A} and the 2nd one into +@var{B}. In this case, the 3rd insn will wait for freeing @var{B} +until the next cycle. If the scheduler issues the 3rd insn the first, +the processor could issue all 3 insns per cycle. + +Actually this code demonstrates advantages of the automaton based +pipeline hazard recognizer. We try quickly and easy many insn +schedules to choose the best one. + +The default is no multipass scheduling. +@end deftypefn + +@deftypefn {Target Hook} void TARGET_SCHED_INIT_DFA_BUBBLES (void) +The @acronym{DFA}-based scheduler could take the insertion of nop +operations for better insn scheduling into account. It can be done +only if the multi-pass insn scheduling works (see hook +@samp{TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD}). + +Let us consider a @acronym{VLIW} processor insn with 3 slots. Each +insn can be placed only in one of the three slots. We have 3 ready +insns @var{A}, @var{B}, and @var{C}. @var{A} and @var{C} can be +placed only in the 1st slot, @var{B} can be placed only in the 3rd +slot. We described the automaton which does not permit empty slot +gaps between insns (usually such description is simpler). Without +this code the scheduler would place each insn in 3 separate +@acronym{VLIW} insns. If the scheduler places a nop insn into the 2nd +slot, it could place the 3 insns into 2 @acronym{VLIW} insns. What is +the nop insn is returned by hook @samp{TARGET_SCHED_DFA_BUBBLE}. Hook +@samp{TARGET_SCHED_INIT_DFA_BUBBLES} can be used to initialize or +create the nop insns. + +You should remember that the scheduler does not insert the nop insns. +It is not wise because of the following optimizations. The scheduler +only considers such possibility to improve the result schedule. The +nop insns should be inserted lately, e.g. on the final phase. +@end deftypefn + +@deftypefn {Target Hook} rtx TARGET_SCHED_DFA_BUBBLE (int @var{index}) +This hook @samp{FIRST_CYCLE_MULTIPASS_SCHEDULING} is used to insert +nop operations for better insn scheduling when @acronym{DFA}-based +scheduler makes multipass insn scheduling (see also description of +hook @samp{TARGET_SCHED_INIT_DFA_BUBBLES}). This hook +returns a nop insn with given @var{index}. The indexes start with +zero. The hook should return @code{NULL} if there are no more nop +insns with indexes greater than given index. +@end deftypefn + +Macros in the following table are generated by the program +@file{genattr} and can be useful for writing the hooks. + +@table @code +@findex TRADITIONAL_PIPELINE_INTERFACE +@item TRADITIONAL_PIPELINE_INTERFACE +The macro definition is generated if there is a traditional pipeline +description in @file{.md} file. You should also remember that to +simplify the insn scheduler sources an empty traditional pipeline +description interface is generated even if there is no a traditional +pipeline description in the @file{.md} file. The macro can be used to +distinguish the two types of the traditional interface. + +@findex DFA_PIPELINE_INTERFACE +@item DFA_PIPELINE_INTERFACE +The macro definition is generated if there is an automaton pipeline +description in @file{.md} file. You should also remember that to +simplify the insn scheduler sources an empty automaton pipeline +description interface is generated even if there is no an automaton +pipeline description in the @file{.md} file. The macro can be used to +distinguish the two types of the automaton interface. + +@findex MAX_DFA_ISSUE_RATE +@item MAX_DFA_ISSUE_RATE +The macro definition is generated in the automaton based pipeline +description interface. Its value is calculated from the automaton +based pipeline description and is equal to maximal number of all insns +described in constructions @samp{define_insn_reservation} which can be +issued on the same processor cycle. + +@end table + @node Sections @section Dividing the Output into Sections (Texts, Data, @dots{}) @c the above section title is WAY too long. maybe cut the part between @@ -5436,12 +5747,39 @@ Normally this is not needed, as simply defining @code{TEXT_SECTION_ASM_OP} is enough. The MIPS port uses this to sort all functions after all data declarations. +@findex HOT_TEXT_SECTION_NAME +@item HOT_TEXT_SECTION_NAME +If defined, a C string constant for the name of the section containing most +frequently executed functions of the program. If not defined, GCC will provide +a default definition if the target supports named sections. + +@findex UNLIKELY_EXECUTED_TEXT_SECTION_NAME +@item UNLIKELY_EXECUTED_TEXT_SECTION_NAME +If defined, a C string constant for the name of the section containing unlikely +executed functions in the program. + @findex DATA_SECTION_ASM_OP @item DATA_SECTION_ASM_OP A C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as writable initialized data. Normally @code{"\t.data"} is right. +@findex READONLY_DATA_SECTION_ASM_OP +@item READONLY_DATA_SECTION_ASM_OP +A C expression whose value is a string, including spacing, containing the +assembler operation to identify the following data as read-only initialized +data. + +@findex READONLY_DATA_SECTION +@item READONLY_DATA_SECTION +A macro naming a function to call to switch to the proper section for +read-only data. The default is to use @code{READONLY_DATA_SECTION_ASM_OP} +if defined, else fall back to @code{text_section}. + +The most common definition will be @code{data_section}, if the target +does not have a special read-only data section, and does not put data +in the text section. + @findex SHARED_SECTION_ASM_OP @item SHARED_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, @@ -5515,44 +5853,6 @@ 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}. -@findex READONLY_DATA_SECTION -@item READONLY_DATA_SECTION -On most machines, read-only variables, constants, and jump tables are -placed in the text section. If this is not the case on your machine, -this macro should be defined to be the name of a function (either -@code{data_section} or a function defined in @code{EXTRA_SECTIONS}) that -switches to the section to be used for read-only items. - -If these items should be placed in the text section, this macro should -not be defined. - -@findex SELECT_SECTION -@item SELECT_SECTION (@var{exp}, @var{reloc}, @var{align}) -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. @var{reloc} -indicates whether the initial value of @var{exp} requires link-time -relocations. Bit 1 is set when variable contains local relocations -only, while bit 2 is set for global relocations. -Select the section by calling @code{text_section} or one -of the alternatives for other sections. @var{align} is the constant -alignment in bits. - -Do not define this macro if you put all read-only variables and -constants in the read-only data section (usually the text section). - -@findex SELECT_RTX_SECTION -@item SELECT_RTX_SECTION (@var{mode}, @var{rtx}, @var{align}) -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. @var{align} is the constant alignment in bits. - -Do not define this macro if you put all constants in the read-only -data section. - @findex JUMP_TABLES_IN_TEXT_SECTION @item JUMP_TABLES_IN_TEXT_SECTION Define this macro to be an expression with a nonzero value if jump @@ -5561,44 +5861,104 @@ section, along with the assembler instructions. Otherwise, the readonly data section is used. This macro is irrelevant if there is no separate readonly data section. +@end table + +@deftypefn {Target Hook} void TARGET_ASM_SELECT_SECTION (tree @var{exp}, int @var{reloc}, unsigned HOST_WIDE_INT @var{align}) +Switches 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. @var{reloc} indicates whether the initial value of @var{exp} +requires link-time relocations. Bit 0 is set when variable contains +local relocations only, while bit 1 is set for global relocations. +Select the section by calling @code{data_section} or one of the +alternatives for other sections. @var{align} is the constant alignment +in bits. + +The default version of this function takes care of putting read-only +variables in @code{readonly_data_section}. +@end deftypefn + +@deftypefn {Target Hook} void TARGET_ASM_UNIQUE_SECTION (tree @var{decl}, int @var{reloc}) +Build up a unique section name, expressed as a @code{STRING_CST} node, +and assign it to @samp{DECL_SECTION_NAME (@var{decl})}. +As with @code{TARGET_ASM_SELECT_SECTION}, @var{reloc} indicates whether +the initial value of @var{exp} requires link-time relocations. + +The default version of this function appends the symbol name to the +ELF section name that would normally be used for the symbol. For +example, the function @code{foo} would be placed in @code{.text.foo}. +Whatever the actual target object format, this is often good enough. +@end deftypefn -@findex ENCODE_SECTION_INFO -@item ENCODE_SECTION_INFO (@var{decl}) -Define this macro if references to a symbol or a constant must be +@deftypefn {Target Hook} void TARGET_ASM_SELECT_RTX_SECTION (enum machine_mode @var{mode}, rtx @var{x}, unsigned HOST_WIDE_INT @var{align}) +Switches to the appropriate section for output of constant pool entry +@var{x} in @var{mode}. You can assume that @var{x} 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{readonly_data_section} or one of the alternatives for other +sections. @var{align} is the constant alignment in bits. + +The default version of this function takes care of putting symbolic +constants in @code{flag_pic} mode in @code{data_section} and everything +else in @code{readonly_data_section}. +@end deftypefn + +@deftypefn {Target Hook} void TARGET_ENCODE_SECTION_INFO (tree @var{decl}, int @var{new_decl_p}) +Define this hook if references to a symbol or a constant must be treated differently depending on something about the variable or function named by the symbol (such as what section it is in). -The macro definition, if any, is executed under two circumstances. One -is immediately after the rtl for @var{decl} that represents a variable -or a function has been created and stored in @code{DECL_RTL -(@var{decl})}. The value of the rtl will be a @code{mem} whose address -is a @code{symbol_ref}. The other is immediately after the rtl for -@var{decl} that represents a constant has been created and stored in -@code{TREE_CST_RTL (@var{decl})}. The macro is called once for each -distinct constant in a source file. - -@cindex @code{SYMBOL_REF_FLAG}, in @code{ENCODE_SECTION_INFO} -The usual thing for this macro to do is to record a flag in the +The hook is executed under two circumstances. One is immediately after +the rtl for @var{decl} that represents a variable or a function has been +created and stored in @code{DECL_RTL(@var{decl})}. The value of the rtl +will be a @code{mem} whose address is a @code{symbol_ref}. The other is +immediately after the rtl for @var{decl} that represents a constant has +been created and stored in @code{TREE_CST_RTL (@var{decl})}. The macro +is called once for each distinct constant in a source file. + +The @var{new_decl_p} argument will be true if this is the first time +that @code{ENCODE_SECTION_INFO} has been invoked on this decl. It will +be false for subsequent invocations, which will happen for duplicate +declarations. Whether or not anything must be done for the duplicate +declaration depends on whether the hook examines @code{DECL_ATTRIBUTES}. + +@cindex @code{SYMBOL_REF_FLAG}, in @code{TARGET_ENCODE_SECTION_INFO} +The usual thing for this hook to do is to record a flag in the @code{symbol_ref} (such as @code{SYMBOL_REF_FLAG}) or to store a -modified name string in the @code{symbol_ref} (if one bit is not enough -information). - -@findex STRIP_NAME_ENCODING -@item STRIP_NAME_ENCODING (@var{var}, @var{sym_name}) -Decode @var{sym_name} and store the real name part in @var{var}, sans -the characters that encode section info. Define this macro if -@code{ENCODE_SECTION_INFO} alters the symbol's name string. - -@findex UNIQUE_SECTION -@item UNIQUE_SECTION (@var{decl}, @var{reloc}) -A C statement to build up a unique section name, expressed as a -@code{STRING_CST} node, and assign it to @samp{DECL_SECTION_NAME (@var{decl})}. -@var{reloc} indicates whether the initial value of @var{exp} requires -link-time relocations. If you do not define this macro, GCC will use -the symbol name prefixed by @samp{.} as the section name. Note - this -macro can now be called for uninitialized data items as well as -initialized data and functions. -@end table +modified name string in the @code{symbol_ref} (if one bit is not +enough information). +@end deftypefn + +@deftypefn {Target Hook} const char *TARGET_STRIP_NAME_ENCODING (const char *name) +Decode @var{name} and return the real name part, sans +the characters that @code{TARGET_ENCODE_SECTION_INFO} +may have added. +@end deftypefn + +@deftypefn {Target Hook} bool TARGET_IN_SMALL_DATA_P (tree @var{exp}) +Returns true if @var{exp} should be placed into a ``small data'' section. +The default version of this hook always returns false. +@end deftypefn + +@deftypevar {Target Hook} bool TARGET_HAVE_SRODATA_SECTION +Contains the value true if the target places read-only +``small data'' into a separate section. The default value is false. +@end deftypevar + +@deftypefn {Target Hook} bool TARGET_BINDS_LOCAL_P (tree @var{exp}) +Returns true if @var{exp} names an object for which name resolution +rules must resolve to the current ``module'' (dynamic shared library +or executable image). + +The default version of this hook implements the name resolution rules +for ELF, which has a looser model of global name binding than other +currently supported object file formats. +@end deftypefn + +@deftypevar {Target Hook} bool TARGET_HAVE_TLS +Contains the value true if the target supports thread-local storage. +The default value is false. +@end deftypevar + @node PIC @section Position Independent Code @@ -5966,26 +6326,18 @@ of @code{ASM_OUTPUT_DOUBLE} and the like: @findex REAL_VALUE_TO_TARGET_DOUBLE @findex REAL_VALUE_TO_TARGET_LONG_DOUBLE These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the target's -floating point representation, and store its bit pattern in the array of -@code{long int} whose address is @var{l}. The number of elements in the -output array is determined by the size of the desired target floating -point data type: 32 bits of it go in each @code{long int} array -element. Each array element holds 32 bits of the result, even if -@code{long int} is wider than 32 bits on the host machine. +floating point representation, and store its bit pattern in the variable +@var{l}. For @code{REAL_VALUE_TO_TARGET_SINGLE}, this variable should +be a simple @code{long int}. For the others, it should be an array of +@code{long int}. The number of elements in this array is determined by +the size of the desired target floating point data type: 32 bits of it +go in each @code{long int} array element. Each array element holds 32 +bits of the result, even if @code{long int} is wider than 32 bits on the +host machine. The array element values are designed so that you can print them out using @code{fprintf} in the order they should appear in the target machine's memory. - -@item REAL_VALUE_TO_DECIMAL (@var{x}, @var{format}, @var{string}) -@findex REAL_VALUE_TO_DECIMAL -This macro converts @var{x}, of type @code{REAL_VALUE_TYPE}, to a -decimal number and stores it as a string into @var{string}. -You must pass, as @var{string}, the address of a long enough block -of space to hold the result. - -The argument @var{format} is a @code{printf}-specification that serves -as a suggestion for how to format the output string. @end table @node Uninitialized Data @@ -6122,7 +6474,78 @@ A C statement (sans semicolon) to output to the stdio stream @var{stream} the assembler definition of a label named @var{name}. Use the expression @code{assemble_name (@var{stream}, @var{name})} to output the name itself; before and after that, output the additional -assembler syntax for defining the name, and a newline. +assembler syntax for defining the name, and a newline. A default +definition of this macro is provided which is correct for most systems. + +@findex SIZE_ASM_OP +@item SIZE_ASM_OP +A C string containing the appropriate assembler directive to specify the +size of a symbol, without any arguments. On systems that use ELF, the +default (in @file{config/elfos.h}) is @samp{"\t.size\t"}; on other +systems, the default is not to define this macro. + +Define this macro only if it is correct to use the default definitions +of @code{ASM_OUTPUT_SIZE_DIRECTIVE} and @code{ASM_OUTPUT_MEASURED_SIZE} +for your system. If you need your own custom definitions of those +macros, or if you do not need explicit symbol sizes at all, do not +define this macro. + +@findex ASM_OUTPUT_SIZE_DIRECTIVE +@item ASM_OUTPUT_SIZE_DIRECTIVE (@var{stream}, @var{name}, @var{size}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} a directive telling the assembler that the size of the +symbol @var{name} is @var{size}. @var{size} is a @code{HOST_WIDE_INT}. +If you define @code{SIZE_ASM_OP}, a default definition of this macro is +provided. + +@findex ASM_OUTPUT_MEASURED_SIZE +@item ASM_OUTPUT_MEASURED_SIZE (@var{stream}, @var{name}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} a directive telling the assembler to calculate the size of +the symbol @var{name} by subtracting its address from the current +address. + +If you define @code{SIZE_ASM_OP}, a default definition of this macro is +provided. The default assumes that the assembler recognizes a special +@samp{.} symbol as referring to the current address, and can calculate +the difference between this and another symbol. If your assembler does +not recognize @samp{.} or cannot do calculations with it, you will need +to redefine @code{ASM_OUTPUT_MEASURED_SIZE} to use some other technique. + +@findex TYPE_ASM_OP +@item TYPE_ASM_OP +A C string containing the appropriate assembler directive to specify the +type of a symbol, without any arguments. On systems that use ELF, the +default (in @file{config/elfos.h}) is @samp{"\t.type\t"}; on other +systems, the default is not to define this macro. + +Define this macro only if it is correct to use the default definition of +@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own +custom definition of this macro, or if you do not need explicit symbol +types at all, do not define this macro. + +@findex TYPE_OPERAND_FMT +@item TYPE_OPERAND_FMT +A C string which specifies (using @code{printf} syntax) the format of +the second operand to @code{TYPE_ASM_OP}. On systems that use ELF, the +default (in @file{config/elfos.h}) is @samp{"@@%s"}; on other systems, +the default is not to define this macro. + +Define this macro only if it is correct to use the default definition of +@code{ASM_OUTPUT_TYPE_DIRECTIVE} for your system. If you need your own +custom definition of this macro, or if you do not need explicit symbol +types at all, do not define this macro. + +@findex ASM_OUTPUT_TYPE_DIRECTIVE +@item ASM_OUTPUT_TYPE_DIRECTIVE (@var{stream}, @var{type}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} a directive telling the assembler that the type of the +symbol @var{name} is @var{type}. @var{type} is a C string; currently, +that string is always either @samp{"function"} or @samp{"object"}, but +you should not count on this. + +If you define @code{TYPE_ASM_OP} and @code{TYPE_OPERAND_FMT}, a default +definition of this macro is provided. @findex ASM_DECLARE_FUNCTION_NAME @item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) @@ -6136,6 +6559,9 @@ outputting the label definition (perhaps using If this macro is not defined, then the function name is defined in the usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). +You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} in the definition +of this macro. + @findex ASM_DECLARE_FUNCTION_SIZE @item ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl}) A C statement (sans semicolon) to output to the stdio stream @@ -6146,6 +6572,9 @@ representing the function. If this macro is not defined, then the function size is not defined. +You may wish to use @code{ASM_OUTPUT_MEASURED_SIZE} in the definition +of this macro. + @findex ASM_DECLARE_OBJECT_NAME @item ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl}) A C statement (sans semicolon) to output to the stdio stream @@ -6157,6 +6586,9 @@ label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument If this macro is not defined, then the variable name is defined in the usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). +You may wish to use @code{ASM_OUTPUT_TYPE_DIRECTIVE} and/or +@code{ASM_OUTPUT_SIZE_DIRECTIVE} in the definition of this macro. + @findex ASM_DECLARE_REGISTER_GLOBAL @item ASM_DECLARE_REGISTER_GLOBAL (@var{stream}, @var{decl}, @var{regno}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @@ -6177,15 +6609,20 @@ something about the size of the object. If you don't define this macro, that is equivalent to defining it to do nothing. -@findex ASM_GLOBALIZE_LABEL -@item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name}) -A C statement (sans semicolon) to output to the stdio stream +You may wish to use @code{ASM_OUTPUT_SIZE_DIRECTIVE} and/or +@code{ASM_OUTPUT_MEASURED_SIZE} in the definition of this macro. +@end table + +@deftypefn {Target Hook} void TARGET_ASM_GLOBALIZE_LABEL (FILE *@var{stream}, const char *@var{name}) +This target hook is a function to output to the stdio stream @var{stream} some commands that will make the label @var{name} global; -that is, available for reference from other files. Use the expression -@code{assemble_name (@var{stream}, @var{name})} to output the name -itself; before and after that, output the additional assembler syntax -for making that name global, and a newline. +that is, available for reference from other files. + +The default implementation relies on a proper definition of +@code{GLOBAL_ASM_OP}. +@end deftypefn +@table @code @findex ASM_WEAKEN_LABEL @item ASM_WEAKEN_LABEL (@var{stream}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @@ -6241,6 +6678,12 @@ you want to control one-only symbol support with a compiler flag, or if setting the @code{DECL_ONE_ONLY} flag is enough to mark a declaration to be emitted as one-only. +@deftypefn {Target Hook} void TARGET_ASM_ASSEMBLE_VISIBILITY (tree @var{decl}, const char *@var{visibility}) +This target hook is a function to output to @var{asm_out_file} some +commands that will make the symbol(s) associated with @var{decl} have +hidden, protected or internal visibility as specified by @var{visibility}. +@end deftypefn + @findex ASM_OUTPUT_EXTERNAL @item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name}) A C statement (sans semicolon) to output to the stdio stream @@ -6276,17 +6719,17 @@ A C statement (sans semicolon) to output a reference to @code{SYMBOL_REF} @var{sym}. If not defined, @code{assemble_name} will be used to output the name of the symbol. This macro may be used to modify the way a symbol is referenced depending on information -encoded by @code{ENCODE_SECTION_INFO}. +encoded by @code{TARGET_ENCODE_SECTION_INFO}. @findex ASM_OUTPUT_LABEL_REF @item ASM_OUTPUT_LABEL_REF (@var{stream}, @var{buf}) A C statement (sans semicolon) to output a reference to @var{buf}, the -result of ASM_GENERATE_INTERNAL_LABEL. If not defined, +result of @code{ASM_GENERATE_INTERNAL_LABEL}. If not defined, @code{assemble_name} will be used to output the name of the symbol. This macro is not used by @code{output_asm_label}, or the @code{%l} specifier that calls it; the intention is that this macro should be set -when it is necessary to output a label differently when its address -is being taken. +when it is necessary to output a label differently when its address is +being taken. @findex ASM_OUTPUT_INTERNAL_LABEL @item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) @@ -6322,17 +6765,6 @@ bundles. If this macro is not defined, then @code{ASM_OUTPUT_INTERNAL_LABEL} will be used. -@findex ASM_OUTPUT_ALTERNATE_LABEL_NAME -@item ASM_OUTPUT_ALTERNATE_LABEL_NAME (@var{stream}, @var{string}) -A C statement to output to the stdio stream @var{stream} the string -@var{string}. - -The default definition of this macro is as follows: - -@example -fprintf (@var{stream}, "%s:\n", LABEL_ALTERNATE_NAME (INSN)) -@end example - @findex ASM_GENERATE_INTERNAL_LABEL @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 @@ -6386,15 +6818,6 @@ to have the value of the tree node @var{decl_of_value}. This macro will be used in preference to @samp{ASM_OUTPUT_DEF} if it is defined and if the tree nodes are available. -@findex ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL -@item ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL (@var{stream}, @var{symbol}, @var{high}, @var{low}) -A C statement to output to the stdio stream @var{stream} assembler code -which defines (equates) the symbol @var{symbol} to have a value equal to -the difference of the two symbols @var{high} and @var{low}, -i.e.@: @var{high} minus @var{low}. GCC guarantees that the symbols @var{high} -and @var{low} are already known by the assembler so that the difference -resolves into a constant. - @findex SET_ASM_OP If @code{SET_ASM_OP} is defined, a default definition is provided which is correct for most systems. @@ -6513,7 +6936,7 @@ When arbitrary sections are available, there are two variants, depending upon how the code in @file{crtstuff.c} is called. On systems that support a @dfn{.init} section which is executed at program startup, parts of @file{crtstuff.c} are compiled into that section. The -program is linked by the @code{gcc} driver like this: +program is linked by the @command{gcc} driver like this: @example ld -o @var{output_file} crti.o crtbegin.o @dots{} -lgcc crtend.o crtn.o @@ -6832,10 +7255,10 @@ A C compound statement to output to stdio stream @var{stream} the assembler syntax for an instruction operand that is a memory reference whose address is @var{x}. @var{x} is an RTL expression. -@cindex @code{ENCODE_SECTION_INFO} usage +@cindex @code{TARGET_ENCODE_SECTION_INFO} usage On some machines, the syntax for a symbolic address depends on the -section that the address refers to. On these machines, define the macro -@code{ENCODE_SECTION_INFO} to store the information into the +section that the address refers to. On these machines, define the hook +@code{TARGET_ENCODE_SECTION_INFO} to store the information into the @code{symbol_ref}, and then check for it here. @xref{Assembler Format}. @findex DBR_OUTPUT_SEQEND @@ -7082,6 +7505,13 @@ is a function that outputs a standard GAS section directive, if directive followed by a synthetic label. @end deftypefn +@deftypevar {Target Hook} bool TARGET_TERMINATE_DW2_EH_FRAME_INFO +Contains the value true if the target should add a zero word onto the +end of a Dwarf-2 frame info section when used for exception handling. +Default value is false if @code{EH_FRAME_SECTION_NAME} is defined, and +true otherwise. +@end deftypevar + @node Alignment Output @subsection Assembler Commands for Alignment @@ -7174,6 +7604,11 @@ A C statement to output to the stdio stream @var{stream} an assembler command 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}. +@findex ASM_OUTPUT_ALIGN_WITH_NOP +@item ASM_OUTPUT_ALIGN_WITH_NOP (@var{stream}, @var{power}) +Like @code{ASM_OUTPUT_ALIGN}, except that the ``nop'' instruction is used +for padding, if necessary. + @findex ASM_OUTPUT_MAX_SKIP_ALIGN @item ASM_OUTPUT_MAX_SKIP_ALIGN (@var{stream}, @var{power}, @var{max_skip}) A C statement to output to the stdio stream @var{stream} an assembler @@ -7620,6 +8055,22 @@ Define this macro to be a nonzero value if the assembler can generate Dwarf 2 line debug info sections. This will result in much more compact line number tables, and hence is desirable if it works. +@findex ASM_OUTPUT_DWARF_DELTA +@item ASM_OUTPUT_DWARF_DELTA (@var{stream}, @var{size}, @var{label1}, @var{label2}) +A C statement to issue assembly directives that create a difference +between the two given labels, using an integer of the given size. + +@findex ASM_OUTPUT_DWARF_OFFSET +@item ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}) +A C statement to issue assembly directives that create a +section-relative reference to the given label, using an integer of the +given size. + +@findex ASM_OUTPUT_DWARF_PCREL +@item ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) +A C statement to issue assembly directives that create a self-relative +reference to the given label, using an integer of the given size. + @findex PUT_SDB_@dots{} @item PUT_SDB_@dots{} Define these macros to override the assembler syntax for the special @@ -7673,180 +8124,118 @@ behavior is controlled by @code{OPTIMIZATION_OPTIONS} and @code{OVERRIDE_OPTIONS}. @end table -@node Cross-compilation +@node Floating Point @section Cross Compilation and Floating Point @cindex cross compilation and floating point @cindex floating point and cross compilation -While all modern machines use 2's complement representation for integers, +While all modern machines use twos-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. -@findex atof 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). +range and precision, all floating point constants must be represented in +the target machine's format. Therefore, the cross compiler cannot +safely use the host machine's floating point arithmetic; it must emulate +the target's arithmetic. To ensure consistency, GCC always uses +emulation to work with floating point values, even when the host and +target floating point formats are identical. + +The following macros are provided by @file{real.h} for the compiler to +use. All parts of the compiler which generate or optimize +floating-point calculations must use these macros. They may evaluate +their operands more than once, so operands must not have side effects. + +@defmac REAL_VALUE_TYPE +The C data type to be used to hold a floating point value in the target +machine's format. Typically this is a @code{struct} containing an +array of @code{HOST_WIDE_INT}, but all code should treat it as an opaque +quantity. +@end defmac + +@deftypefn Macro int REAL_VALUES_EQUAL (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) +Compares for equality the two values, @var{x} and @var{y}. If the target +floating point format supports negative zeroes and/or NaNs, +@samp{REAL_VALUES_EQUAL (-0.0, 0.0)} is true, and +@samp{REAL_VALUES_EQUAL (NaN, NaN)} is false. +@end deftypefn -The macros in the following table should be defined only if you are cross -compiling between different floating point formats. +@deftypefn Macro int REAL_VALUES_LESS (REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) +Tests whether @var{x} is less than @var{y}. +@end deftypefn -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. +@deftypefn Macro HOST_WIDE_INT REAL_VALUE_FIX (REAL_VALUE_TYPE @var{x}) +Truncates @var{x} to a signed integer, rounding toward zero. +@end deftypefn -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. +@deftypefn Macro {unsigned HOST_WIDE_INT} REAL_VALUE_UNSIGNED_FIX (REAL_VALUE_TYPE @var{x}) +Truncates @var{x} to an unsigned integer, rounding toward zero. If +@var{x} is negative, returns zero. +@end deftypefn -@table @code -@findex REAL_VALUE_TYPE -@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}. - -@findex REAL_VALUES_EQUAL -@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}. - -@findex REAL_VALUES_LESS -@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. - -@findex REAL_VALUE_LDEXP -@findex ldexp -@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. - -@findex REAL_VALUE_FIX -@item REAL_VALUE_FIX (@var{x}) -A macro whose definition is a C expression to convert the target-machine -floating point value @var{x} to a signed integer. @var{x} has type -@code{REAL_VALUE_TYPE}. - -@findex REAL_VALUE_UNSIGNED_FIX -@item REAL_VALUE_UNSIGNED_FIX (@var{x}) -A macro whose definition is a C expression to convert the target-machine -floating point value @var{x} to an unsigned integer. @var{x} has type -@code{REAL_VALUE_TYPE}. - -@findex REAL_VALUE_RNDZINT -@item REAL_VALUE_RNDZINT (@var{x}) -A macro whose definition is a C expression to round the target-machine -floating point value @var{x} towards zero to an integer value (but still -as a floating point number). @var{x} has type @code{REAL_VALUE_TYPE}, -and so does the value. - -@findex REAL_VALUE_UNSIGNED_RNDZINT -@item REAL_VALUE_UNSIGNED_RNDZINT (@var{x}) -A macro whose definition is a C expression to round the target-machine -floating point value @var{x} towards zero to an unsigned integer value -(but still represented as a floating point number). @var{x} has type -@code{REAL_VALUE_TYPE}, and so does the value. - -@findex REAL_VALUE_ATOF -@item REAL_VALUE_ATOF (@var{string}, @var{mode}) -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 for mode @var{mode}. The value has type -@code{REAL_VALUE_TYPE}. - -@findex REAL_INFINITY -@item REAL_INFINITY -Define this macro if infinity is a possible floating point value, and -therefore division by 0 is legitimate. - -@findex REAL_VALUE_ISINF -@findex isinf -@item REAL_VALUE_ISINF (@var{x}) -A macro for a C expression which determines whether @var{x}, a floating -point value, is infinity. The value has type @code{int}. -By default, this is defined to call @code{isinf}. - -@findex REAL_VALUE_ISNAN -@findex isnan -@item REAL_VALUE_ISNAN (@var{x}) -A macro for a C expression which determines whether @var{x}, a floating -point value, is a ``nan'' (not-a-number). The value has type -@code{int}. By default, this is defined to call @code{isnan}. -@end table +@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ATOF (const char *@var{string}, enum machine_mode @var{mode}) +Converts @var{string} into a floating point number in the target machine's +representation for mode @var{mode}. This routine can handle both +decimal and hexadecimal floating point constants, using the syntax +defined by the C language for both. +@end deftypefn -@cindex constant folding and floating point -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. +@deftypefn Macro int REAL_VALUE_NEGATIVE (REAL_VALUE_TYPE @var{x}) +Returns 1 if @var{x} is negative (including negative zero), 0 otherwise. +@end deftypefn -@table @code -@findex REAL_ARITHMETIC -@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}. - -@cindex overflow while constant folding -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. - -@findex REAL_VALUE_NEGATE -@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. - -@findex REAL_VALUE_TRUNCATE -@item REAL_VALUE_TRUNCATE (@var{mode}, @var{x}) -A macro for a C expression which converts the floating point value -@var{x} to mode @var{mode}. - -Both @var{x} and the value of the expression are in the target machine's -floating point representation and have type @code{REAL_VALUE_TYPE}. -However, the value should have an appropriate bit pattern to be output -properly as a floating constant whose precision accords with mode -@var{mode}. +@deftypefn Macro int REAL_VALUE_ISINF (REAL_VALUE_TYPE @var{x}) +Determines whether @var{x} represents infinity (positive or negative). +@end deftypefn + +@deftypefn Macro int REAL_VALUE_ISNAN (REAL_VALUE_TYPE @var{x}) +Determines whether @var{x} represents a ``NaN'' (not-a-number). +@end deftypefn + +@deftypefn Macro void REAL_ARITHMETIC (REAL_VALUE_TYPE @var{output}, enum tree_code @var{code}, REAL_VALUE_TYPE @var{x}, REAL_VALUE_TYPE @var{y}) +Calculates an arithmetic operation on the two floating point values +@var{x} and @var{y}, storing the result in @var{output} (which must be a +variable). + +The operation to be performed is specified by @var{code}. Only the +following codes are supported: @code{PLUS_EXPR}, @code{MINUS_EXPR}, +@code{MULT_EXPR}, @code{RDIV_EXPR}, @code{MAX_EXPR}, @code{MIN_EXPR}. + +If @code{REAL_ARITHMETIC} is asked to evaluate division by zero and the +target's floating point format cannot represent infinity, it will call +@code{abort}. Callers should check for this situation first, using +@code{MODE_HAS_INFINITIES}. @xref{Storage Layout}. +@end deftypefn + +@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_NEGATE (REAL_VALUE_TYPE @var{x}) +Returns the negative of the floating point value @var{x}. +@end deftypefn -There is no way for this macro to report overflow. +@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_ABS (REAL_VALUE_TYPE @var{x}) +Returns the absolute value of @var{x}. +@end deftypefn -@findex REAL_VALUE_TO_INT -@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}. +@deftypefn Macro REAL_VALUE_TYPE REAL_VALUE_TRUNCATE (REAL_VALUE_TYPE @var{mode}, enum machine_mode @var{x}) +Truncates the floating point value @var{x} to fit in @var{mode}. The +return value is still a full-size @code{REAL_VALUE_TYPE}, but it has an +appropriate bit pattern to be output asa floating constant whose +precision accords with mode @var{mode}. +@end deftypefn + +@deftypefn Macro void REAL_VALUE_TO_INT (HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, REAL_VALUE_TYPE @var{x}) +Converts a floating point value @var{x} into a double-precision integer +which is then stored into @var{low} and @var{high}. If the value is not +integral, it is truncated. +@end deftypefn -@item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high}, @var{mode}) +@deftypefn Macro void REAL_VALUE_FROM_INT (REAL_VALUE_TYPE @var{x}, HOST_WIDE_INT @var{low}, HOST_WIDE_INT @var{high}, enum machine_mode @var{mode}) @findex REAL_VALUE_FROM_INT -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}. -The value is in the target machine's representation for mode @var{mode} -and has the type @code{REAL_VALUE_TYPE}. -@end table +Converts a double-precision integer found in @var{low} and @var{high}, +into a floating point value which is then stored into @var{x}. The +value is truncated to fit in mode @var{mode}. +@end deftypefn @node Mode Switching @section Mode Switching Instructions @@ -7997,6 +8386,50 @@ attributes, @code{false} otherwise. By default, if a function has a target specific attribute attached to it, it will not be inlined. @end deftypefn +@node MIPS Coprocessors +@section Defining coprocessor specifics for MIPS targets. +@cindex MIPS coprocessor-definition macros + +The MIPS specification allows MIPS implementations to have as many as 4 +coprocessors, each with as many as 32 private registers. gcc supports +accessing these registers and transferring values between the registers +and memory using asm-ized variables. For example: + +@smallexample + register unsigned int cp0count asm ("c0r1"); + unsigned int d; + + d = cp0count + 3; +@end smallexample + +(``c0r1'' is the default name of register 1 in coprocessor 0; alternate +names may be added as described below, or the default names may be +overridden entirely in @code{SUBTARGET_CONDITIONAL_REGISTER_USAGE}.) + +Coprocessor registers are assumed to be epilogue-used; sets to them will +be preserved even if it does not appear that the register is used again +later in the function. + +Another note: according to the MIPS spec, coprocessor 1 (if present) is +the FPU. One accesses COP1 registers through standard mips +floating-point support; they are not included in this mechanism. + +There is one macro used in defining the MIPS coprocessor interface which +you may want to override in subtargets; it is described below. + +@table @code + +@item ALL_COP_ADDITIONAL_REGISTER_NAMES +@findex ALL_COP_ADDITIONAL_REGISTER_NAMES +A comma-separated list (with leading comma) of pairs describing the +alternate names of coprocessor registers. The format of each entry should be +@smallexample +@{ @var{alternatename}, @var{register_number}@} +@end smallexample +Default: empty. + +@end table + @node Misc @section Miscellaneous Parameters @cindex parameters, miscellaneous @@ -8059,7 +8492,7 @@ elements of a jump-table should have. Optional: return the preferred mode for an @code{addr_diff_vec} when the minimum and maximum offset are known. If you define this, it enables extra code in branch shortening to deal with @code{addr_diff_vec}. -To make this work, you also have to define INSN_ALIGN and +To make this work, you also have to define @code{INSN_ALIGN} and make the alignment for @code{addr_diff_vec} explicit. The @var{body} argument is provided so that the offset_unsigned and scale flags can be updated. @@ -8316,11 +8749,6 @@ Defining @code{STDC_0_IN_SYSTEM_HEADERS} makes GNU CPP follows the host convention when processing system header files, but when processing user files @code{__STDC__} will always expand to 1. -@findex SCCS_DIRECTIVE -@item SCCS_DIRECTIVE -Define this if the preprocessor should ignore @code{#sccs} directives -and print no error message. - @findex NO_IMPLICIT_EXTERN_C @item NO_IMPLICIT_EXTERN_C Define this macro if the system header files support C++ as well as C@. @@ -8401,6 +8829,21 @@ within a structure, in much the same way as the @samp{__aligned__} and @samp{__packed__} @code{__attribute__}s do. A pack value of zero resets the behavior to the default. +A subtlety for Microsoft Visual C/C++ style bit-field packing +(e.g. -mms-bitfields) for targets that support it: +When a bit-field is inserted into a packed record, the whole size +of the underlying type is used by one or more same-size adjacent +bit-fields (that is, if its long:3, 32 bits is used in the record, +and any additional adjacent long bit-fields are packed into the same +chunk of 32 bits. However, if the size changes, a new field of that +size is allocated). + +If both MS bit-fields and @samp{__attribute__((packed))} are used, +the latter will take precedence. If @samp{__attribute__((packed))} is +used on a single field when MS bit-fields are in use, it will take +precedence for that field, but the alignment of the rest of the structure +may affect its placement. + The weak pragma only works if @code{SUPPORTS_WEAK} and @code{ASM_WEAKEN_LABEL} are defined. If enabled it allows the creation of specifically named weak labels, optionally with a value. @@ -8561,29 +9004,54 @@ conditional execution instructions instead of a branch. A value of 1 if it does use cc0. @findex IFCVT_MODIFY_TESTS -@item IFCVT_MODIFY_TESTS -A C expression to modify the tests in @code{TRUE_EXPR}, and -@code{FALSE_EXPR} for use in converting insns in @code{TEST_BB}, -@code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB} basic blocks to -conditional execution. Set either @code{TRUE_EXPR} or @code{FALSE_EXPR} -to a null pointer if the tests cannot be converted. +@item IFCVT_MODIFY_TESTS(@var{ce_info}, @var{true_expr}, @var{false_expr}) +Used if the target needs to perform machine-dependent modifications on the +conditionals used for turning basic blocks into conditionally executed code. +@var{ce_info} points to a data structure, @code{struct ce_if_block}, which +contains information about the currently processed blocks. @var{true_expr} +and @var{false_expr} are the tests that are used for converting the +then-block and the else-block, respectively. Set either @var{true_expr} or +@var{false_expr} to a null pointer if the tests cannot be converted. + +@findex IFCVT_MODIFY_MULTIPLE_TESTS +@item IFCVT_MODIFY_MULTIPLE_TESTS(@var{ce_info}, @var{bb}, @var{true_expr}, @var{false_expr}) +Like @code{IFCVT_MODIFY_TESTS}, but used when converting more complicated +if-statements into conditions combined by @code{and} and @code{or} operations. +@var{bb} contains the basic block that contains the test that is currently +being processed and about to be turned into a condition. @findex IFCVT_MODIFY_INSN -@item IFCVT_MODIFY_INSN -A C expression to modify the @code{PATTERN} of an @code{INSN} that is to -be converted to conditional execution format. +@item IFCVT_MODIFY_INSN(@var{ce_info}, @var{pattern}, @var{insn}) +A C expression to modify the @var{PATTERN} of an @var{INSN} that is to +be converted to conditional execution format. @var{ce_info} points to +a data structure, @code{struct ce_if_block}, which contains information +about the currently processed blocks. @findex IFCVT_MODIFY_FINAL -@item IFCVT_MODIFY_FINAL +@item IFCVT_MODIFY_FINAL(@var{ce_info}) A C expression to perform any final machine dependent modifications in -converting code to conditional execution in the basic blocks -@code{TEST_BB}, @code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB}. +converting code to conditional execution. The involved basic blocks +can be found in the @code{struct ce_if_block} structure that is pointed +to by @var{ce_info}. @findex IFCVT_MODIFY_CANCEL -@item IFCVT_MODIFY_CANCEL +@item IFCVT_MODIFY_CANCEL(@var{ce_info}) A C expression to cancel any machine dependent modifications in -converting code to conditional execution in the basic blocks -@code{TEST_BB}, @code{THEN_BB}, @code{ELSE_BB}, and @code{JOIN_BB}. +converting code to conditional execution. The involved basic blocks +can be found in the @code{struct ce_if_block} structure that is pointed +to by @var{ce_info}. + +@findex IFCVT_INIT_EXTRA_FIELDS +@item IFCVT_INIT_EXTRA_FIELDS(@var{ce_info}) +A C expression to initialize any extra fields in a @code{struct ce_if_block} +structure, which are defined by the @code{IFCVT_EXTRA_FIELDS} macro. + +@findex IFCVT_EXTRA_FIELDS +@item IFCVT_EXTRA_FIELDS +If defined, it should expand to a set of field declarations that will be +added to the @code{struct ce_if_block} structure. These should be initialized +by the @code{IFCVT_INIT_EXTRA_FIELDS} macro. + @end table @deftypefn {Target Hook} void TARGET_INIT_BUILTINS () @@ -8668,6 +9136,22 @@ Define this macro for systems like AIX, where the linker discards object files that are not referenced from @code{main} and uses export lists. +@findex MODIFY_JNI_METHOD_CALL +@item MODIFY_JNI_METHOD_CALL (@var{mdecl}) +Define this macro to a C expression representing a variant of the +method call @var{mdecl}, if Java Native Interface (JNI) methods +must be invoked differently from other methods on your target. +For example, on 32-bit Windows, JNI methods must be invoked using +the @code{stdcall} calling convention and this macro is then +defined as this expression: + +@smallexample +build_type_attribute_variant (@var{mdecl}, + build_tree_list + (get_identifier ("stdcall"), + NULL)) +@end smallexample + @end table @deftypefn {Target Hook} bool TARGET_CANNOT_MODIFY_JUMPS_P (void) diff --git a/contrib/gcc/doc/trouble.texi b/contrib/gcc/doc/trouble.texi index 4cfef9f..4a8f0c3 100644 --- a/contrib/gcc/doc/trouble.texi +++ b/contrib/gcc/doc/trouble.texi @@ -163,7 +163,7 @@ Naturally, this does not happen when you use GCC@. You must specify all three options explicitly. @item -On a Sparc, GCC aligns all values of type @code{double} on an 8-byte +On a SPARC, GCC aligns all values of type @code{double} on an 8-byte boundary, and it expects every @code{double} to be so aligned. The Sun compiler usually gives @code{double} values 8-byte alignment, with one exception: function arguments of type @code{double} may not be aligned. @@ -202,7 +202,7 @@ Storing into the pointer can be done likewise with the same union. @item On Solaris, the @code{malloc} function in the @file{libmalloc.a} library may allocate memory that is only 4 byte aligned. Since GCC on the -Sparc assumes that doubles are 8 byte aligned, this may result in a +SPARC assumes that doubles are 8 byte aligned, this may result in a fatal signal if doubles are stored in memory allocated by the @file{libmalloc.a} library. @@ -219,7 +219,7 @@ when linking, compile and link against the file @file{mit/util/misc/dlsym.c} from the MIT version of X windows. @item -The 128-bit long double format that the Sparc port supports currently +The 128-bit long double format that the SPARC port supports currently works by using the architecturally defined quad-word floating point instructions. Since there is no hardware that supports these instructions they must be emulated by the operating system. Long @@ -338,47 +338,6 @@ you cannot successfully use @samp{$} in identifiers on the RS/6000 due to a restriction in the IBM assembler. GAS supports these identifiers. -@item -@opindex mno-serialize-volatile -There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that -occurs when the @samp{fldcr} instruction is used. GCC uses -@samp{fldcr} on the 88100 to serialize volatile memory references. Use -the option @option{-mno-serialize-volatile} if your version of the -assembler has this bug. - -@item -On VMS, GAS versions 1.38.1 and earlier may cause spurious warning -messages from the linker. These warning messages complain of mismatched -psect attributes. You can ignore them. - -@item -On NewsOS version 3, if you include both of the files @file{stddef.h} -and @file{sys/types.h}, you get an error because there are two typedefs -of @code{size_t}. You should change @file{sys/types.h} by adding these -lines around the definition of @code{size_t}: - -@smallexample -#ifndef _SIZE_T -#define _SIZE_T -@var{actual-typedef-here} -#endif -@end smallexample - -@cindex Alliant -@item -On the Alliant, the system's own convention for returning structures -and unions is unusual, and is not compatible with GCC no matter -what options are used. - -@cindex RT PC -@cindex IBM RT PC -@item -@opindex mhc-struct-return -On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different -convention for structure and union returning. Use the option -@option{-mhc-struct-return} to tell GCC to use a convention compatible -with it. - @cindex VAX calling convention @cindex Ultrix calling convention @item @@ -395,42 +354,10 @@ these options to produce code compatible with the Fortran compiler: @end smallexample @item -On the WE32k, you may find that programs compiled with GCC do not -work with the standard shared C library. You may need to link with -the ordinary C compiler. If you do so, you must specify the following -options: - -@smallexample --L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s -@end smallexample - -The first specifies where to find the library @file{libgcc.a} -specified with the @option{-lgcc} option. - -GCC does linking by invoking @command{ld}, just as @command{cc} does, and -there is no reason why it @emph{should} matter which compilation program -you use to invoke @command{ld}. If someone tracks this problem down, -it can probably be fixed easily. - -@item On the Alpha, you may get assembler errors about invalid syntax as a result of floating point constants. This is due to a bug in the C library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid floating point numbers, they sometimes print @samp{NaN}. - -@item -On Irix 4.0.5F (and perhaps in some other versions), an assembler bug -sometimes reorders instructions incorrectly when optimization is turned -on. If you think this may be happening to you, try using the GNU -assembler; GAS version 2.1 supports ECOFF on Irix. - -@opindex noasmopt -Or use the @option{-noasmopt} option when you compile GCC with itself, -and then again when you compile your program. (This is a temporary -kludge to turn off assembler optimization on Irix.) If this proves to -be what you need, edit the assembler spec in the file @file{specs} so -that it unconditionally passes @option{-O0} to the assembler, and never -passes @option{-O2} or @option{-O3}. @end itemize @node External Bugs @@ -445,8 +372,7 @@ Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2 because of problems in DEC's versions of the X11 header files @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding @option{-I/usr/include/mit} to use the MIT versions of the header files, -using the @option{-traditional} switch to turn off ISO C, or fixing the -header files by adding this: +or fixing the header files by adding this: @example #ifdef __STDC__ @@ -486,9 +412,7 @@ MALLOC=gmalloc.o @opindex traditional There are several noteworthy incompatibilities between GNU C and K&R -(non-ISO) versions of C@. The @option{-traditional} option -eliminates many of these incompatibilities, @emph{but not all}, by -telling GCC to behave like a K&R C compiler. +(non-ISO) versions of C@. @itemize @bullet @cindex string constants @@ -518,7 +442,6 @@ The best solution to these problems is to change the program to use purposes instead of string constants. But if this is not possible, you can use the @option{-fwritable-strings} flag, which directs GCC to handle string constants the same way most C compilers do. -@option{-traditional} also has this effect, among others. @item @code{-2147483648} is positive. @@ -538,9 +461,6 @@ string constants. For example, the following macro in GCC @noindent will produce output @code{"a"} regardless of what the argument @var{a} is. -The @option{-traditional} option directs GCC to handle such cases -(among others) in the old-fashioned (non-ISO) fashion. - @cindex @code{setjmp} incompatibilities @cindex @code{longjmp} incompatibilities @item @@ -575,11 +495,6 @@ in it. If you use the @option{-W} option with the @option{-O} option, you will get a warning when GCC thinks such a problem might be possible. -The @option{-traditional} option directs GCC 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 Programs that use preprocessing directives in the middle of macro arguments do not work with GCC@. For example, a program like this @@ -593,9 +508,7 @@ foobar ( @end group @end example -ISO C does not permit such a construct. It would make sense to support -it when @option{-traditional} is used, but it is too much work to -implement. +ISO C does not permit such a construct. @item K&R compilers allow comments to cross over an inclusion boundary @@ -613,9 +526,6 @@ have the same scope as any other declaration in the same place. In some other C compilers, a @code{extern} declaration affects all the rest of the file even if it happens within a block. -The @option{-traditional} option directs GCC to treat all @code{extern} -declarations as global, like traditional compilers. - @item In traditional C, you can combine @code{long}, etc., with a typedef name, as shown here: @@ -626,18 +536,15 @@ typedef long foo bar; @end example In ISO C, this is not allowed: @code{long} and other type modifiers -require an explicit @code{int}. Because this criterion is expressed -by Bison grammar rules rather than C code, the @option{-traditional} -flag cannot alter it. +require an explicit @code{int}. @cindex typedef names as function parameters @item -PCC allows typedef names to be used as function parameters. The -difficulty described immediately above applies here too. +PCC allows typedef names to be used as function parameters. @item -When in @option{-traditional} mode, GCC allows the following erroneous -pair of declarations to appear together in a given scope: +Traditional C allows the following erroneous pair of declarations to +appear together in a given scope: @example typedef int foo; @@ -645,19 +552,18 @@ typedef foo foo; @end example @item -GCC treats all characters of identifiers as significant, even when in -@option{-traditional} mode. According to K&R-1 (2.2), ``No more than the -first eight characters are significant, although more may be used.''. -Also according to K&R-1 (2.2), ``An identifier is a sequence of letters -and digits; the first character must be a letter. The underscore _ -counts as a letter.'', but GCC also allows dollar signs in identifiers. +GCC treats all characters of identifiers as significant. According to +K&R-1 (2.2), ``No more than the first eight characters are significant, +although more may be used.''. Also according to K&R-1 (2.2), ``An +identifier is a sequence of letters and digits; the first character must +be a letter. The underscore _ counts as a letter.'', but GCC also +allows dollar signs in identifiers. @cindex whitespace @item PCC allows whitespace in the middle of compound assignment operators such as @samp{+=}. GCC, following the ISO standard, does not -allow this. The difficulty described immediately above applies here -too. +allow this. @cindex apostrophes @cindex ' @@ -675,8 +581,7 @@ You can't expect this to work. @end example The best solution to such a problem is to put the text into an actual -C comment delimited by @samp{/*@dots{}*/}. However, -@option{-traditional} suppresses these error messages. +C comment delimited by @samp{/*@dots{}*/}. @item Many user programs contain the declaration @samp{long time ();}. In the @@ -916,27 +821,20 @@ You can partially avoid this problem by using the @option{-ffloat-store} option (@pxref{Optimize Options}). @item -On the MIPS, variable argument functions using @file{varargs.h} -cannot have a floating point value for the first argument. The -reason for this is that in the absence of a prototype in scope, -if the first argument is a floating point, it is passed in a -floating point register, rather than an integer register. - -If the code is rewritten to use the ISO standard @file{stdarg.h} -method of variable arguments, and the prototype is in scope at -the time of the call, everything will work fine. - -@item -On the H8/300 and H8/300H, variable argument functions must be -implemented using the ISO standard @file{stdarg.h} method of -variable arguments. Furthermore, calls to functions using @file{stdarg.h} -variable arguments must have a prototype for the called function -in scope at the time of the call. - -@item On AIX and other platforms without weak symbol support, templates need to be instantiated explicitly and symbols for static members of templates will not be generated. + +@item +On AIX, GCC scans object files and library archives for static +constructors and destructors when linking an application before the +linker prunes unreferenced symbols. This is necessary to prevent the +AIX linker from mistakenly assuming that static constructor or +destructor are unused and removing them before the scanning can occur. +All static constructors and destructors found will be referenced even +though the modules in which they occur may not be used by the program. +This may lead to both increased executable size and unexpected symbol +references. @end itemize @node C++ Misunderstandings @@ -988,9 +886,9 @@ int Foo::bar = 0; @end example Other C++ compilers may not correctly implement the standard behavior. -As a result, when you switch to @code{g++} from one of these compilers, +As a result, when you switch to @command{g++} from one of these compilers, you may discover that a program that appeared to work correctly in fact -does not conform to the standard: @code{g++} reports as undefined +does not conform to the standard: @command{g++} reports as undefined symbols any static data members that lack definitions. @node Temporaries @@ -1298,12 +1196,11 @@ they write programs which have the same meaning in both C dialects.) @item @opindex ansi -@opindex traditional @opindex std Undefining @code{__STDC__} when @option{-ansi} is not used. -Currently, GCC defines @code{__STDC__} as long as you don't use -@option{-traditional}. This provides good results in practice. +Currently, GCC defines @code{__STDC__} unconditionally. This provides +good results in practice. Programmers normally use conditionals on @code{__STDC__} to ask whether it is safe to use certain features of ISO C, such as function |
