diff options
author | ache <ache@FreeBSD.org> | 1995-01-22 21:54:49 +0000 |
---|---|---|
committer | ache <ache@FreeBSD.org> | 1995-01-22 21:54:49 +0000 |
commit | a45b3b018f2b98c44e177733bee1eee74cabb2a3 (patch) | |
tree | a2ef9aefa2554a7da6bf61e5b9572ad48b3aea3f /gnu/usr.bin | |
parent | bb1df6868cd5d855e210222b5bd61e85a90c0614 (diff) | |
download | FreeBSD-src-a45b3b018f2b98c44e177733bee1eee74cabb2a3.zip FreeBSD-src-a45b3b018f2b98c44e177733bee1eee74cabb2a3.tar.gz |
Add missing infopages
Diffstat (limited to 'gnu/usr.bin')
-rw-r--r-- | gnu/usr.bin/cc/doc/Makefile | 3 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/cpp.texi | 2807 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/extend.texi | 2919 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/gcc.texi | 4525 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/gpcompare.texi | 236 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/gxxint.texi | 1271 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/install.texi | 2086 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/invoke.texi | 4207 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/md.texi | 3965 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/reno.texi | 752 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/rtl.texi | 2800 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/templates.texi | 235 | ||||
-rw-r--r-- | gnu/usr.bin/cc/doc/tm.texi | 6337 |
13 files changed, 32143 insertions, 0 deletions
diff --git a/gnu/usr.bin/cc/doc/Makefile b/gnu/usr.bin/cc/doc/Makefile new file mode 100644 index 0000000..f0587fd --- /dev/null +++ b/gnu/usr.bin/cc/doc/Makefile @@ -0,0 +1,3 @@ +INFO = gcc cpp reno gxxint + +.include <bsd.info.mk> diff --git a/gnu/usr.bin/cc/doc/cpp.texi b/gnu/usr.bin/cc/doc/cpp.texi new file mode 100644 index 0000000..b1b19dc --- /dev/null +++ b/gnu/usr.bin/cc/doc/cpp.texi @@ -0,0 +1,2807 @@ +\input texinfo +@setfilename cpp.info +@settitle The C Preprocessor + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* Cpp: (cpp). The C preprocessor. +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ignore + +@c @smallbook +@c @cropmarks +@c @finalout +@setchapternewpage odd +@ifinfo +This file documents the GNU C Preprocessor. + +Copyright 1987, 1989, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@titlepage +@c @finalout +@title The C Preprocessor +@subtitle Last revised July 1992 +@subtitle for GCC version 2 +@author Richard M. Stallman +@page +@vskip 2pc +This booklet is eventually intended to form the first chapter of a GNU +C Language manual. + +@vskip 0pt plus 1filll +Copyright @copyright{} 1987, 1989, 1991, 1992, 1994 Free Software +Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage +@page + +@node Top, Global Actions,, (DIR) +@chapter The C Preprocessor + +The C preprocessor is a @dfn{macro processor} that is used automatically by +the C compiler to transform your program before actual compilation. It is +called a macro processor because it allows you to define @dfn{macros}, +which are brief abbreviations for longer constructs. + +The C preprocessor provides four separate facilities that you can use as +you see fit: + +@itemize @bullet +@item +Inclusion of header files. These are files of declarations that can be +substituted into your program. + +@item +Macro expansion. You can define @dfn{macros}, which are abbreviations +for arbitrary fragments of C code, and then the C preprocessor will +replace the macros with their definitions throughout the program. + +@item +Conditional compilation. Using special preprocessor commands, you +can include or exclude parts of the program according to various +conditions. + +@item +Line control. If you use a program to combine or rearrange source files into +an intermediate file which is then compiled, you can use line control +to inform the compiler of where each source line originally came from. +@end itemize + +C preprocessors vary in some details. This manual discusses the GNU C +preprocessor, the C Compatible Compiler Preprocessor. The GNU C +preprocessor provides a superset of the features of ANSI Standard C. + +ANSI Standard C requires the rejection of many harmless constructs commonly +used by today's C programs. Such incompatibility would be inconvenient for +users, so the GNU C preprocessor is configured to accept these constructs +by default. Strictly speaking, to get ANSI Standard C, you must use the +options @samp{-trigraphs}, @samp{-undef} and @samp{-pedantic}, but in +practice the consequences of having strict ANSI Standard C make it +undesirable to do this. @xref{Invocation}. + +@menu +* Global Actions:: Actions made uniformly on all input files. +* Commands:: General syntax of preprocessor commands. +* Header Files:: How and why to use header files. +* Macros:: How and why to use macros. +* Conditionals:: How and why to use conditionals. +* Combining Sources:: Use of line control when you combine source files. +* Other Commands:: Miscellaneous preprocessor commands. +* Output:: Format of output from the C preprocessor. +* Invocation:: How to invoke the preprocessor; command options. +* Concept Index:: Index of concepts and terms. +* Index:: Index of commands, predefined macros and options. +@end menu + +@node Global Actions, Commands, Top, Top +@section Transformations Made Globally + +Most C preprocessor features are inactive unless you give specific commands +to request their use. (Preprocessor commands are lines starting with +@samp{#}; @pxref{Commands}). But there are three transformations that the +preprocessor always makes on all the input it receives, even in the absence +of commands. + +@itemize @bullet +@item +All C comments are replaced with single spaces. + +@item +Backslash-Newline sequences are deleted, no matter where. This +feature allows you to break long lines for cosmetic purposes without +changing their meaning. + +@item +Predefined macro names are replaced with their expansions +(@pxref{Predefined}). +@end itemize + +The first two transformations are done @emph{before} nearly all other parsing +and before preprocessor commands are recognized. Thus, for example, you +can split a line cosmetically with Backslash-Newline anywhere (except +when trigraphs are in use; see below). + +@example +/* +*/ # /* +*/ defi\ +ne FO\ +O 10\ +20 +@end example + +@noindent +is equivalent into @samp{#define FOO 1020}. You can split even an escape +sequence with Backslash-Newline. For example, you can split @code{"foo\bar"} +between the @samp{\} and the @samp{b} to get + +@example +"foo\\ +bar" +@end example + +@noindent +This behavior is unclean: in all other contexts, a Backslash can be +inserted in a string constant as an ordinary character by writing a double +Backslash, and this creates an exception. But the ANSI C standard requires +it. (Strict ANSI C does not allow Newlines in string constants, so they +do not consider this a problem.) + +But there are a few exceptions to all three transformations. + +@itemize @bullet +@item +C comments and predefined macro names are not recognized inside a +@samp{#include} command in which the file name is delimited with +@samp{<} and @samp{>}. + +@item +C comments and predefined macro names are never recognized within a +character or string constant. (Strictly speaking, this is the rule, +not an exception, but it is worth noting here anyway.) + +@item +Backslash-Newline may not safely be used within an ANSI ``trigraph''. +Trigraphs are converted before Backslash-Newline is deleted. If you +write what looks like a trigraph with a Backslash-Newline inside, the +Backslash-Newline is deleted as usual, but it is then too late to +recognize the trigraph. + +This exception is relevant only if you use the @samp{-trigraphs} +option to enable trigraph processing. @xref{Invocation}. +@end itemize + +@node Commands, Header Files, Global Actions, Top +@section Preprocessor Commands + +@cindex preprocessor commands +@cindex commands +Most preprocessor features are active only if you use preprocessor commands +to request their use. + +Preprocessor commands are lines in your program that start with @samp{#}. +The @samp{#} is followed by an identifier that is the @dfn{command name}. +For example, @samp{#define} is the command that defines a macro. +Whitespace is also allowed before and after the @samp{#}. + +The set of valid command names is fixed. Programs cannot define new +preprocessor commands. + +Some command names require arguments; these make up the rest of the command +line and must be separated from the command name by whitespace. For example, +@samp{#define} must be followed by a macro name and the intended expansion +of the macro. @xref{Simple Macros}. + +A preprocessor command cannot be more than one line in normal circumstances. +It may be split cosmetically with Backslash-Newline, but that has no effect +on its meaning. Comments containing Newlines can also divide the command into +multiple lines, but the comments are changed to Spaces before the command +is interpreted. The only way a significant Newline can occur in a preprocessor +command is within a string constant or character constant. Note that +most C compilers that might be applied to the output from the preprocessor +do not accept string or character constants containing Newlines. + +The @samp{#} and the command name cannot come from a macro expansion. For +example, if @samp{foo} is defined as a macro expanding to @samp{define}, +that does not make @samp{#foo} a valid preprocessor command. + +@node Header Files, Macros, Commands, Top +@section Header Files + +@cindex header file +A header file is a file containing C declarations and macro definitions +(@pxref{Macros}) to be shared between several source files. You request +the use of a header file in your program with the C preprocessor command +@samp{#include}. + +@menu +* Header Uses:: What header files are used for. +* Include Syntax:: How to write @samp{#include} commands. +* Include Operation:: What @samp{#include} does. +* Once-Only:: Preventing multiple inclusion of one header file. +* Inheritance:: Including one header file in another header file. +@end menu + +@node Header Uses, Include Syntax, Header Files, Header Files +@subsection Uses of Header Files + +Header files serve two kinds of purposes. + +@itemize @bullet +@item +@findex system header files +System header files declare the interfaces to parts of the operating +system. You include them in your program to supply the definitions and +declarations you need to invoke system calls and libraries. + +@item +Your own header files contain declarations for interfaces between the +source files of your program. Each time you have a group of related +declarations and macro definitions all or most of which are needed in +several different source files, it is a good idea to create a header +file for them. +@end itemize + +Including a header file produces the same results in C compilation as +copying the header file into each source file that needs it. But such +copying would be time-consuming and error-prone. With a header file, the +related declarations appear in only one place. If they need to be changed, +they can be changed in one place, and programs that include the header file +will automatically use the new version when next recompiled. The header +file eliminates the labor of finding and changing all the copies as well as +the risk that a failure to find one copy will result in inconsistencies +within a program. + +The usual convention is to give header files names that end with +@file{.h}. Avoid unusual characters in header file names, as they +reduce portability. + +@node Include Syntax, Include Operation, Header Uses, Header Files +@subsection The @samp{#include} Command + +@findex #include +Both user and system header files are included using the preprocessor +command @samp{#include}. It has three variants: + +@table @code +@item #include <@var{file}> +This variant is used for system header files. It searches for a file +named @var{file} in a list of directories specified by you, then in a +standard list of system directories. You specify directories to +search for header files with the command option @samp{-I} +(@pxref{Invocation}). The option @samp{-nostdinc} inhibits searching +the standard system directories; in this case only the directories +you specify are searched. + +The parsing of this form of @samp{#include} is slightly special +because comments are not recognized within the @samp{<@dots{}>}. +Thus, in @samp{#include <x/*y>} the @samp{/*} does not start a comment +and the command specifies inclusion of a system header file named +@file{x/*y}. Of course, a header file with such a name is unlikely to +exist on Unix, where shell wildcard features would make it hard to +manipulate.@refill + +The argument @var{file} may not contain a @samp{>} character. It may, +however, contain a @samp{<} character. + +@item #include "@var{file}" +This variant is used for header files of your own program. It +searches for a file named @var{file} first in the current directory, +then in the same directories used for system header files. The +current directory is the directory of the current input file. It is +tried first because it is presumed to be the location of the files +that the current input file refers to. (If the @samp{-I-} option is +used, the special treatment of the current directory is inhibited.) + +The argument @var{file} may not contain @samp{"} characters. If +backslashes occur within @var{file}, they are considered ordinary text +characters, not escape characters. None of the character escape +sequences appropriate to string constants in C are processed. Thus, +@samp{#include "x\n\\y"} specifies a filename containing three +backslashes. It is not clear why this behavior is ever useful, but +the ANSI standard specifies it. + +@item #include @var{anything else} +@cindex computed @samp{#include} +This variant is called a @dfn{computed #include}. Any @samp{#include} +command whose argument does not fit the above two forms is a computed +include. The text @var{anything else} is checked for macro calls, +which are expanded (@pxref{Macros}). When this is done, the result +must fit one of the above two variants---in particular, the expanded +text must in the end be surrounded by either quotes or angle braces. + +This feature allows you to define a macro which controls the file name +to be used at a later point in the program. One application of this is +to allow a site-specific configuration file for your program to specify +the names of the system include files to be used. This can help in +porting the program to various operating systems in which the necessary +system header files are found in different places. +@end table + +@node Include Operation, Once-Only, Include Syntax, Header Files +@subsection How @samp{#include} Works + +The @samp{#include} command works by directing the C preprocessor to scan +the specified file as input before continuing with the rest of the current +file. The output from the preprocessor contains the output already +generated, followed by the output resulting from the included file, +followed by the output that comes from the text after the @samp{#include} +command. For example, given a header file @file{header.h} as follows, + +@example +char *test (); +@end example + +@noindent +and a main program called @file{program.c} that uses the header file, +like this, + +@example +int x; +#include "header.h" + +main () +@{ + printf (test ()); +@} +@end example + +@noindent +the output generated by the C preprocessor for @file{program.c} as input +would be + +@example +int x; +char *test (); + +main () +@{ + printf (test ()); +@} +@end example + +Included files are not limited to declarations and macro definitions; 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. + +It is possible for a header file to begin or end a syntactic unit such +as a function definition, but that would be very confusing, so don't do +it. + +The line following the @samp{#include} command is always treated as a +separate line by the C preprocessor even if the included file lacks a final +newline. + +@node Once-Only, Inheritance, Include Operation, Header Files +@subsection Once-Only Include Files +@cindex repeated inclusion +@cindex including just once + +Very often, one header file includes another. It can easily result that a +certain header file is included more than once. This may lead to errors, +if the header file defines structure types or typedefs, and is certainly +wasteful. Therefore, we often wish to prevent multiple inclusion of a +header file. + +The standard way to do this is to enclose the entire real contents of the +file in a conditional, like this: + +@example +#ifndef FILE_FOO_SEEN +#define FILE_FOO_SEEN + +@var{the entire file} + +#endif /* FILE_FOO_SEEN */ +@end example + +The macro @code{FILE_FOO_SEEN} indicates that the file has been included +once already. In a user header file, the macro name should not begin +with @samp{_}. In a system header file, this name should begin with +@samp{__} to avoid conflicts with user programs. In any kind of header +file, the macro name should contain the name of the file and some +additional text, to avoid conflicts with other header files. + +The GNU C preprocessor is programmed to notice when a header file uses +this particular construct and handle it efficiently. If a header file +is contained entirely in a @samp{#ifndef} conditional, then it records +that fact. If a subsequent @samp{#include} specifies the same file, +and the macro in the @samp{#ifndef} is already defined, then the file +is entirely skipped, without even reading it. + +@findex #pragma once +There is also an explicit command to tell the preprocessor that it need +not include a file more than once. This is called @samp{#pragma once}, +and was used @emph{in addition to} the @samp{#ifndef} conditional around +the contents of the header file. @samp{#pragma once} is now obsolete +and should not be used at all. + +@findex #import +In the Objective C language, there is a variant of @samp{#include} +called @samp{#import} which includes a file, but does so at most once. +If you use @samp{#import} @emph{instead of} @samp{#include}, then you +don't need the conditionals inside the header file to prevent multiple +execution of the contents. + +@samp{#import} is obsolete because it is not a well designed feature. +It requires the users of a header file---the applications +programmers---to know that a certain header file should only be included +once. It is much better for the header file's implementor to write the +file so that users don't need to know this. Using @samp{#ifndef} +accomplishes this goal. + +@node Inheritance,, Once-Only, Header Files +@subsection Inheritance and Header Files +@cindex inheritance +@cindex overriding a header file + +@dfn{Inheritance} is what happens when one object or file derives some +of its contents by virtual copying from another object or file. In +the case of C header files, inheritance means that one header file +includes another header file and then replaces or adds something. + +If the inheriting header file and the base header file have different +names, then inheritance is straightforward: simply write @samp{#include +"@var{base}"} in the inheriting file. + +Sometimes it is necessary to give the inheriting file the same name as +the base file. This is less straightforward. + +For example, suppose an application program uses the system header file +@file{sys/signal.h}, but the version of @file{/usr/include/sys/signal.h} +on a particular system doesn't do what the application program expects. +It might be convenient to define a ``local'' version, perhaps under the +name @file{/usr/local/include/sys/signal.h}, to override or add to the +one supplied by the system. + +You can do this by using the option @samp{-I.} for compilation, and +writing a file @file{sys/signal.h} that does what the application +program expects. But making this file include the standard +@file{sys/signal.h} is not so easy---writing @samp{#include +<sys/signal.h>} in that file doesn't work, because it includes your own +version of the file, not the standard system version. Used in that file +itself, this leads to an infinite recursion and a fatal error in +compilation. + +@samp{#include </usr/include/sys/signal.h>} would find the proper file, +but that is not clean, since it makes an assumption about where the +system header file is found. This is bad for maintenance, since it +means that any change in where the system's header files are kept +requires a change somewhere else. + +@findex #include_next +The clean way to solve this problem is to use +@samp{#include_next}, which means, ``Include the @emph{next} file with +this name.'' This command works like @samp{#include} except in +searching for the specified file: it starts searching the list of header +file directories @emph{after} the directory in which the current file +was found. + +Suppose you specify @samp{-I /usr/local/include}, and the list of +directories to search also includes @file{/usr/include}; and suppose that +both directories contain a file named @file{sys/signal.h}. Ordinary +@samp{#include <sys/signal.h>} finds the file under +@file{/usr/local/include}. If that file contains @samp{#include_next +<sys/signal.h>}, it starts searching after that directory, and finds the +file in @file{/usr/include}. + +@node Macros, Conditionals, Header Files, Top +@section Macros + +A macro is a sort of abbreviation which you can define once and then +use later. There are many complicated features associated with macros +in the C preprocessor. + +@menu +* Simple Macros:: Macros that always expand the same way. +* Argument Macros:: Macros that accept arguments that are substituted + into the macro expansion. +* Predefined:: Predefined macros that are always available. +* Stringification:: Macro arguments converted into string constants. +* Concatenation:: Building tokens from parts taken from macro arguments. +* Undefining:: Cancelling a macro's definition. +* Redefining:: Changing a macro's definition. +* Macro Pitfalls:: Macros can confuse the unwary. Here we explain + several common problems and strange features. +@end menu + +@node Simple Macros, Argument Macros, Macros, Macros +@subsection Simple Macros +@cindex simple macro +@cindex manifest constant + +A @dfn{simple macro} is a kind of abbreviation. It is a name which +stands for a fragment of code. Some people refer to these as +@dfn{manifest constants}. + +Before you can use a macro, you must @dfn{define} it explicitly with the +@samp{#define} command. @samp{#define} is followed by the name of the +macro and then the code it should be an abbreviation for. For example, + +@example +#define BUFFER_SIZE 1020 +@end example + +@noindent +defines a macro named @samp{BUFFER_SIZE} as an abbreviation for the text +@samp{1020}. If somewhere after this @samp{#define} command there comes +a C statement of the form + +@example +foo = (char *) xmalloc (BUFFER_SIZE); +@end example + +@noindent +then the C preprocessor will recognize and @dfn{expand} the macro +@samp{BUFFER_SIZE}, resulting in + +@example +foo = (char *) xmalloc (1020); +@end example + +The use of all upper case for macro names is a standard convention. +Programs are easier to read when it is possible to tell at a glance which +names are macros. + +Normally, a macro definition must be a single line, like all C +preprocessor commands. (You can split a long macro definition +cosmetically with Backslash-Newline.) There is one exception: Newlines +can be included in the macro definition if within a string or character +constant. This is because it is not possible for a macro definition to +contain an unbalanced quote character; the definition automatically +extends to include the matching quote character that ends the string or +character constant. Comments within a macro definition may contain +Newlines, which make no difference since the comments are entirely +replaced with Spaces regardless of their contents. + +Aside from the above, there is no restriction on what can go in a macro +body. Parentheses need not balance. The body need not resemble valid C +code. (But if it does not, you may get error messages from the C +compiler when you use the macro.) + +The C preprocessor scans your program sequentially, so macro definitions +take effect at the place you write them. Therefore, the following input to +the C preprocessor + +@example +foo = X; +#define X 4 +bar = X; +@end example + +@noindent +produces as output + +@example +foo = X; + +bar = 4; +@end example + +After the preprocessor expands a macro name, the macro's definition body is +appended to the front of the remaining input, and the check for macro calls +continues. Therefore, the macro body can contain calls to other macros. +For example, after + +@example +#define BUFSIZE 1020 +#define TABLESIZE BUFSIZE +@end example + +@noindent +the name @samp{TABLESIZE} when used in the program would go through two +stages of expansion, resulting ultimately in @samp{1020}. + +This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}. +The @samp{#define} for @samp{TABLESIZE} uses exactly the body you +specify---in this case, @samp{BUFSIZE}---and does not check to see whether +it too is the name of a macro. It's only when you @emph{use} @samp{TABLESIZE} +that the result of its expansion is checked for more macro names. +@xref{Cascaded Macros}. + +@node Argument Macros, Predefined, Simple Macros, Macros +@subsection Macros with Arguments +@cindex macros with argument +@cindex arguments in macro definitions +@cindex function-like macro + +A simple macro always stands for exactly the same text, each time it is +used. Macros can be more flexible when they accept @dfn{arguments}. +Arguments are fragments of code that you supply each time the macro is +used. These fragments are included in the expansion of the macro +according to the directions in the macro definition. A macro that +accepts arguments is called a @dfn{function-like macro} because the +syntax for using it looks like a function call. + +@findex #define +To define a macro that uses arguments, you write a @samp{#define} command +with a list of @dfn{argument names} in parentheses after the name of the +macro. The argument names may be any valid C identifiers, separated by +commas and optionally whitespace. The open-parenthesis must follow the +macro name immediately, with no space in between. + +For example, here is a macro that computes the minimum of two numeric +values, as it is defined in many C programs: + +@example +#define min(X, Y) ((X) < (Y) ? (X) : (Y)) +@end example + +@noindent +(This is not the best way to define a ``minimum'' macro in GNU C. +@xref{Side Effects}, for more information.) + +To use a macro that expects arguments, you write the name of the macro +followed by a list of @dfn{actual arguments} in parentheses, separated by +commas. The number of actual arguments you give must match the number of +arguments the macro expects. Examples of use of the macro @samp{min} +include @samp{min (1, 2)} and @samp{min (x + 28, *p)}. + +The expansion text of the macro depends on the arguments you use. +Each of the argument names of the macro is replaced, throughout the +macro definition, with the corresponding actual argument. Using the +same macro @samp{min} defined above, @samp{min (1, 2)} expands into + +@example +((1) < (2) ? (1) : (2)) +@end example + +@noindent +where @samp{1} has been substituted for @samp{X} and @samp{2} for @samp{Y}. + +Likewise, @samp{min (x + 28, *p)} expands into + +@example +((x + 28) < (*p) ? (x + 28) : (*p)) +@end example + +Parentheses in the actual arguments must balance; a comma within +parentheses does not end an argument. However, there is no requirement +for brackets or braces to balance, and they do not prevent a comma from +separating arguments. Thus, + +@example +macro (array[x = y, x + 1]) +@end example + +@noindent +passes two arguments to @code{macro}: @samp{array[x = y} and @samp{x + +1]}. If you want to supply @samp{array[x = y, x + 1]} as an argument, +you must write it as @samp{array[(x = y, x + 1)]}, which is equivalent C +code. + +After the actual arguments are substituted into the macro body, the entire +result is appended to the front of the remaining input, and the check for +macro calls continues. Therefore, the actual arguments can contain calls +to other macros, either with or without arguments, or even to the same +macro. The macro body can also contain calls to other macros. For +example, @samp{min (min (a, b), c)} expands into this text: + +@example +((((a) < (b) ? (a) : (b))) < (c) + ? (((a) < (b) ? (a) : (b))) + : (c)) +@end example + +@noindent +(Line breaks shown here for clarity would not actually be generated.) + +@cindex blank macro arguments +@cindex space as macro argument +If a macro @code{foo} takes one argument, and you want to supply an +empty argument, you must write at least some whitespace between the +parentheses, like this: @samp{foo ( )}. Just @samp{foo ()} is providing +no arguments, which is an error if @code{foo} expects an argument. But +@samp{foo0 ()} is the correct way to call a macro defined to take zero +arguments, like this: + +@example +#define foo0() @dots{} +@end example + +If you use the macro name followed by something other than an +open-parenthesis (after ignoring any spaces, tabs and comments that +follow), it is not a call to the macro, and the preprocessor does not +change what you have written. Therefore, it is possible for the same name +to be a variable or function in your program as well as a macro, and you +can choose in each instance whether to refer to the macro (if an actual +argument list follows) or the variable or function (if an argument list +does not follow). + +Such dual use of one name could be confusing and should be avoided +except when the two meanings are effectively synonymous: that is, when the +name is both a macro and a function and the two have similar effects. You +can think of the name simply as a function; use of the name for purposes +other than calling it (such as, to take the address) will refer to the +function, while calls will expand the macro and generate better but +equivalent code. For example, you can use a function named @samp{min} in +the same source file that defines the macro. If you write @samp{&min} with +no argument list, you refer to the function. If you write @samp{min (x, +bb)}, with an argument list, the macro is expanded. If you write +@samp{(min) (a, bb)}, where the name @samp{min} is not followed by an +open-parenthesis, the macro is not expanded, so you wind up with a call to +the function @samp{min}. + +You may not define the same name as both a simple macro and a macro with +arguments. + +In the definition of a macro with arguments, the list of argument names +must follow the macro name immediately with no space in between. If there +is a space after the macro name, the macro is defined as taking no +arguments, and all the rest of the line is taken to be the expansion. The +reason for this is that it is often useful to define a macro that takes no +arguments and whose definition begins with an identifier in parentheses. +This rule about spaces makes it possible for you to do either this: + +@example +#define FOO(x) - 1 / (x) +@end example + +@noindent +(which defines @samp{FOO} to take an argument and expand into minus the +reciprocal of that argument) or this: + +@example +#define BAR (x) - 1 / (x) +@end example + +@noindent +(which defines @samp{BAR} to take no argument and always expand into +@samp{(x) - 1 / (x)}). + +Note that the @emph{uses} of a macro with arguments can have spaces before +the left parenthesis; it's the @emph{definition} where it matters whether +there is a space. + +@node Predefined, Stringification, Argument Macros, Macros +@subsection Predefined Macros + +@cindex predefined macros +Several simple macros are predefined. You can use them without giving +definitions for them. They fall into two classes: standard macros and +system-specific macros. + +@menu +* Standard Predefined:: Standard predefined macros. +* Nonstandard Predefined:: Nonstandard predefined macros. +@end menu + +@node Standard Predefined, Nonstandard Predefined, Predefined, Predefined +@subsubsection Standard Predefined Macros +@cindex standard predefined macros + +The standard predefined macros are available with the same meanings +regardless of the machine or operating system on which you are using GNU C. +Their names all start and end with double underscores. Those preceding +@code{__GNUC__} in this table are standardized by ANSI C; the rest are +GNU C extensions. + +@table @code +@item __FILE__ +@findex __FILE__ +This macro expands to the name of the current input file, in the form of +a C string constant. The precise name returned is the one that was +specified in @samp{#include} or as the input file name argument. + +@item __LINE__ +@findex __LINE__ +This macro expands to the current input line number, in the form of a +decimal integer constant. While we call it a predefined macro, it's +a pretty strange macro, since its ``definition'' changes with each +new line of source code. + +This and @samp{__FILE__} are useful in generating an error message to +report an inconsistency detected by the program; the message can state +the source line at which the inconsistency was detected. For example, + +@smallexample +fprintf (stderr, "Internal error: " + "negative string length " + "%d at %s, line %d.", + length, __FILE__, __LINE__); +@end smallexample + +A @samp{#include} command changes the expansions of @samp{__FILE__} +and @samp{__LINE__} to correspond to the included file. At the end of +that file, when processing resumes on the input file that contained +the @samp{#include} command, the expansions of @samp{__FILE__} and +@samp{__LINE__} revert to the values they had before the +@samp{#include} (but @samp{__LINE__} is then incremented by one as +processing moves to the line after the @samp{#include}). + +The expansions of both @samp{__FILE__} and @samp{__LINE__} are altered +if a @samp{#line} command is used. @xref{Combining Sources}. + +@item __INCLUDE_LEVEL__ +@findex __INCLUDE_LEVEL_ +This macro expands to a decimal integer constant that represents the +depth of nesting in include files. The value of this macro is +incremented on every @samp{#include} command and decremented at every +end of file. For input files specified by command line arguments, +the nesting level is zero. + +@item __DATE__ +@findex __DATE__ +This macro expands to a string constant that describes the date on +which the preprocessor is being run. The string constant contains +eleven characters and looks like @samp{"Jan 29 1987"} or @w{@samp{"Apr +1 1905"}}. + +@item __TIME__ +@findex __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 @samp{"23:59:01"}. + +@item __STDC__ +@findex __STDC__ +This macro expands to the constant 1, to signify that this is ANSI +Standard C. (Whether that is actually true depends on what C compiler +will operate on the output from the preprocessor.) + +@item __GNUC__ +@findex __GNUC__ +This macro is defined if and only if this is GNU C. This macro is +defined only when the entire GNU C compiler is in use; if you invoke the +preprocessor directly, @samp{__GNUC__} is undefined. The value +identifies the major version number of GNU CC (@samp{1} for GNU CC +version 1, which is now obsolete, and @samp{2} for version 2). + +@item __GNUG__ +@findex __GNUG__ +The GNU C compiler defines this when the compilation language is +C++; use @samp{__GNUG__} to distinguish between GNU C and GNU +C++. + +@item __cplusplus +@findex __cplusplus +The draft ANSI standard for C++ used to require predefining this +variable. Though it is no longer required, GNU C++ continues to define +it, as do other popular C++ compilers. You can use @samp{__cplusplus} +to test whether a header is compiled by a C compiler or a C++ compiler. + +@item __STRICT_ANSI__ +@findex __STRICT_ANSI__ +This macro is defined if and only if the @samp{-ansi} switch was +specified when GNU C was invoked. Its definition is the null string. +This macro exists primarily to direct certain GNU header files not to +define certain traditional Unix constructs which are incompatible with +ANSI C. + +@item __BASE_FILE__ +@findex __BASE_FILE__ +This macro expands to the name of the main input file, in the form +of a C string constant. This is the source file that was specified +as an argument when the C compiler was invoked. + +@item __VERSION__ +@findex __VERSION__ +This macro expands to a string which describes the version number of +GNU C. The string is normally a sequence of decimal numbers separated +by periods, such as @samp{"2.6.0"}. The only reasonable use of this +macro is to incorporate it into a string constant. + +@item __OPTIMIZE__ +@findex __OPTIMIZE__ +This macro is defined in optimizing compilations. It causes certain +GNU header files to define alternative macro definitions for some +system library functions. It is unwise to refer to or test the +definition of this macro unless you make very sure that programs will +execute with the same effect regardless. + +@item __CHAR_UNSIGNED__ +@findex __CHAR_UNSIGNED__ +This macro is defined if and only if the data type @code{char} is +unsigned on the target machine. It exists to cause the standard +header file @file{limit.h} to work correctly. It is bad practice +to refer to this macro yourself; instead, refer to the standard +macros defined in @file{limit.h}. The preprocessor uses +this macro to determine whether or not to sign-extend large character +constants written in octal; see @ref{#if Command,,The @samp{#if} Command}. +@end table + +@node Nonstandard Predefined,, Standard Predefined, Predefined +@subsubsection Nonstandard Predefined Macros + +The C preprocessor normally has several predefined macros that vary between +machines because their purpose is to indicate what type of system and +machine is in use. This manual, being for all systems and machines, cannot +tell you exactly what their names are; instead, we offer a list of some +typical ones. You can use @samp{cpp -dM} to see the values of +predefined macros; see @ref{Invocation}. + +Some nonstandard predefined macros describe the operating system in use, +with more or less specificity. For example, + +@table @code +@item unix +@findex unix +@samp{unix} is normally predefined on all Unix systems. + +@item BSD +@findex BSD +@samp{BSD} is predefined on recent versions of Berkeley Unix +(perhaps only in version 4.3). +@end table + +Other nonstandard predefined macros describe the kind of CPU, with more or +less specificity. For example, + +@table @code +@item vax +@findex vax +@samp{vax} is predefined on Vax computers. + +@item mc68000 +@findex mc68000 +@samp{mc68000} is predefined on most computers whose CPU is a Motorola +68000, 68010 or 68020. + +@item m68k +@findex m68k +@samp{m68k} is also predefined on most computers whose CPU is a 68000, +68010 or 68020; however, some makers use @samp{mc68000} and some use +@samp{m68k}. Some predefine both names. What happens in GNU C +depends on the system you are using it on. + +@item M68020 +@findex M68020 +@samp{M68020} has been observed to be predefined on some systems that +use 68020 CPUs---in addition to @samp{mc68000} and @samp{m68k}, which +are less specific. + +@item _AM29K +@findex _AM29K +@itemx _AM29000 +@findex _AM29000 +Both @samp{_AM29K} and @samp{_AM29000} are predefined for the AMD 29000 +CPU family. + +@item ns32000 +@findex ns32000 +@samp{ns32000} is predefined on computers which use the National +Semiconductor 32000 series CPU. +@end table + +Yet other nonstandard predefined macros describe the manufacturer of +the system. For example, + +@table @code +@item sun +@findex sun +@samp{sun} is predefined on all models of Sun computers. + +@item pyr +@findex pyr +@samp{pyr} is predefined on all models of Pyramid computers. + +@item sequent +@findex sequent +@samp{sequent} is predefined on all models of Sequent computers. +@end table + +These predefined symbols are not only nonstandard, they are contrary to the +ANSI standard because their names do not start with underscores. +Therefore, the option @samp{-ansi} inhibits the definition of these +symbols. + +This tends to make @samp{-ansi} useless, since many programs depend on the +customary nonstandard predefined symbols. Even system header files check +them and will generate incorrect declarations if they do not find the names +that are expected. You might think that the header files supplied for the +Uglix computer would not need to test what machine they are running on, +because they can simply assume it is the Uglix; but often they do, and they +do so using the customary names. As a result, very few C programs will +compile with @samp{-ansi}. We intend to avoid such problems on the GNU +system. + +What, then, should you do in an ANSI C program to test the type of machine +it will run on? + +GNU C offers a parallel series of symbols for this purpose, whose names +are made from the customary ones by adding @samp{__} at the beginning +and end. Thus, the symbol @code{__vax__} would be available on a Vax, +and so on. + +The set of nonstandard predefined names in the GNU C preprocessor is +controlled (when @code{cpp} is itself compiled) by the macro +@samp{CPP_PREDEFINES}, which should be a string containing @samp{-D} +options, separated by spaces. For example, on the Sun 3, we use the +following definition: + +@example +#define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k" +@end example + +@noindent +This macro is usually specified in @file{tm.h}. + +@node Stringification, Concatenation, Predefined, Macros +@subsection Stringification + +@cindex stringification +@dfn{Stringification} means turning a code fragment into a string constant +whose contents are the text for the code fragment. For example, +stringifying @samp{foo (z)} results in @samp{"foo (z)"}. + +In the C preprocessor, stringification is an option available when macro +arguments are substituted into the macro definition. In the body of the +definition, when an argument name appears, the character @samp{#} before +the name specifies stringification of the corresponding actual argument +when it is substituted at that point in the definition. The same argument +may be substituted in other places in the definition without +stringification if the argument name appears in those places with no +@samp{#}. + +Here is an example of a macro definition that uses stringification: + +@smallexample +@group +#define WARN_IF(EXP) \ +do @{ if (EXP) \ + fprintf (stderr, "Warning: " #EXP "\n"); @} \ +while (0) +@end group +@end smallexample + +@noindent +Here the actual argument for @samp{EXP} is substituted once as given, +into the @samp{if} statement, and once as stringified, into the +argument to @samp{fprintf}. The @samp{do} and @samp{while (0)} are +a kludge to make it possible to write @samp{WARN_IF (@var{arg});}, +which the resemblance of @samp{WARN_IF} to a function would make +C programmers want to do; see @ref{Swallow Semicolon}. + +The stringification feature is limited to transforming one macro argument +into one string constant: there is no way to combine the argument with +other text and then stringify it all together. But the example above shows +how an equivalent result can be obtained in ANSI Standard C using the +feature that adjacent string constants are concatenated as one string +constant. The preprocessor stringifies the actual value of @samp{EXP} +into a separate string constant, resulting in text like + +@smallexample +@group +do @{ if (x == 0) \ + fprintf (stderr, "Warning: " "x == 0" "\n"); @} \ +while (0) +@end group +@end smallexample + +@noindent +but the C compiler then sees three consecutive string constants and +concatenates them into one, producing effectively + +@smallexample +do @{ if (x == 0) \ + fprintf (stderr, "Warning: x == 0\n"); @} \ +while (0) +@end smallexample + +Stringification in C involves more than putting doublequote characters +around the fragment; it is necessary to put backslashes in front of all +doublequote characters, and all backslashes in string and character +constants, in order to get a valid C string constant with the proper +contents. Thus, stringifying @samp{p = "foo\n";} results in @samp{"p = +\"foo\\n\";"}. However, backslashes that are not inside of string or +character constants are not duplicated: @samp{\n} by itself stringifies to +@samp{"\n"}. + +Whitespace (including comments) in the text being stringified is handled +according to precise rules. All leading and trailing whitespace is ignored. +Any sequence of whitespace in the middle of the text is converted to +a single space in the stringified result. + +@node Concatenation, Undefining, Stringification, Macros +@subsection Concatenation +@cindex concatenation +@cindex @samp{##} +@dfn{Concatenation} means joining two strings into one. In the context +of macro expansion, concatenation refers to joining two lexical units +into one longer one. Specifically, an actual argument to the macro can be +concatenated with another actual argument or with fixed text to produce +a longer name. The longer name might be the name of a function, +variable or type, or a C keyword; it might even be the name of another +macro, in which case it will be expanded. + +When you define a macro, you request concatenation with the special +operator @samp{##} in the macro body. When the macro is called, +after actual arguments are substituted, all @samp{##} operators are +deleted, and so is any whitespace next to them (including whitespace +that was part of an actual argument). The result is to concatenate +the syntactic tokens on either side of the @samp{##}. + +Consider a C program that interprets named commands. There probably needs +to be a table of commands, perhaps an array of structures declared as +follows: + +@example +struct command +@{ + char *name; + void (*function) (); +@}; + +struct command commands[] = +@{ + @{ "quit", quit_command@}, + @{ "help", help_command@}, + @dots{} +@}; +@end example + +It would be cleaner not to have to give each command name twice, once in +the string constant and once in the function name. A macro which takes the +name of a command as an argument can make this unnecessary. The string +constant can be created with stringification, and the function name by +concatenating the argument with @samp{_command}. Here is how it is done: + +@example +#define COMMAND(NAME) @{ #NAME, NAME ## _command @} + +struct command commands[] = +@{ + COMMAND (quit), + COMMAND (help), + @dots{} +@}; +@end example + +The usual case of concatenation is concatenating two names (or a name and a +number) into a longer name. But this isn't the only valid case. It is +also possible to concatenate two numbers (or a number and a name, such as +@samp{1.5} and @samp{e3}) into a number. Also, multi-character operators +such as @samp{+=} can be formed by concatenation. In some cases it is even +possible to piece together a string constant. However, two pieces of text +that don't together form a valid lexical unit cannot be concatenated. For +example, concatenation with @samp{x} on one side and @samp{+} on the other +is not meaningful because those two characters can't fit together in any +lexical unit of C. The ANSI standard says that such attempts at +concatenation are undefined, but in the GNU C preprocessor it is well +defined: it puts the @samp{x} and @samp{+} side by side with no particular +special results. + +Keep in mind that the C preprocessor converts comments to whitespace before +macros are even considered. Therefore, you cannot create a comment by +concatenating @samp{/} and @samp{*}: the @samp{/*} sequence that starts a +comment is not a lexical unit, but rather the beginning of a ``long'' space +character. Also, you can freely use comments next to a @samp{##} in a +macro definition, or in actual arguments that will be concatenated, because +the comments will be converted to spaces at first sight, and concatenation +will later discard the spaces. + +@node Undefining, Redefining, Concatenation, Macros +@subsection Undefining Macros + +@cindex undefining macros +To @dfn{undefine} a macro means to cancel its definition. This is done +with the @samp{#undef} command. @samp{#undef} is followed by the macro +name to be undefined. + +Like definition, undefinition occurs at a specific point in the source +file, and it applies starting from that point. The name ceases to be a +macro name, and from that point on it is treated by the preprocessor as if +it had never been a macro name. + +For example, + +@example +#define FOO 4 +x = FOO; +#undef FOO +x = FOO; +@end example + +@noindent +expands into + +@example +x = 4; + +x = FOO; +@end example + +@noindent +In this example, @samp{FOO} had better be a variable or function as well +as (temporarily) a macro, in order for the result of the expansion to be +valid C code. + +The same form of @samp{#undef} command will cancel definitions with +arguments or definitions that don't expect arguments. The @samp{#undef} +command has no effect when used on a name not currently defined as a macro. + +@node Redefining, Macro Pitfalls, Undefining, Macros +@subsection Redefining Macros + +@cindex redefining macros +@dfn{Redefining} a macro means defining (with @samp{#define}) a name that +is already defined as a macro. + +A redefinition is trivial if the new definition is transparently identical +to the old one. You probably wouldn't deliberately write a trivial +redefinition, but they can happen automatically when a header file is +included more than once (@pxref{Header Files}), so they are accepted +silently and without effect. + +Nontrivial redefinition is considered likely to be an error, so +it provokes a warning message from the preprocessor. However, sometimes it +is useful to change the definition of a macro in mid-compilation. You can +inhibit the warning by undefining the macro with @samp{#undef} before the +second definition. + +In order for a redefinition to be trivial, the new definition must +exactly match the one already in effect, with two possible exceptions: + +@itemize @bullet +@item +Whitespace may be added or deleted at the beginning or the end. + +@item +Whitespace may be changed in the middle (but not inside strings). +However, it may not be eliminated entirely, and it may not be added +where there was no whitespace at all. +@end itemize + +Recall that a comment counts as whitespace. + +@node Macro Pitfalls,, Redefining, Macros +@subsection Pitfalls and Subtleties of Macros +@cindex problems with macros +@cindex pitfalls of macros + +In this section we describe some special rules that apply to macros and +macro expansion, and point out certain cases in which the rules have +counterintuitive consequences that you must watch out for. + +@menu +* Misnesting:: Macros can contain unmatched parentheses. +* Macro Parentheses:: Why apparently superfluous parentheses + may be necessary to avoid incorrect grouping. +* Swallow Semicolon:: Macros that look like functions + but expand into compound statements. +* Side Effects:: Unsafe macros that cause trouble when + arguments contain side effects. +* Self-Reference:: Macros whose definitions use the macros' own names. +* Argument Prescan:: Actual arguments are checked for macro calls + before they are substituted. +* Cascaded Macros:: Macros whose definitions use other macros. +* Newlines in Args:: Sometimes line numbers get confused. +@end menu + +@node Misnesting, Macro Parentheses, Macro Pitfalls, Macro Pitfalls +@subsubsection Improperly Nested Constructs + +Recall that when a macro is called with arguments, the arguments are +substituted into the macro body and the result is checked, together with +the rest of the input file, for more macro calls. + +It is possible to piece together a macro call coming partially from the +macro body and partially from the actual arguments. For example, + +@example +#define double(x) (2*(x)) +#define call_with_1(x) x(1) +@end example + +@noindent +would expand @samp{call_with_1 (double)} into @samp{(2*(1))}. + +Macro definitions do not have to have balanced parentheses. By writing an +unbalanced open parenthesis in a macro body, it is possible to create a +macro call that begins inside the macro body but ends outside of it. For +example, + +@example +#define strange(file) fprintf (file, "%s %d", +@dots{} +strange(stderr) p, 35) +@end example + +@noindent +This bizarre example expands to @samp{fprintf (stderr, "%s %d", p, 35)}! + +@node Macro Parentheses, Swallow Semicolon, Misnesting, Macro Pitfalls +@subsubsection Unintended Grouping of Arithmetic +@cindex parentheses in macro bodies + +You may have noticed that in most of the macro definition examples shown +above, each occurrence of a macro argument name had parentheses around it. +In addition, another pair of parentheses usually surround the entire macro +definition. Here is why it is best to write macros that way. + +Suppose you define a macro as follows, + +@example +#define ceil_div(x, y) (x + y - 1) / y +@end example + +@noindent +whose purpose is to divide, rounding up. (One use for this operation is +to compute how many @samp{int} objects are needed to hold a certain +number of @samp{char} objects.) Then suppose it is used as follows: + +@example +a = ceil_div (b & c, sizeof (int)); +@end example + +@noindent +This expands into + +@example +a = (b & c + sizeof (int) - 1) / sizeof (int); +@end example + +@noindent +which does not do what is intended. The operator-precedence rules of +C make it equivalent to this: + +@example +a = (b & (c + sizeof (int) - 1)) / sizeof (int); +@end example + +@noindent +But what we want is this: + +@example +a = ((b & c) + sizeof (int) - 1)) / sizeof (int); +@end example + +@noindent +Defining the macro as + +@example +#define ceil_div(x, y) ((x) + (y) - 1) / (y) +@end example + +@noindent +provides the desired result. + +However, unintended grouping can result in another way. Consider +@samp{sizeof ceil_div(1, 2)}. That has the appearance of a C expression +that would compute the size of the type of @samp{ceil_div (1, 2)}, but in +fact it means something very different. Here is what it expands to: + +@example +sizeof ((1) + (2) - 1) / (2) +@end example + +@noindent +This would take the size of an integer and divide it by two. The precedence +rules have put the division outside the @samp{sizeof} when it was intended +to be inside. + +Parentheses around the entire macro definition can prevent such problems. +Here, then, is the recommended way to define @samp{ceil_div}: + +@example +#define ceil_div(x, y) (((x) + (y) - 1) / (y)) +@end example + +@node Swallow Semicolon, Side Effects, Macro Parentheses, Macro Pitfalls +@subsubsection Swallowing the Semicolon + +@cindex semicolons (after macro calls) +Often it is desirable to define a macro that expands into a compound +statement. Consider, for example, the following macro, that advances a +pointer (the argument @samp{p} says where to find it) across whitespace +characters: + +@example +#define SKIP_SPACES (p, limit) \ +@{ register char *lim = (limit); \ + while (p != lim) @{ \ + if (*p++ != ' ') @{ \ + p--; break; @}@}@} +@end example + +@noindent +Here Backslash-Newline is used to split the macro definition, which must +be a single line, so that it resembles the way such C code would be +laid out if not part of a macro definition. + +A call to this macro might be @samp{SKIP_SPACES (p, lim)}. Strictly +speaking, the call expands to a compound statement, which is a complete +statement with no need for a semicolon to end it. But it looks like a +function call. So it minimizes confusion if you can use it like a function +call, writing a semicolon afterward, as in @samp{SKIP_SPACES (p, lim);} + +But this can cause trouble before @samp{else} statements, because the +semicolon is actually a null statement. Suppose you write + +@example +if (*p != 0) + SKIP_SPACES (p, lim); +else @dots{} +@end example + +@noindent +The presence of two statements---the compound statement and a null +statement---in between the @samp{if} condition and the @samp{else} +makes invalid C code. + +The definition of the macro @samp{SKIP_SPACES} can be altered to solve +this problem, using a @samp{do @dots{} while} statement. Here is how: + +@example +#define SKIP_SPACES (p, limit) \ +do @{ register char *lim = (limit); \ + while (p != lim) @{ \ + if (*p++ != ' ') @{ \ + p--; break; @}@}@} \ +while (0) +@end example + +Now @samp{SKIP_SPACES (p, lim);} expands into + +@example +do @{@dots{}@} while (0); +@end example + +@noindent +which is one statement. + +@node Side Effects, Self-Reference, Swallow Semicolon, Macro Pitfalls +@subsubsection Duplication of Side Effects + +@cindex side effects (in macro arguments) +@cindex unsafe macros +Many C programs define a macro @samp{min}, for ``minimum'', like this: + +@example +#define min(X, Y) ((X) < (Y) ? (X) : (Y)) +@end example + +When you use this macro with an argument containing a side effect, +as shown here, + +@example +next = min (x + y, foo (z)); +@end example + +@noindent +it expands as follows: + +@example +next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); +@end example + +@noindent +where @samp{x + y} has been substituted for @samp{X} and @samp{foo (z)} +for @samp{Y}. + +The function @samp{foo} is used only once in the statement as it appears +in the program, but the expression @samp{foo (z)} has been substituted +twice into the macro expansion. As a result, @samp{foo} might be called +two times when the statement is executed. If it has side effects or +if it takes a long time to compute, the results might not be what you +intended. We say that @samp{min} is an @dfn{unsafe} macro. + +The best solution to this problem is to define @samp{min} in a way that +computes the value of @samp{foo (z)} only once. The C language offers no +standard way to do this, but it can be done with GNU C extensions as +follows: + +@example +#define min(X, Y) \ +(@{ typeof (X) __x = (X), __y = (Y); \ + (__x < __y) ? __x : __y; @}) +@end example + +If you do not wish to use GNU C extensions, the only solution is to be +careful when @emph{using} the macro @samp{min}. For example, you can +calculate the value of @samp{foo (z)}, save it in a variable, and use that +variable in @samp{min}: + +@example +#define min(X, Y) ((X) < (Y) ? (X) : (Y)) +@dots{} +@{ + int tem = foo (z); + next = min (x + y, tem); +@} +@end example + +@noindent +(where we assume that @samp{foo} returns type @samp{int}). + +@node Self-Reference, Argument Prescan, Side Effects, Macro Pitfalls +@subsubsection Self-Referential Macros + +@cindex self-reference +A @dfn{self-referential} macro is one whose name appears in its definition. +A special feature of ANSI Standard C is that the self-reference is not +considered a macro call. It is passed into the preprocessor output +unchanged. + +Let's consider an example: + +@example +#define foo (4 + foo) +@end example + +@noindent +where @samp{foo} is also a variable in your program. + +Following the ordinary rules, each reference to @samp{foo} will expand into +@samp{(4 + foo)}; then this will be rescanned and will expand into @samp{(4 ++ (4 + foo))}; and so on until it causes a fatal error (memory full) in the +preprocessor. + +However, the special rule about self-reference cuts this process short +after one step, at @samp{(4 + foo)}. Therefore, this macro definition +has the possibly useful effect of causing the program to add 4 to +the value of @samp{foo} wherever @samp{foo} is referred to. + +In most cases, it is a bad idea to take advantage of this feature. A +person reading the program who sees that @samp{foo} is a variable will +not expect that it is a macro as well. The reader will come across the +identifier @samp{foo} in the program and think its value should be that +of the variable @samp{foo}, whereas in fact the value is four greater. + +The special rule for self-reference applies also to @dfn{indirect} +self-reference. This is the case where a macro @var{x} expands to use a +macro @samp{y}, and the expansion of @samp{y} refers to the macro +@samp{x}. The resulting reference to @samp{x} comes indirectly from the +expansion of @samp{x}, so it is a self-reference and is not further +expanded. Thus, after + +@example +#define x (4 + y) +#define y (2 * x) +@end example + +@noindent +@samp{x} would expand into @samp{(4 + (2 * x))}. Clear? + +But suppose @samp{y} is used elsewhere, not from the definition of @samp{x}. +Then the use of @samp{x} in the expansion of @samp{y} is not a self-reference +because @samp{x} is not ``in progress''. So it does expand. However, +the expansion of @samp{x} contains a reference to @samp{y}, and that +is an indirect self-reference now because @samp{y} is ``in progress''. +The result is that @samp{y} expands to @samp{(2 * (4 + y))}. + +It is not clear that this behavior would ever be useful, but it is specified +by the ANSI C standard, so you may need to understand it. + +@node Argument Prescan, Cascaded Macros, Self-Reference, Macro Pitfalls +@subsubsection Separate Expansion of Macro Arguments +@cindex expansion of arguments +@cindex macro argument expansion +@cindex prescan of macro arguments + +We have explained that the expansion of a macro, including the substituted +actual arguments, is scanned over again for macro calls to be expanded. + +What really happens is more subtle: first each actual argument text is scanned +separately for macro calls. Then the results of this are substituted into +the macro body to produce the macro expansion, and the macro expansion +is scanned again for macros to expand. + +The result is that the actual arguments are scanned @emph{twice} to expand +macro calls in them. + +Most of the time, this has no effect. If the actual argument contained +any macro calls, they are expanded during the first scan. The result +therefore contains no macro calls, so the second scan does not change it. +If the actual argument were substituted as given, with no prescan, +the single remaining scan would find the same macro calls and produce +the same results. + +You might expect the double scan to change the results when a +self-referential macro is used in an actual argument of another macro +(@pxref{Self-Reference}): the self-referential macro would be expanded once +in the first scan, and a second time in the second scan. But this is not +what happens. The self-references that do not expand in the first scan are +marked so that they will not expand in the second scan either. + +The prescan is not done when an argument is stringified or concatenated. +Thus, + +@example +#define str(s) #s +#define foo 4 +str (foo) +@end example + +@noindent +expands to @samp{"foo"}. Once more, prescan has been prevented from +having any noticeable effect. + +More precisely, stringification and concatenation use the argument as +written, in un-prescanned form. The same actual argument would be used in +prescanned form if it is substituted elsewhere without stringification or +concatenation. + +@example +#define str(s) #s lose(s) +#define foo 4 +str (foo) +@end example + +expands to @samp{"foo" lose(4)}. + +You might now ask, ``Why mention the prescan, if it makes no difference? +And why not skip it and make the preprocessor faster?'' The answer is +that the prescan does make a difference in three special cases: + +@itemize @bullet +@item +Nested calls to a macro. + +@item +Macros that call other macros that stringify or concatenate. + +@item +Macros whose expansions contain unshielded commas. +@end itemize + +We say that @dfn{nested} calls to a macro occur when a macro's actual +argument contains a call to that very macro. For example, if @samp{f} +is a macro that expects one argument, @samp{f (f (1))} is a nested +pair of calls to @samp{f}. The desired expansion is made by +expanding @samp{f (1)} and substituting that into the definition of +@samp{f}. The prescan causes the expected result to happen. +Without the prescan, @samp{f (1)} itself would be substituted as +an actual argument, and the inner use of @samp{f} would appear +during the main scan as an indirect self-reference and would not +be expanded. Here, the prescan cancels an undesirable side effect +(in the medical, not computational, sense of the term) of the special +rule for self-referential macros. + +But prescan causes trouble in certain other cases of nested macro calls. +Here is an example: + +@example +#define foo a,b +#define bar(x) lose(x) +#define lose(x) (1 + (x)) + +bar(foo) +@end example + +@noindent +We would like @samp{bar(foo)} to turn into @samp{(1 + (foo))}, which +would then turn into @samp{(1 + (a,b))}. But instead, @samp{bar(foo)} +expands into @samp{lose(a,b)}, and you get an error because @code{lose} +requires a single argument. In this case, the problem is easily solved +by the same parentheses that ought to be used to prevent misnesting of +arithmetic operations: + +@example +#define foo (a,b) +#define bar(x) lose((x)) +@end example + +The problem is more serious when the operands of the macro are not +expressions; for example, when they are statements. Then parentheses +are unacceptable because they would make for invalid C code: + +@example +#define foo @{ int a, b; @dots{} @} +@end example + +@noindent +In GNU C you can shield the commas using the @samp{(@{@dots{}@})} +construct which turns a compound statement into an expression: + +@example +#define foo (@{ int a, b; @dots{} @}) +@end example + +Or you can rewrite the macro definition to avoid such commas: + +@example +#define foo @{ int a; int b; @dots{} @} +@end example + +There is also one case where prescan is useful. It is possible +to use prescan to expand an argument and then stringify it---if you use +two levels of macros. Let's add a new macro @samp{xstr} to the +example shown above: + +@example +#define xstr(s) str(s) +#define str(s) #s +#define foo 4 +xstr (foo) +@end example + +This expands into @samp{"4"}, not @samp{"foo"}. The reason for the +difference is that the argument of @samp{xstr} is expanded at prescan +(because @samp{xstr} does not specify stringification or concatenation of +the argument). The result of prescan then forms the actual argument for +@samp{str}. @samp{str} uses its argument without prescan because it +performs stringification; but it cannot prevent or undo the prescanning +already done by @samp{xstr}. + +@node Cascaded Macros, Newlines in Args, Argument Prescan, Macro Pitfalls +@subsubsection Cascaded Use of Macros + +@cindex cascaded macros +@cindex macro body uses macro +A @dfn{cascade} of macros is when one macro's body contains a reference +to another macro. This is very common practice. For example, + +@example +#define BUFSIZE 1020 +#define TABLESIZE BUFSIZE +@end example + +This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}. +The @samp{#define} for @samp{TABLESIZE} uses exactly the body you +specify---in this case, @samp{BUFSIZE}---and does not check to see whether +it too is the name of a macro. + +It's only when you @emph{use} @samp{TABLESIZE} that the result of its expansion +is checked for more macro names. + +This makes a difference if you change the definition of @samp{BUFSIZE} +at some point in the source file. @samp{TABLESIZE}, defined as shown, +will always expand using the definition of @samp{BUFSIZE} that is +currently in effect: + +@example +#define BUFSIZE 1020 +#define TABLESIZE BUFSIZE +#undef BUFSIZE +#define BUFSIZE 37 +@end example + +@noindent +Now @samp{TABLESIZE} expands (in two stages) to @samp{37}. (The +@samp{#undef} is to prevent any warning about the nontrivial +redefinition of @code{BUFSIZE}.) + +@node Newlines in Args,, Cascaded Macros, Macro Pitfalls +@subsection Newlines in Macro Arguments +@cindex newlines in macro arguments + +Traditional macro processing carries forward all newlines in macro +arguments into the expansion of the macro. This means that, if some of +the arguments are substituted more than once, or not at all, or out of +order, newlines can be duplicated, lost, or moved around within the +expansion. If the expansion consists of multiple statements, then the +effect is to distort the line numbers of some of these statements. The +result can be incorrect line numbers, in error messages or displayed in +a debugger. + +The GNU C preprocessor operating in ANSI C mode adjusts appropriately +for multiple use of an argument---the first use expands all the +newlines, and subsequent uses of the same argument produce no newlines. +But even in this mode, it can produce incorrect line numbering if +arguments are used out of order, or not used at all. + +Here is an example illustrating this problem: + +@example +#define ignore_second_arg(a,b,c) a; c + +ignore_second_arg (foo (), + ignored (), + syntax error); +@end example + +@noindent +The syntax error triggered by the tokens @samp{syntax error} results +in an error message citing line four, even though the statement text +comes from line five. + +@node Conditionals, Combining Sources, Macros, Top +@section Conditionals + +@cindex conditionals +In a macro processor, a @dfn{conditional} is a command that allows a part +of the program to be ignored during compilation, on some conditions. +In the C preprocessor, a conditional can test either an arithmetic expression +or whether a name is defined as a macro. + +A conditional in the C preprocessor resembles in some ways an @samp{if} +statement in C, but it is important to understand the difference between +them. The condition in an @samp{if} statement is tested during the execution +of your program. Its purpose is to allow your program to behave differently +from run to run, depending on the data it is operating on. The condition +in a preprocessor conditional command is tested when your program is compiled. +Its purpose is to allow different code to be included in the program depending +on the situation at the time of compilation. + +@menu +* Uses: Conditional Uses. What conditionals are for. +* Syntax: Conditional Syntax. How conditionals are written. +* Deletion: Deleted Code. Making code into a comment. +* Macros: Conditionals-Macros. Why conditionals are used with macros. +* Assertions:: How and why to use assertions. +* Errors: #error Command. Detecting inconsistent compilation parameters. +@end menu + +@node Conditional Uses +@subsection Why Conditionals are Used + +Generally there are three kinds of reason to use a conditional. + +@itemize @bullet +@item +A program may need to use different code depending on the machine or +operating system it is to run on. In some cases the code for one +operating system may be erroneous on another operating system; for +example, it might refer to library routines that do not exist on the +other system. When this happens, it is not enough to avoid executing +the invalid code: merely having it in the program makes it impossible +to link the program and run it. With a preprocessor conditional, the +offending code can be effectively excised from the program when it is +not valid. + +@item +You may want to be able to compile the same source file into two +different programs. Sometimes the difference between the programs is +that one makes frequent time-consuming consistency checks on its +intermediate data, or prints the values of those data for debugging, +while the other does not. + +@item +A conditional whose condition is always false is a good way to exclude +code from the program but keep it as a sort of comment for future +reference. +@end itemize + +Most simple programs that are intended to run on only one machine will +not need to use preprocessor conditionals. + +@node Conditional Syntax +@subsection Syntax of Conditionals + +@findex #if +A conditional in the C preprocessor begins with a @dfn{conditional +command}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. +@xref{Conditionals-Macros}, for information on @samp{#ifdef} and +@samp{#ifndef}; only @samp{#if} is explained here. + +@menu +* If: #if Command. Basic conditionals using @samp{#if} and @samp{#endif}. +* Else: #else Command. Including some text if the condition fails. +* Elif: #elif Command. Testing several alternative possibilities. +@end menu + +@node #if Command +@subsubsection The @samp{#if} Command + +The @samp{#if} command in its simplest form consists of + +@example +#if @var{expression} +@var{controlled text} +#endif /* @var{expression} */ +@end example + +The comment following the @samp{#endif} is not required, but it is a good +practice because it helps people match the @samp{#endif} to the +corresponding @samp{#if}. Such comments should always be used, except in +short conditionals that are not nested. In fact, you can put anything at +all after the @samp{#endif} and it will be ignored by the GNU C preprocessor, +but only comments are acceptable in ANSI Standard C. + +@var{expression} is a C expression of integer type, subject to stringent +restrictions. It may contain + +@itemize @bullet +@item +Integer constants, which are all regarded as @code{long} or +@code{unsigned long}. + +@item +Character constants, which are interpreted according to the character +set and conventions of the machine and operating system on which the +preprocessor is running. The GNU C preprocessor uses the C data type +@samp{char} for these character constants; therefore, whether some +character codes are negative is determined by the C compiler used to +compile the preprocessor. If it treats @samp{char} as signed, then +character codes large enough to set the sign bit will be considered +negative; otherwise, no character code is considered negative. + +@item +Arithmetic operators for addition, subtraction, multiplication, +division, bitwise operations, shifts, comparisons, and logical +operations (@samp{&&} and @samp{||}). + +@item +Identifiers that are not macros, which are all treated as zero(!). + +@item +Macro calls. All macro calls in the expression are expanded before +actual computation of the expression's value begins. +@end itemize + +Note that @samp{sizeof} operators and @code{enum}-type values are not allowed. +@code{enum}-type values, like all other identifiers that are not taken +as macro calls and expanded, are treated as zero. + +The @var{controlled text} inside of a conditional can include +preprocessor commands. Then the commands inside the conditional are +obeyed only if that branch of the conditional succeeds. The text can +also contain other conditional groups. However, the @samp{#if} and +@samp{#endif} commands must balance. + +@node #else Command +@subsubsection The @samp{#else} Command + +@findex #else +The @samp{#else} command can be added to a conditional to provide +alternative text to be used if the condition is false. This is what +it looks like: + +@example +#if @var{expression} +@var{text-if-true} +#else /* Not @var{expression} */ +@var{text-if-false} +#endif /* Not @var{expression} */ +@end example + +If @var{expression} is nonzero, and thus the @var{text-if-true} is +active, then @samp{#else} acts like a failing conditional and the +@var{text-if-false} is ignored. Contrariwise, if the @samp{#if} +conditional fails, the @var{text-if-false} is considered included. + +@node #elif Command +@subsubsection The @samp{#elif} Command + +@findex #elif +One common case of nested conditionals is used to check for more than two +possible alternatives. For example, you might have + +@example +#if X == 1 +@dots{} +#else /* X != 1 */ +#if X == 2 +@dots{} +#else /* X != 2 */ +@dots{} +#endif /* X != 2 */ +#endif /* X != 1 */ +@end example + +Another conditional command, @samp{#elif}, allows this to be abbreviated +as follows: + +@example +#if X == 1 +@dots{} +#elif X == 2 +@dots{} +#else /* X != 2 and X != 1*/ +@dots{} +#endif /* X != 2 and X != 1*/ +@end example + +@samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the +middle of a @samp{#if}-@samp{#endif} pair and subdivides it; it does not +require a matching @samp{#endif} of its own. Like @samp{#if}, the +@samp{#elif} command includes an expression to be tested. + +The text following the @samp{#elif} is processed only if the original +@samp{#if}-condition failed and the @samp{#elif} condition succeeds. +More than one @samp{#elif} can go in the same @samp{#if}-@samp{#endif} +group. Then the text after each @samp{#elif} is processed only if the +@samp{#elif} condition succeeds after the original @samp{#if} and any +previous @samp{#elif} commands within it have failed. @samp{#else} is +equivalent to @samp{#elif 1}, and @samp{#else} is allowed after any +number of @samp{#elif} commands, but @samp{#elif} may not follow +@samp{#else}. + +@node Deleted Code +@subsection Keeping Deleted Code for Future Reference +@cindex commenting out code + +If you replace or delete a part of the program but want to keep the old +code around as a comment for future reference, the easy way to do this +is to put @samp{#if 0} before it and @samp{#endif} after it. This is +better than using comment delimiters @samp{/*} and @samp{*/} since those +won't work if the code already contains comments (C comments do not +nest). + +This works even if the code being turned off contains conditionals, but +they must be entire conditionals (balanced @samp{#if} and @samp{#endif}). + +Conversely, do not use @samp{#if 0} for comments which are not C code. +Use the comment delimiters @samp{/*} and @samp{*/} instead. The +interior of @samp{#if 0} must consist of complete tokens; in particular, +singlequote characters must balance. But comments often contain +unbalanced singlequote characters (known in English as apostrophes). +These confuse @samp{#if 0}. They do not confuse @samp{/*}. + +@node Conditionals-Macros +@subsection Conditionals and Macros + +Conditionals are useful in connection with macros or assertions, because +those are the only ways that an expression's value can vary from one +compilation to another. A @samp{#if} command whose expression uses no +macros or assertions is equivalent to @samp{#if 1} or @samp{#if 0}; you +might as well determine which one, by computing the value of the +expression yourself, and then simplify the program. + +For example, here is a conditional that tests the expression +@samp{BUFSIZE == 1020}, where @samp{BUFSIZE} must be a macro. + +@example +#if BUFSIZE == 1020 + printf ("Large buffers!\n"); +#endif /* BUFSIZE is large */ +@end example + +(Programmers often wish they could test the size of a variable or data +type in @samp{#if}, but this does not work. The preprocessor does not +understand @code{sizeof}, or typedef names, or even the type keywords +such as @code{int}.) + +@findex defined +The special operator @samp{defined} is used in @samp{#if} expressions to +test whether a certain name is defined as a macro. Either @samp{defined +@var{name}} or @samp{defined (@var{name})} is an expression whose value +is 1 if @var{name} is defined as macro at the current point in the +program, and 0 otherwise. For the @samp{defined} operator it makes no +difference what the definition of the macro is; all that matters is +whether there is a definition. Thus, for example,@refill + +@example +#if defined (vax) || defined (ns16000) +@end example + +@noindent +would succeed if either of the names @samp{vax} and @samp{ns16000} is +defined as a macro. You can test the same condition using assertions +(@pxref{Assertions}), like this: + +@example +#if #cpu (vax) || #cpu (ns16000) +@end example + +If a macro is defined and later undefined with @samp{#undef}, +subsequent use of the @samp{defined} operator returns 0, because +the name is no longer defined. If the macro is defined again with +another @samp{#define}, @samp{defined} will recommence returning 1. + +@findex #ifdef +@findex #ifndef +Conditionals that test whether just one name is defined are very common, +so there are two special short conditional commands for this case. + +@table @code +@item #ifdef @var{name} +is equivalent to @samp{#if defined (@var{name})}. + +@item #ifndef @var{name} +is equivalent to @samp{#if ! defined (@var{name})}. +@end table + +Macro definitions can vary between compilations for several reasons. + +@itemize @bullet +@item +Some macros are predefined on each kind of machine. For example, on a +Vax, the name @samp{vax} is a predefined macro. On other machines, it +would not be defined. + +@item +Many more macros are defined by system header files. Different +systems and machines define different macros, or give them different +values. It is useful to test these macros with conditionals to avoid +using a system feature on a machine where it is not implemented. + +@item +Macros are a common way of allowing users to customize a program for +different machines or applications. For example, the macro +@samp{BUFSIZE} might be defined in a configuration file for your +program that is included as a header file in each source file. You +would use @samp{BUFSIZE} in a preprocessor conditional in order to +generate different code depending on the chosen configuration. + +@item +Macros can be defined or undefined with @samp{-D} and @samp{-U} +command options when you compile the program. You can arrange to +compile the same source file into two different programs by choosing +a macro name to specify which program you want, writing conditionals +to test whether or how this macro is defined, and then controlling +the state of the macro with compiler command options. +@xref{Invocation}. +@end itemize + +@ifinfo +Assertions are usually predefined, but can be defined with preprocessor +commands or command-line options. +@end ifinfo + +@node Assertions +@subsection Assertions + +@cindex assertions +@dfn{Assertions} are a more systematic alternative to macros in writing +conditionals to test what sort of computer or system the compiled +program will run on. Assertions are usually predefined, but you can +define them with preprocessor commands or command-line options. + +@cindex predicates +The macros traditionally used to describe the type of target are not +classified in any way according to which question they answer; they may +indicate a hardware architecture, a particular hardware model, an +operating system, a particular version of an operating system, or +specific configuration options. These are jumbled together in a single +namespace. In contrast, each assertion consists of a named question and +an answer. The question is usually called the @dfn{predicate}. +An assertion looks like this: + +@example +#@var{predicate} (@var{answer}) +@end example + +@noindent +You must use a properly formed identifier for @var{predicate}. The +value of @var{answer} can be any sequence of words; all characters are +significant except for leading and trailing whitespace, and differences +in internal whitespace sequences are ignored. Thus, @samp{x + y} is +different from @samp{x+y} but equivalent to @samp{x + y}. @samp{)} is +not allowed in an answer. + +@cindex testing predicates +Here is a conditional to test whether the answer @var{answer} is asserted +for the predicate @var{predicate}: + +@example +#if #@var{predicate} (@var{answer}) +@end example + +@noindent +There may be more than one answer asserted for a given predicate. If +you omit the answer, you can test whether @emph{any} answer is asserted +for @var{predicate}: + +@example +#if #@var{predicate} +@end example + +@findex #system +@findex #machine +@findex #cpu +Most of the time, the assertions you test will be predefined assertions. +GNU C provides three predefined predicates: @code{system}, @code{cpu}, +and @code{machine}. @code{system} is for assertions about the type of +software, @code{cpu} describes the type of computer architecture, and +@code{machine} gives more information about the computer. For example, +on a GNU system, the following assertions would be true: + +@example +#system (gnu) +#system (mach) +#system (mach 3) +#system (mach 3.@var{subversion}) +#system (hurd) +#system (hurd @var{version}) +@end example + +@noindent +and perhaps others. The alternatives with +more or less version information let you ask more or less detailed +questions about the type of system software. + +On a Unix system, you would find @code{#system (unix)} and perhaps one of: +@code{#system (aix)}, @code{#system (bsd)}, @code{#system (hpux)}, +@code{#system (lynx)}, @code{#system (mach)}, @code{#system (posix)}, +@code{#system (svr3)}, @code{#system (svr4)}, or @code{#system (xpg4)} +with possible version numbers following. + +Other values for @code{system} are @code{#system (mvs)} +and @code{#system (vms)}. + +@strong{Portability note:} Many Unix C compilers provide only one answer +for the @code{system} assertion: @code{#system (unix)}, if they support +assertions at all. This is less than useful. + +An assertion with a multi-word answer is completely different from several +assertions with individual single-word answers. For example, the presence +of @code{system (mach 3.0)} does not mean that @code{system (3.0)} is true. +It also does not directly imply @code{system (mach)}, but in GNU C, that +last will normally be asserted as well. + +The current list of possible assertion values for @code{cpu} is: +@code{#cpu (a29k)}, @code{#cpu (alpha)}, @code{#cpu (arm)}, @code{#cpu +(clipper)}, @code{#cpu (convex)}, @code{#cpu (elxsi)}, @code{#cpu +(tron)}, @code{#cpu (h8300)}, @code{#cpu (i370)}, @code{#cpu (i386)}, +@code{#cpu (i860)}, @code{#cpu (i960)}, @code{#cpu (m68k)}, @code{#cpu +(m88k)}, @code{#cpu (mips)}, @code{#cpu (ns32k)}, @code{#cpu (hppa)}, +@code{#cpu (pyr)}, @code{#cpu (ibm032)}, @code{#cpu (rs6000)}, +@code{#cpu (sh)}, @code{#cpu (sparc)}, @code{#cpu (spur)}, @code{#cpu +(tahoe)}, @code{#cpu (vax)}, @code{#cpu (we32000)}. + +@findex #assert +You can create assertions within a C program using @samp{#assert}, like +this: + +@example +#assert @var{predicate} (@var{answer}) +@end example + +@noindent +(Note the absence of a @samp{#} before @var{predicate}.) + +@cindex unassert +@cindex assertions, undoing +@cindex retracting assertions +@findex #unassert +Each time you do this, you assert a new true answer for @var{predicate}. +Asserting one answer does not invalidate previously asserted answers; +they all remain true. The only way to remove an assertion is with +@samp{#unassert}. @samp{#unassert} has the same syntax as +@samp{#assert}. You can also remove all assertions about +@var{predicate} like this: + +@example +#unassert @var{predicate} +@end example + +You can also add or cancel assertions using command options +when you run @code{gcc} or @code{cpp}. @xref{Invocation}. + +@node #error Command +@subsection The @samp{#error} and @samp{#warning} Commands + +@findex #error +The command @samp{#error} causes the preprocessor to report a fatal +error. The rest of the line that follows @samp{#error} is used as the +error message. + +You would use @samp{#error} inside of a conditional that detects a +combination of parameters which you know the program does not properly +support. For example, if you know that the program will not run +properly on a Vax, you might write + +@smallexample +@group +#ifdef __vax__ +#error Won't work on Vaxen. See comments at get_last_object. +#endif +@end group +@end smallexample + +@noindent +@xref{Nonstandard Predefined}, for why this works. + +If you have several configuration parameters that must be set up by +the installation in a consistent way, you can use conditionals to detect +an inconsistency and report it with @samp{#error}. For example, + +@smallexample +#if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \ + || HASH_TABLE_SIZE % 5 == 0 +#error HASH_TABLE_SIZE should not be divisible by a small prime +#endif +@end smallexample + +@findex #warning +The command @samp{#warning} is like the command @samp{#error}, but causes +the preprocessor to issue a warning and continue preprocessing. The rest of +the line that follows @samp{#warning} is used as the warning message. + +You might use @samp{#warning} in obsolete header files, with a message +directing the user to the header file which should be used instead. + +@node Combining Sources, Other Commands, Conditionals, Top +@section Combining Source Files + +@cindex line control +One of the jobs of the C preprocessor is to inform the C compiler of where +each line of C code came from: which source file and which line number. + +C code can come from multiple source files if you use @samp{#include}; +both @samp{#include} and the use of conditionals and macros can cause +the line number of a line in the preprocessor output to be different +from the line's number in the original source file. You will appreciate +the value of making both the C compiler (in error messages) and symbolic +debuggers such as GDB use the line numbers in your source file. + +The C preprocessor builds on this feature by offering a command by which +you can control the feature explicitly. This is useful when a file for +input to the C preprocessor is the output from another program such as the +@code{bison} parser generator, which operates on another file that is the +true source file. Parts of the output from @code{bison} are generated from +scratch, other parts come from a standard parser file. The rest are copied +nearly verbatim from the source file, but their line numbers in the +@code{bison} output are not the same as their original line numbers. +Naturally you would like compiler error messages and symbolic debuggers to +know the original source file and line number of each line in the +@code{bison} input. + +@findex #line +@code{bison} arranges this by writing @samp{#line} commands into the output +file. @samp{#line} is a command that specifies the original line number +and source file name for subsequent input in the current preprocessor input +file. @samp{#line} has three variants: + +@table @code +@item #line @var{linenum} +Here @var{linenum} is a decimal integer constant. This specifies that +the line number of the following line of input, in its original source file, +was @var{linenum}. + +@item #line @var{linenum} @var{filename} +Here @var{linenum} is a decimal integer constant and @var{filename} +is a string constant. This specifies that the following line of input +came originally from source file @var{filename} and its line number there +was @var{linenum}. Keep in mind that @var{filename} is not just a +file name; it is surrounded by doublequote characters so that it looks +like a string constant. + +@item #line @var{anything else} +@var{anything else} is checked for macro calls, which are expanded. +The result should be a decimal integer constant followed optionally +by a string constant, as described above. +@end table + +@samp{#line} commands alter the results of the @samp{__FILE__} and +@samp{__LINE__} predefined macros from that point on. @xref{Standard +Predefined}. + +The output of the preprocessor (which is the input for the rest of the +compiler) contains commands that look much like @samp{#line} commands. +They start with just @samp{#} instead of @samp{#line}, but this is +followed by a line number and file name as in @samp{#line}. @xref{Output}. + +@node Other Commands, Output, Combining Sources, Top +@section Miscellaneous Preprocessor Commands + +@cindex null command +This section describes three additional preprocessor commands. They are +not very useful, but are mentioned for completeness. + +The @dfn{null command} consists of a @samp{#} followed by a Newline, with +only whitespace (including comments) in between. A null command is +understood as a preprocessor command but has no effect on the preprocessor +output. The primary significance of the existence of the null command is +that an input line consisting of just a @samp{#} will produce no output, +rather than a line of output containing just a @samp{#}. Supposedly +some old C programs contain such lines. + +@findex #pragma +The ANSI standard specifies that the @samp{#pragma} command has an +arbitrary, implementation-defined effect. In the GNU C preprocessor, +@samp{#pragma} commands are not used, except for @samp{#pragma once} +(@pxref{Once-Only}). However, they are left in the preprocessor output, +so they are available to the compilation pass. + +@findex #ident +The @samp{#ident} command is supported for compatibility with certain +other systems. It is followed by a line of text. On some systems, the +text is copied into a special place in the object file; on most systems, +the text is ignored and this command has no effect. Typically +@samp{#ident} is only used in header files supplied with those systems +where it is meaningful. + +@node Output, Invocation, Other Commands, Top +@section C Preprocessor Output + +@cindex output format +The output from the C preprocessor looks much like the input, except +that all preprocessor command lines have been replaced with blank lines +and all comments with spaces. Whitespace within a line is not altered; +however, a space is inserted after the expansions of most macro calls. + +Source file name and line number information is conveyed by lines of +the form + +@example +# @var{linenum} @var{filename} @var{flags} +@end example + +@noindent +which are inserted as needed into the middle of the input (but never +within a string or character constant). Such a line means that the +following line originated in file @var{filename} at line @var{linenum}. + +After the file name comes zero or more flags, which are @samp{1}, +@samp{2} or @samp{3}. If there are multiple flags, spaces separate +them. Here is what the flags mean: + +@table @samp +@item 1 +This indicates the start of a new file. +@item 2 +This indicates returning to a file (after having included another file). +@item 3 +This indicates that the following text comes from a system header file, +so certain warnings should be suppressed. +@end table + +@node Invocation, Concept Index, Output, Top +@section Invoking the C Preprocessor +@cindex invocation of the preprocessor + +Most often when you use the C preprocessor you will not have to invoke it +explicitly: the C compiler will do so automatically. However, the +preprocessor is sometimes useful on its own. + +The C preprocessor expects two file names as arguments, @var{infile} and +@var{outfile}. The preprocessor reads @var{infile} together with any other +files it specifies with @samp{#include}. All the output generated by the +combined input files is written in @var{outfile}. + +Either @var{infile} or @var{outfile} may be @samp{-}, which as @var{infile} +means to read from standard input and as @var{outfile} means to write to +standard output. Also, if @var{outfile} or both file names are omitted, +the standard output and standard input are used for the omitted file names. + +@cindex options +Here is a table of command options accepted by the C preprocessor. +These options can also be given when compiling a C program; they are +passed along automatically to the preprocessor when it is invoked by the +compiler. + +@table @samp +@item -P +@findex -P +Inhibit generation of @samp{#}-lines with line-number information in +the output from the preprocessor (@pxref{Output}). This might be +useful when running the preprocessor on something that is not C code +and will be sent to a program which might be confused by the +@samp{#}-lines. + +@item -C +@findex -C +Do not discard comments: pass them through to the output file. +Comments appearing in arguments of a macro call will be copied to the +output before the expansion of the macro call. + +@item -traditional +@findex -traditional +Try to imitate the behavior of old-fashioned C, as opposed to ANSI C. + +@itemize @bullet +@item +Traditional macro expansion pays no attention to singlequote or +doublequote characters; macro argument symbols are replaced by the +argument values even when they appear within apparent string or +character constants. + +@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. + +@item +However, traditionally the end of the line terminates a string or +character constant, with no error. + +@item +In traditional C, a comment is equivalent to no text at all. (In ANSI +C, a comment counts as whitespace.) + +@item +Traditional C does not have the concept of a ``preprocessing number''. +It considers @samp{1.0e+4} to be three tokens: @samp{1.0e}, @samp{+}, +and @samp{4}. + +@item +A macro is not suppressed within its own definition, in traditional C. +Thus, any macro that is used recursively inevitably causes an error. + +@item +The character @samp{#} has no special meaning within a macro definition +in traditional C. + +@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 ANSI C.) + +@item +Traditionally, @samp{\} inside a macro argument suppresses the syntactic +significance of the following character. +@end itemize + +@item -trigraphs +@findex -trigraphs +Process ANSI standard trigraph sequences. These are three-character +sequences, all starting with @samp{??}, that are defined by ANSI C to +stand for single characters. For example, @samp{??/} stands for +@samp{\}, so @samp{'??/n'} is a character constant for a newline. +Strictly speaking, the GNU C preprocessor does not support all +programs in ANSI Standard C unless @samp{-trigraphs} is used, but if +you ever notice the difference it will be with relief. + +You don't want to know any more about trigraphs. + +@item -pedantic +@findex -pedantic +Issue warnings required by the ANSI C standard in certain cases such +as when text other than a comment follows @samp{#else} or @samp{#endif}. + +@item -pedantic-errors +@findex -pedantic-errors +Like @samp{-pedantic}, except that errors are produced rather than +warnings. + +@item -Wtrigraphs +@findex -Wtrigraphs +Warn if any trigraphs are encountered (assuming they are enabled). + +@item -Wcomment +@findex -Wcomment +@ignore +@c "Not worth documenting" both singular and plural forms of this +@c option, per RMS. But also unclear which is better; hence may need to +@c switch this at some future date. pesch@cygnus.com, 2jan92. +@itemx -Wcomments +(Both forms have the same effect). +@end ignore +Warn whenever a comment-start sequence @samp{/*} appears in a comment. + +@item -Wall +@findex -Wall +Requests both @samp{-Wtrigraphs} and @samp{-Wcomment} (but not +@samp{-Wtraditional}). + +@item -Wtraditional +@findex -Wtraditional +Warn about certain constructs that behave differently in traditional and +ANSI C. + +@item -I @var{directory} +@findex -I +Add the directory @var{directory} to the end of the list of +directories to be searched for header files (@pxref{Include Syntax}). +This can be used to override a system header file, substituting your +own version, since these directories are searched before the system +header file directories. If you use more than one @samp{-I} option, +the directories are scanned in left-to-right order; the standard +system directories come after. + +@item -I- +Any directories specified with @samp{-I} options before the @samp{-I-} +option are searched only for the case of @samp{#include "@var{file}"}; +they are not searched for @samp{#include <@var{file}>}. + +If additional directories are specified with @samp{-I} options after +the @samp{-I-}, these directories are searched for all @samp{#include} +commands. + +In addition, the @samp{-I-} option inhibits the use of the current +directory as the first search directory for @samp{#include "@var{file}"}. +Therefore, the current directory is searched only if it is requested +explicitly with @samp{-I.}. Specifying both @samp{-I-} and @samp{-I.} +allows you to control precisely which directories are searched before +the current one and which are searched after. + +@item -nostdinc +@findex -nostdinc +Do not search the standard system directories for header files. +Only the directories you have specified with @samp{-I} options +(and the current directory, if appropriate) are searched. + +@item -nostdinc++ +@findex -nostdinc++ +Do not search for header files in the C++-specific standard directories, +but do still search the other standard directories. +(This option is used when building libg++.) + +@item -D @var{name} +@findex -D +Predefine @var{name} as a macro, with definition @samp{1}. + +@item -D @var{name}=@var{definition} +Predefine @var{name} as a macro, with definition @var{definition}. +There are no restrictions on the contents of @var{definition}, but if +you are invoking the preprocessor from a shell or shell-like program you +may need to use the shell's quoting syntax to protect characters such as +spaces that have a meaning in the shell syntax. If you use more than +one @samp{-D} for the same @var{name}, the rightmost definition takes +effect. + +@item -U @var{name} +@findex -U +Do not predefine @var{name}. If both @samp{-U} and @samp{-D} are +specified for one name, the @samp{-U} beats the @samp{-D} and the name +is not predefined. + +@item -undef +@findex -undef +Do not predefine any nonstandard macros. + +@item -A @var{predicate}(@var{answer}) +@findex -A +Make an assertion with the predicate @var{predicate} and answer +@var{answer}. @xref{Assertions}. + +@noindent +You can use @samp{-A-} to disable all predefined assertions; it also +undefines all predefined macros that identify the type of target system. + +@item -dM +@findex -dM +Instead of outputting the result of preprocessing, output a list of +@samp{#define} commands for all the macros defined during the +execution of the preprocessor, including predefined macros. This gives +you a way of finding out what is predefined in your version of the +preprocessor; assuming you have no file @samp{foo.h}, the command + +@example +touch foo.h; cpp -dM foo.h +@end example + +@noindent +will show the values of any predefined macros. + +@item -dD +@findex -dD +Like @samp{-dM} except in two respects: it does @emph{not} include the +predefined macros, and it outputs @emph{both} the @samp{#define} +commands and the result of preprocessing. Both kinds of output go to +the standard output file. + +@item -M [-MG] +@findex -M +Instead of outputting the result of preprocessing, output a rule +suitable for @code{make} describing the dependencies of the main +source file. The preprocessor outputs one @code{make} rule containing +the object file name for that source file, a colon, and the names of +all the included files. If there are many included files then the +rule is split into several lines using @samp{\}-newline. + +@samp{-MG} says to treat missing header files as generated files and assume +they live in the same directory as the source file. It must be specified +in addition to @samp{-M}. + +This feature is used in automatic updating of makefiles. + +@item -MM [-MG] +@findex -MM +Like @samp{-M} but mention only the files included with @samp{#include +"@var{file}"}. System header files included with @samp{#include +<@var{file}>} are omitted. + +@item -MD @var{file} +@findex -MD +Like @samp{-M} but the dependency information is written to @var{file}. +This is in addition to compiling the file as specified---@samp{-MD} does +not inhibit ordinary compilation the way @samp{-M} does. + +When invoking gcc, do not specify the @var{file} argument. +Gcc will create file names made by replacing ".c" with ".d" at +the end of the input file names. + +In Mach, you can use the utility @code{md} to merge multiple dependency +files into a single dependency file suitable for using with the @samp{make} +command. + +@item -MMD @var{file} +@findex -MMD +Like @samp{-MD} except mention only user header files, not system +header files. + +@item -H +@findex -H +Print the name of each header file used, in addition to other normal +activities. + +@item -imacros @var{file} +@findex -imacros +Process @var{file} as input, discarding the resulting output, before +processing the regular input file. Because the output generated from +@var{file} is discarded, the only effect of @samp{-imacros @var{file}} +is to make the macros defined in @var{file} available for use in the +main input. + +@item -include @var{file} +@findex -include +Process @var{file} as input, and include all the resulting output, +before processing the regular input file. + +@item -idirafter @var{dir} +@findex -idirafter +@cindex second include path +Add the directory @var{dir} to the second include path. The directories +on the second include path are searched when a header file is not found +in any of the directories in the main include path (the one that +@samp{-I} adds to). + +@item -iprefix @var{prefix} +@findex -iprefix +Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix} +options. + +@item -iwithprefix @var{dir} +@findex -iwithprefix +Add a directory to the second include path. The directory's name is +made by concatenating @var{prefix} and @var{dir}, where @var{prefix} +was specified previously with @samp{-iprefix}. + +@item -isystem @var{dir} +@findex -isystem +Add a directory to the beginning of the second include path, marking it +as a system directory, so that it gets the same special treatment as +is applied to the standard system directories. + +@item -lang-c +@itemx -lang-c++ +@itemx -lang-objc +@itemx -lang-objc++ +@findex -lang-c +@findex -lang-c++ +@findex -lang-objc +@findex -lang-objc++ +Specify the source language. @samp{-lang-c++} makes the preprocessor +handle C++ comment syntax (comments may begin with @samp{//}, in which +case they end at end of line), and includes extra default include +directories for C++; and @samp{-lang-objc} enables the Objective C +@samp{#import} command. @samp{-lang-c} explicitly turns off both of +these extensions, and @samp{-lang-objc++} enables both. + +These options are generated by the compiler driver @code{gcc}, but not +passed from the @samp{gcc} command line. + +@item -lint +Look for commands to the program checker @code{lint} embedded in +comments, and emit them preceded by @samp{#pragma lint}. For example, +the comment @samp{/* NOTREACHED */} becomes @samp{#pragma lint +NOTREACHED}. + +This option is available only when you call @code{cpp} directly; +@code{gcc} will not pass it from its command line. + +@item -$ +@findex -$ +Forbid the use of @samp{$} in identifiers. This is required for ANSI +conformance. @code{gcc} automatically supplies this option to the +preprocessor if you specify @samp{-ansi}, but @code{gcc} doesn't +recognize the @samp{-$} option itself---to use it without the other +effects of @samp{-ansi}, you must call the preprocessor directly. + +@end table + +@node Concept Index, Index, Invocation, Top +@unnumbered Concept Index +@printindex cp + +@node Index,, Concept Index, Top +@unnumbered Index of Commands, Macros and Options +@printindex fn + +@contents +@bye diff --git a/gnu/usr.bin/cc/doc/extend.texi b/gnu/usr.bin/cc/doc/extend.texi new file mode 100644 index 0000000..13e8aa4 --- /dev/null +++ b/gnu/usr.bin/cc/doc/extend.texi @@ -0,0 +1,2919 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node C Extensions +@chapter Extensions to the C Language Family +@cindex extensions, C language +@cindex C language extensions + +GNU C provides several language features not found in ANSI standard C. +(The @samp{-pedantic} option directs GNU CC to print a warning message if +any of these features is used.) To test for the availability of these +features in conditional compilation, check for a predefined macro +@code{__GNUC__}, which is always defined under GNU CC. + +These extensions are available in C and Objective C. Most of them are +also available in C++. @xref{C++ Extensions,,Extensions to the +C++ Language}, for extensions that apply @emph{only} to C++. + +@c The only difference between the two versions of this menu is that the +@c version for clear INTERNALS has an extra node, "Constraints" (which +@c appears in a separate chapter in the other version of the manual). +@ifset INTERNALS +@menu +* Statement Exprs:: Putting statements and declarations inside expressions. +* Local Labels:: Labels local to a statement-expression. +* Labels as Values:: Getting pointers to labels, and computed gotos. +* Nested Functions:: As in Algol and Pascal, lexical scoping of functions. +* Constructing Calls:: Dispatching a call to another function. +* Naming Types:: Giving a name to the type of some expression. +* Typeof:: @code{typeof}: referring to the type of an expression. +* Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues. +* Conditionals:: Omitting the middle operand of a @samp{?:} expression. +* Long Long:: Double-word integers---@code{long long int}. +* Complex:: Data types for complex numbers. +* Zero Length:: Zero-length arrays. +* Variable Length:: Arrays whose length is computed at run time. +* Macro Varargs:: Macros with variable number of arguments. +* Subscripting:: Any array can be subscripted, even if not an lvalue. +* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. +* Initializers:: Non-constant initializers. +* Constructors:: Constructor expressions give structures, unions + or arrays as values. +* Labeled Elements:: Labeling elements of initializers. +* Cast to Union:: Casting to union type from any member of the union. +* Case Ranges:: `case 1 ... 9' and such. +* Function Attributes:: Declaring that functions have no side effects, + or that they can never return. +* Function Prototypes:: Prototype declarations and old-style definitions. +* Dollar Signs:: Dollar sign is allowed in identifiers. +* Character Escapes:: @samp{\e} stands for the character @key{ESC}. +* Variable Attributes:: Specifying attributes of variables. +* Alignment:: Inquiring about the alignment of a type or variable. +* Inline:: Defining inline functions (as fast as macros). +* Extended Asm:: Assembler instructions with C expressions as operands. + (With them you can define ``built-in'' functions.) +* Asm Labels:: Specifying the assembler name to use for a C symbol. +* Explicit Reg Vars:: Defining variables residing in specified registers. +* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. +* Incomplete Enums:: @code{enum foo;}, with details to follow. +* Function Names:: Printable strings which are the name of the current + function. +@end menu +@end ifset +@ifclear INTERNALS +@menu +* Statement Exprs:: Putting statements and declarations inside expressions. +* Local Labels:: Labels local to a statement-expression. +* Labels as Values:: Getting pointers to labels, and computed gotos. +* Nested Functions:: As in Algol and Pascal, lexical scoping of functions. +* Constructing Calls:: Dispatching a call to another function. +* Naming Types:: Giving a name to the type of some expression. +* Typeof:: @code{typeof}: referring to the type of an expression. +* Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues. +* Conditionals:: Omitting the middle operand of a @samp{?:} expression. +* Long Long:: Double-word integers---@code{long long int}. +* Complex:: Data types for complex numbers. +* Zero Length:: Zero-length arrays. +* Variable Length:: Arrays whose length is computed at run time. +* Macro Varargs:: Macros with variable number of arguments. +* Subscripting:: Any array can be subscripted, even if not an lvalue. +* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. +* Initializers:: Non-constant initializers. +* Constructors:: Constructor expressions give structures, unions + or arrays as values. +* Labeled Elements:: Labeling elements of initializers. +* Cast to Union:: Casting to union type from any member of the union. +* Case Ranges:: `case 1 ... 9' and such. +* Function Attributes:: Declaring that functions have no side effects, + or that they can never return. +* Function Prototypes:: Prototype declarations and old-style definitions. +* Dollar Signs:: Dollar sign is allowed in identifiers. +* Character Escapes:: @samp{\e} stands for the character @key{ESC}. +* Variable Attributes:: Specifying attributes of variables. +* Alignment:: Inquiring about the alignment of a type or variable. +* Inline:: Defining inline functions (as fast as macros). +* Extended Asm:: Assembler instructions with C expressions as operands. + (With them you can define ``built-in'' functions.) +* Constraints:: Constraints for asm operands +* Asm Labels:: Specifying the assembler name to use for a C symbol. +* Explicit Reg Vars:: Defining variables residing in specified registers. +* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. +* Incomplete Enums:: @code{enum foo;}, with details to follow. +* Function Names:: Printable strings which are the name of the current + function. +@end menu +@end ifclear + +@node Statement Exprs +@section Statements and Declarations in Expressions +@cindex statements inside expressions +@cindex declarations inside expressions +@cindex expressions containing statements +@cindex macros, statements in expressions + +@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. + +Recall that a compound statement is a sequence of statements surrounded +by braces; in this construct, parentheses go around the braces. For +example: + +@example +(@{ int y = foo (); int z; + if (y > 0) z = y; + else z = - y; + z; @}) +@end example + +@noindent +is a valid (though slightly more complex than necessary) expression +for the absolute value of @code{foo ()}. + +The last thing in the compound statement should be an expression +followed by a semicolon; the value of this subexpression serves as the +value of the entire construct. (If you use some other kind of statement +last within the braces, the construct has type @code{void}, and thus +effectively no value.) + +This feature is especially useful in making macro definitions ``safe'' (so +that they evaluate each operand exactly once). For example, the +``maximum'' function is commonly defined as a macro in standard C as +follows: + +@example +#define max(a,b) ((a) > (b) ? (a) : (b)) +@end example + +@noindent +@cindex side effects, macro argument +But this definition computes either @var{a} or @var{b} twice, with bad +results if the operand has side effects. In GNU C, if you know the +type of the operands (here let's assume @code{int}), you can define +the macro safely as follows: + +@example +#define maxint(a,b) \ + (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) +@end example + +Embedded statements are not allowed in constant expressions, such as +the value of an enumeration constant, the width of a bit field, or +the initial value of a static variable. + +If you don't know the type of the operand, you can still do this, but you +must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming +Types}). + +@node Local Labels +@section Locally Declared Labels +@cindex local labels +@cindex macros, local labels + +Each statement expression is a scope in which @dfn{local labels} can be +declared. A local label is simply an identifier; you can jump to it +with an ordinary @code{goto} statement, but only from within the +statement expression it belongs to. + +A local label declaration looks like this: + +@example +__label__ @var{label}; +@end example + +@noindent +or + +@example +__label__ @var{label1}, @var{label2}, @dots{}; +@end example + +Local label declarations must come at the beginning of the statement +expression, right after the @samp{(@{}, before any ordinary +declarations. + +The label declaration defines the label @emph{name}, but does not define +the label itself. You must do this in the usual way, with +@code{@var{label}:}, within the statements of the statement expression. + +The local label feature is useful because statement expressions are +often used in macros. If the macro contains nested loops, a @code{goto} +can be useful for breaking out of them. However, an ordinary label +whose scope is the whole function cannot be used: if the macro can be +expanded several times in one function, the label will be multiply +defined in that function. A local label avoids this problem. For +example: + +@example +#define SEARCH(array, target) \ +(@{ \ + __label__ found; \ + typeof (target) _SEARCH_target = (target); \ + typeof (*(array)) *_SEARCH_array = (array); \ + int i, j; \ + int value; \ + for (i = 0; i < max; i++) \ + for (j = 0; j < max; j++) \ + if (_SEARCH_array[i][j] == _SEARCH_target) \ + @{ value = i; goto found; @} \ + value = -1; \ + found: \ + value; \ +@}) +@end example + +@node Labels as Values +@section Labels as Values +@cindex labels as values +@cindex computed gotos +@cindex goto with computed label +@cindex address of a label + +You can get the address of a label defined in the current function +(or a containing function) with the unary operator @samp{&&}. The +value has type @code{void *}. This value is a constant and can be used +wherever a constant of that type is valid. For example: + +@example +void *ptr; +@dots{} +ptr = &&foo; +@end example + +To use these values, you need to be able to jump to one. This is done +with the computed goto statement@footnote{The analogous feature in +Fortran is called an assigned goto, but that name seems inappropriate in +C, where one can do more than simply store label addresses in label +variables.}, @code{goto *@var{exp};}. For example, + +@example +goto *ptr; +@end example + +@noindent +Any expression of type @code{void *} is allowed. + +One way of using these constants is in initializing a static array that +will serve as a jump table: + +@example +static void *array[] = @{ &&foo, &&bar, &&hack @}; +@end example + +Then you can select a label with indexing, like this: + +@example +goto *array[i]; +@end example + +@noindent +Note that this does not check whether the subscript is in bounds---array +indexing in C never does that. + +Such an array of label values serves a purpose much like that of the +@code{switch} statement. The @code{switch} statement is cleaner, so +use that rather than an array unless the problem does not fit a +@code{switch} statement very well. + +Another use of label values is in an interpreter for threaded code. +The labels within the interpreter function can be stored in the +threaded code for super-fast dispatching. + +You can use this mechanism to jump to code in a different function. If +you do that, totally unpredictable things will happen. The best way to +avoid this is to store the label address only in automatic variables and +never pass it as an argument. + +@node Nested Functions +@section Nested Functions +@cindex nested functions +@cindex downward funargs +@cindex thunks + +A @dfn{nested function} is a function defined inside another function. +(Nested functions are not supported for GNU C++.) The nested function's +name is local to the block where it is defined. For example, here we +define a nested function named @code{square}, and call it twice: + +@example +@group +foo (double a, double b) +@{ + double square (double z) @{ return z * z; @} + + return square (a) + square (b); +@} +@end group +@end example + +The nested function can access all the variables of the containing +function that are visible at the point of its definition. This is +called @dfn{lexical scoping}. For example, here we show a nested +function which uses an inherited variable named @code{offset}: + +@example +bar (int *array, int offset, int size) +@{ + int access (int *array, int index) + @{ return array[index + offset]; @} + int i; + @dots{} + for (i = 0; i < size; i++) + @dots{} access (array, i) @dots{} +@} +@end example + +Nested function definitions are permitted within functions in the places +where variable definitions are allowed; that is, in any block, before +the first statement in the block. + +It is possible to call the nested function from outside the scope of its +name by storing its address or passing the address to another function: + +@example +hack (int *array, int size) +@{ + void store (int index, int value) + @{ array[index] = value; @} + + intermediate (store, size); +@} +@end example + +Here, the function @code{intermediate} receives the address of +@code{store} as an argument. If @code{intermediate} calls @code{store}, +the arguments given to @code{store} are used to store into @code{array}. +But this technique works only so long as the containing function +(@code{hack}, in this example) does not exit. + +If you try to call the nested function through its address after the +containing function has exited, all hell will break loose. If you try +to call it after a containing scope level has exited, and if it refers +to some of the variables that are no longer in scope, you may be lucky, +but it's not wise to take the risk. If, however, the nested function +does not refer to anything that has gone out of scope, you should be +safe. + +GNU CC implements taking the address of a nested function using a +technique called @dfn{trampolines}. A paper describing them is +available from @samp{maya.idiap.ch} in directory @file{pub/tmb}, +file @file{usenix88-lexic.ps.Z}. + +A nested function can jump to a label inherited from a containing +function, provided the label was explicitly declared in the containing +function (@pxref{Local Labels}). Such a jump returns instantly to the +containing function, exiting the nested function which did the +@code{goto} and any intermediate functions as well. Here is an example: + +@example +@group +bar (int *array, int offset, int size) +@{ + __label__ failure; + int access (int *array, int index) + @{ + if (index > size) + goto failure; + return array[index + offset]; + @} + int i; + @dots{} + for (i = 0; i < size; i++) + @dots{} access (array, i) @dots{} + @dots{} + return 0; + + /* @r{Control comes here from @code{access} + if it detects an error.} */ + failure: + return -1; +@} +@end group +@end example + +A nested function always has internal linkage. Declaring one with +@code{extern} is erroneous. If you need to declare the nested function +before its definition, use @code{auto} (which is otherwise meaningless +for function declarations). + +@example +bar (int *array, int offset, int size) +@{ + __label__ failure; + auto int access (int *, int); + @dots{} + int access (int *array, int index) + @{ + if (index > size) + goto failure; + return array[index + offset]; + @} + @dots{} +@} +@end example + +@node Constructing Calls +@section Constructing Function Calls +@cindex constructing calls +@cindex forwarding calls + +Using the built-in functions described below, you can record +the arguments a function received, and call another function +with the same arguments, without knowing the number or types +of the arguments. + +You can also record the return value of that function call, +and later return that value, without knowing what data type +the function tried to return (as long as your caller expects +that data type). + +@table @code +@findex __builtin_apply_args +@item __builtin_apply_args () +This built-in function returns a pointer of type @code{void *} to data +describing how to perform a call with the same arguments as were passed +to the current function. + +The function saves the arg pointer register, structure value address, +and all registers that might be used to pass arguments to a function +into a block of memory allocated on the stack. Then it returns the +address of that block. + +@findex __builtin_apply +@item __builtin_apply (@var{function}, @var{arguments}, @var{size}) +This built-in function invokes @var{function} (type @code{void (*)()}) +with a copy of the parameters described by @var{arguments} (type +@code{void *}) and @var{size} (type @code{int}). + +The value of @var{arguments} should be the value returned by +@code{__builtin_apply_args}. The argument @var{size} specifies the size +of the stack argument data, in bytes. + +This function returns a pointer of type @code{void *} to data describing +how to return whatever value was returned by @var{function}. The data +is saved in a block of memory allocated on the stack. + +It is not always simple to compute the proper value for @var{size}. The +value is used by @code{__builtin_apply} to compute the amount of data +that should be pushed on the stack and copied from the incoming argument +area. + +@findex __builtin_return +@item __builtin_return (@var{result}) +This built-in function returns the value described by @var{result} from +the containing function. You should specify, for @var{result}, a value +returned by @code{__builtin_apply}. +@end table + +@node Naming Types +@section Naming an Expression's Type +@cindex naming types + +You can give a name to the type of an expression using a @code{typedef} +declaration with an initializer. Here is how to define @var{name} as a +type name for the type of @var{exp}: + +@example +typedef @var{name} = @var{exp}; +@end example + +This is useful in conjunction with the statements-within-expressions +feature. Here is how the two together can be used to define a safe +``maximum'' macro that operates on any arithmetic type: + +@example +#define max(a,b) \ + (@{typedef _ta = (a), _tb = (b); \ + _ta _a = (a); _tb _b = (b); \ + _a > _b ? _a : _b; @}) +@end example + +@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 +@findex sizeof +@cindex macros, types of arguments + +Another way to refer to the type of an expression is with @code{typeof}. +The syntax of using of this keyword looks like @code{sizeof}, but the +construct acts semantically like a type name defined with @code{typedef}. + +There are two ways of writing the argument to @code{typeof}: with an +expression or with a type. Here is an example with an expression: + +@example +typeof (x[0](1)) +@end example + +@noindent +This assumes that @code{x} is an array of functions; the type described +is that of the values of the functions. + +Here is an example with a typename as the argument: + +@example +typeof (int *) +@end example + +@noindent +Here the type described is that of pointers to @code{int}. + +If you are writing a header file that must work when included in ANSI C +programs, write @code{__typeof__} instead of @code{typeof}. +@xref{Alternate Keywords}. + +A @code{typeof}-construct can be used anywhere a typedef name could be +used. For example, you can use it in a declaration, in a cast, or inside +of @code{sizeof} or @code{typeof}. + +@itemize @bullet +@item +This declares @code{y} with the type of what @code{x} points to. + +@example +typeof (*x) y; +@end example + +@item +This declares @code{y} as an array of such values. + +@example +typeof (*x) y[4]; +@end example + +@item +This declares @code{y} as an array of pointers to characters: + +@example +typeof (typeof (char *)[4]) y; +@end example + +@noindent +It is equivalent to the following traditional C declaration: + +@example +char *y[4]; +@end example + +To see the meaning of the declaration using @code{typeof}, and why it +might be a useful way to write, let's rewrite it with these macros: + +@example +#define pointer(T) typeof(T *) +#define array(T, N) typeof(T [N]) +@end example + +@noindent +Now the declaration can be rewritten this way: + +@example +array (pointer (char), 4) y; +@end example + +@noindent +Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 +pointers to @code{char}. +@end itemize + +@node Lvalues +@section Generalized Lvalues +@cindex compound expressions as lvalues +@cindex expressions, compound, as lvalues +@cindex conditional expressions as lvalues +@cindex expressions, conditional, as lvalues +@cindex casts as lvalues +@cindex generalized lvalues +@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. + +Standard C++ allows compound expressions and conditional expressions as +lvalues, and permits casts to reference type, so use of this extension +is deprecated for C++ code. + +For example, a compound expression can be assigned, provided the last +expression in the sequence is an lvalue. These two expressions are +equivalent: + +@example +(a, b) += 5 +a, (b += 5) +@end example + +Similarly, the address of the compound expression can be taken. These two +expressions are equivalent: + +@example +&(a, b) +a, &b +@end example + +A conditional expression is a valid lvalue if its type is not void and the +true and false branches are both valid lvalues. For example, these two +expressions are equivalent: + +@example +(a ? b : c) = 5 +(a ? b = 5 : (c = 5)) +@end example + +A cast is a valid lvalue if its operand is an lvalue. A simple +assignment whose left-hand side is a cast works by converting the +right-hand side first to the specified type, then to the type of the +inner left-hand side expression. After this is stored, the value is +converted back to the specified type to become the value of the +assignment. Thus, if @code{a} has type @code{char *}, the following two +expressions are equivalent: + +@example +(int)a = 5 +(int)(a = (char *)(int)5) +@end example + +An assignment-with-arithmetic operation such as @samp{+=} applied to a cast +performs the arithmetic using the type resulting from the cast, and then +continues as in the previous case. Therefore, these two expressions are +equivalent: + +@example +(int)a += 5 +(int)(a = (char *)(int) ((int)a + 5)) +@end example + +You cannot take the address of an lvalue cast, because the use of its +address would not work out coherently. Suppose that @code{&(int)f} were +permitted, where @code{f} has type @code{float}. Then the following +statement would try to store an integer bit-pattern where a floating +point number belongs: + +@example +*&(int)f = 1; +@end example + +This is quite different from what @code{(int)f = 1} would do---that +would convert 1 to floating point and store it. Rather than cause this +inconsistency, we think it is better to prohibit use of @samp{&} on a cast. + +If you really do want an @code{int *} pointer with the address of +@code{f}, you can simply write @code{(int *)&f}. + +@node Conditionals +@section Conditionals with Omitted Operands +@cindex conditional expressions, extensions +@cindex omitted middle-operands +@cindex middle-operands, omitted +@cindex extensions, @code{?:} +@cindex @code{?:} extensions + +The middle operand in a conditional expression may be omitted. Then +if the first operand is nonzero, its value is the value of the conditional +expression. + +Therefore, the expression + +@example +x ? : y +@end example + +@noindent +has the value of @code{x} if that is nonzero; otherwise, the value of +@code{y}. + +This example is perfectly equivalent to + +@example +x ? x : y +@end example + +@cindex side effect in ?: +@cindex ?: side effect +@noindent +In this simple case, the ability to omit the middle operand is not +especially useful. When it becomes useful is when the first operand does, +or may (if it is a macro argument), contain a side effect. Then repeating +the operand in the middle would perform the side effect twice. Omitting +the middle operand uses the value already computed without the undesirable +effects of recomputing it. + +@node Long Long +@section Double-Word Integers +@cindex @code{long long} data types +@cindex double-word arithmetic +@cindex multiprecision arithmetic + +GNU C supports data types for integers that are twice as long as +@code{long int}. Simply write @code{long long int} for a signed +integer, or @code{unsigned long long int} for an unsigned integer. +To make an integer constant of type @code{long long int}, add the suffix +@code{LL} to the integer. To make an integer constant of type +@code{unsigned long long int}, add the suffix @code{ULL} to the integer. + +You can use these types in arithmetic like any other integer types. +Addition, subtraction, and bitwise boolean operations on these types +are open-coded on all types of machines. Multiplication is open-coded +if the machine supports fullword-to-doubleword a widening multiply +instruction. Division and shifts are open-coded only on machines that +provide special support. The operations that are not open-coded use +special library routines that come with GNU CC. + +There may be pitfalls when you use @code{long long} types for function +arguments, unless you declare function prototypes. If a function +expects type @code{int} for its argument, and you pass a value of type +@code{long long int}, confusion will result because the caller and the +subroutine will disagree about the number of bytes for the argument. +Likewise, if the function expects @code{long long int} and you pass +@code{int}. The best way to avoid such problems is to use prototypes. + +@node Complex +@section Complex Numbers +@cindex complex numbers + +GNU C supports complex data types. You can declare both complex integer +types and complex floating types, using the keyword @code{__complex__}. + +For example, @samp{__complex__ double x;} declares @code{x} as a +variable whose real part and imaginary part are both of type +@code{double}. @samp{__complex__ short int y;} declares @code{y} to +have real and imaginary parts of type @code{short int}; this is not +likely to be useful, but it shows that the set of complex types is +complete. + +To write a constant with a complex data type, use the suffix @samp{i} or +@samp{j} (either one; they are equivalent). For example, @code{2.5fi} +has type @code{__complex__ float} and @code{3i} has type +@code{__complex__ int}. Such a constant always has a pure imaginary +value, but you can form any complex value you like by adding one to a +real constant. + +To extract the real part of a complex-valued expression @var{exp}, write +@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to +extract the imaginary part. + +The operator @samp{~} performs complex conjugation when used on a value +with a complex type. + +GNU CC 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 GNU CC 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 Zero Length +@section Arrays of Length Zero +@cindex arrays of length zero +@cindex zero-length arrays +@cindex length-zero arrays + +Zero-length arrays are allowed in GNU C. They are very useful as the last +element of a structure which is really a header for a variable-length +object: + +@example +struct line @{ + int length; + char contents[0]; +@}; + +@{ + struct line *thisline = (struct line *) + malloc (sizeof (struct line) + this_length); + thisline->length = this_length; +@} +@end example + +In standard C, you would have to give @code{contents} a length of 1, which +means either you waste space or complicate the argument to @code{malloc}. + +@node Variable Length +@section Arrays of Variable Length +@cindex variable-length arrays +@cindex arrays of variable length + +Variable-length automatic arrays are allowed in GNU C. These arrays are +declared like any other automatic arrays, but with a length that is not +a constant expression. The storage is allocated at the point of +declaration and deallocated when the brace-level is exited. For +example: + +@example +FILE * +concat_fopen (char *s1, char *s2, char *mode) +@{ + char str[strlen (s1) + strlen (s2) + 1]; + strcpy (str, s1); + strcat (str, s2); + return fopen (str, mode); +@} +@end example + +@cindex scope of a variable length array +@cindex variable-length array scope +@cindex deallocating variable length arrays +Jumping or breaking out of the scope of the array name deallocates the +storage. Jumping into the scope is not allowed; you get an error +message for it. + +@cindex @code{alloca} vs variable-length arrays +You can use the function @code{alloca} to get an effect much like +variable-length arrays. The function @code{alloca} is available in +many other C implementations (but not in all). On the other hand, +variable-length arrays are more elegant. + +There are other differences between these two methods. Space allocated +with @code{alloca} exists until the containing @emph{function} returns. +The space for a variable-length array is deallocated as soon as the array +name's scope ends. (If you use both variable-length arrays and +@code{alloca} in the same function, deallocation of a variable-length array +will also deallocate anything more recently allocated with @code{alloca}.) + +You can also use variable-length arrays as arguments to functions: + +@example +struct entry +tester (int len, char data[len][len]) +@{ + @dots{} +@} +@end example + +The length of an array is computed once when the storage is allocated +and is remembered for the scope of the array in case you access it with +@code{sizeof}. + +If you want to pass the array first and the length afterward, you can +use a forward declaration in the parameter list---another GNU extension. + +@example +struct entry +tester (int len; char data[len][len], int len) +@{ + @dots{} +@} +@end example + +@cindex parameter forward declaration +The @samp{int len} before the semicolon is a @dfn{parameter forward +declaration}, and it serves the purpose of making the name @code{len} +known when the declaration of @code{data} is parsed. + +You can write any number of such parameter forward declarations in the +parameter list. They can be separated by commas or semicolons, but the +last one must end with a semicolon, which is followed by the ``real'' +parameter declarations. Each forward declaration must match a ``real'' +declaration in parameter name and data type. + +@node Macro Varargs +@section Macros with Variable Numbers of Arguments +@cindex variable number of arguments +@cindex macro with variable arguments +@cindex rest argument (in macro) + +In GNU C, a macro can accept a variable number of arguments, much as a +function can. The syntax for defining the macro looks much like that +used for a function. Here is an example: + +@example +#define eprintf(format, args...) \ + fprintf (stderr, format , ## args) +@end example + +Here @code{args} is a @dfn{rest argument}: it takes in zero or more +arguments, as many as the call contains. All of them plus the commas +between them form the value of @code{args}, which is substituted into +the macro body where @code{args} is used. Thus, we have this expansion: + +@example +eprintf ("%s:%d: ", input_file_name, line_number) +@expansion{} +fprintf (stderr, "%s:%d: " , input_file_name, line_number) +@end example + +@noindent +Note that the comma after the string constant comes from the definition +of @code{eprintf}, whereas the last comma comes from the value of +@code{args}. + +The reason for using @samp{##} is to handle the case when @code{args} +matches no arguments at all. In this case, @code{args} has an empty +value. In this case, the second comma in the definition becomes an +embarrassment: if it got through to the expansion of the macro, we would +get something like this: + +@example +fprintf (stderr, "success!\n" , ) +@end example + +@noindent +which is invalid C syntax. @samp{##} gets rid of the comma, so we get +the following instead: + +@example +fprintf (stderr, "success!\n") +@end example + +This is a special feature of the GNU C preprocessor: @samp{##} before a +rest argument that is empty discards the preceding sequence of +non-whitespace characters from the macro definition. (If another macro +argument precedes, none of it is discarded.) + +It might be better to discard the last preprocessor token instead of the +last preceding sequence of non-whitespace characters; in fact, we may +someday change this feature to do so. We advise you to write the macro +definition so that the preceding sequence of non-whitespace characters +is just a single token, so that the meaning will not change if we change +the definition of this feature. + +@node Subscripting +@section Non-Lvalue Arrays May Have Subscripts +@cindex subscripting +@cindex arrays, non-lvalue + +@cindex subscripting and function values +Subscripting is allowed on arrays that are not lvalues, even though the +unary @samp{&} operator is not. For example, this is valid in GNU C though +not valid in other C dialects: + +@example +@group +struct foo @{int a[4];@}; + +struct foo f(); + +bar (int index) +@{ + return f().a[index]; +@} +@end group +@end example + +@node Pointer Arith +@section Arithmetic on @code{void}- and Function-Pointers +@cindex void pointers, arithmetic +@cindex void, size of pointer to +@cindex function pointers, arithmetic +@cindex function, size of pointer to + +In GNU C, addition and subtraction operations are supported on pointers to +@code{void} and on pointers to functions. This is done by treating the +size of a @code{void} or of a function as 1. + +A consequence of this is that @code{sizeof} is also allowed on @code{void} +and on function types, and returns 1. + +The option @samp{-Wpointer-arith} requests a warning if these extensions +are used. + +@node Initializers +@section Non-Constant Initializers +@cindex initializers, non-constant +@cindex non-constant initializers + +As in standard C++, the elements of an aggregate initializer for an +automatic variable are not required to be constant expressions in GNU C. +Here is an example of an initializer with run-time varying elements: + +@example +foo (float f, float g) +@{ + float beat_freqs[2] = @{ f-g, f+g @}; + @dots{} +@} +@end example + +@node Constructors +@section Constructor Expressions +@cindex constructor expressions +@cindex initializations in expressions +@cindex structures, constructor expression +@cindex expressions, constructor + +GNU C supports constructor expressions. A constructor looks like +a cast containing an initializer. Its value is an object of the +type specified in the cast, containing the elements specified in +the initializer. + +Usually, the specified type is a structure. Assume that +@code{struct foo} and @code{structure} are declared as shown: + +@example +struct foo @{int a; char b[2];@} structure; +@end example + +@noindent +Here is an example of constructing a @code{struct foo} with a constructor: + +@example +structure = ((struct foo) @{x + y, 'a', 0@}); +@end example + +@noindent +This is equivalent to writing the following: + +@example +@{ + struct foo temp = @{x + y, 'a', 0@}; + structure = temp; +@} +@end example + +You can also construct an array. If all the elements of the constructor +are (made up of) simple constant expressions, suitable for use in +initializers, then the constructor is an lvalue and can be coerced to a +pointer to its first element, as shown here: + +@example +char **foo = (char *[]) @{ "x", "y", "z" @}; +@end example + +Array constructors whose elements are not simple constants are +not very useful, because the constructor is not an lvalue. There +are only two valid ways to use it: to subscript it, or initialize +an array variable with it. The former is probably slower than a +@code{switch} statement, while the latter does the same thing an +ordinary C initializer would do. Here is an example of +subscripting an array constructor: + +@example +output = ((int[]) @{ 2, x, 28 @}) [input]; +@end example + +Constructor expressions for scalar types and union types are is +also allowed, but then the constructor expression is equivalent +to a cast. + +@node Labeled Elements +@section Labeled Elements in Initializers +@cindex initializers with labeled elements +@cindex labeled elements in initializers +@cindex case labels in initializers + +Standard C requires the elements of an initializer to appear in a fixed +order, the same as the order of the elements in the array or structure +being initialized. + +In GNU C you can give the elements in any order, specifying the array +indices or structure field names they apply to. This extension is not +implemented in GNU C++. + +To specify an array index, write @samp{[@var{index}]} or +@samp{[@var{index}] =} before the element value. For example, + +@example +int a[6] = @{ [4] 29, [2] = 15 @}; +@end example + +@noindent +is equivalent to + +@example +int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; +@end example + +@noindent +The index values must be constant expressions, even if the array being +initialized is automatic. + +To initialize a range of elements to the same value, write +@samp{[@var{first} ... @var{last}] = @var{value}}. For example, + +@example +int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; +@end example + +@noindent +Note that the length of the array is the highest value specified +plus one. + +In a structure initializer, specify the name of a field to initialize +with @samp{@var{fieldname}:} before the element value. For example, +given the following structure, + +@example +struct point @{ int x, y; @}; +@end example + +@noindent +the following initialization + +@example +struct point p = @{ y: yvalue, x: xvalue @}; +@end example + +@noindent +is equivalent to + +@example +struct point p = @{ xvalue, yvalue @}; +@end example + +Another syntax which has the same meaning is @samp{.@var{fieldname} =}., +as shown here: + +@example +struct point p = @{ .y = yvalue, .x = xvalue @}; +@end example + +You can also use an element label (with either the colon syntax or the +period-equal syntax) when initializing a union, to specify which element +of the union should be used. For example, + +@example +union foo @{ int i; double d; @}; + +union foo f = @{ d: 4 @}; +@end example + +@noindent +will convert 4 to a @code{double} to store it in the union using +the second element. By contrast, casting 4 to type @code{union foo} +would store it into the union as the integer @code{i}, since it is +an integer. (@xref{Cast to Union}.) + +You can combine this technique of naming elements with ordinary C +initialization of successive elements. Each initializer element that +does not have a label applies to the next consecutive element of the +array or structure. For example, + +@example +int a[6] = @{ [1] = v1, v2, [4] = v4 @}; +@end example + +@noindent +is equivalent to + +@example +int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; +@end example + +Labeling the elements of an array initializer is especially useful +when the indices are characters or belong to an @code{enum} type. +For example: + +@example +int whitespace[256] + = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, + ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; +@end example + +@node Case Ranges +@section Case Ranges +@cindex case ranges +@cindex ranges in case statements + +You can specify a range of consecutive values in a single @code{case} label, +like this: + +@example +case @var{low} ... @var{high}: +@end example + +@noindent +This has the same effect as the proper number of individual @code{case} +labels, one for each integer value from @var{low} to @var{high}, inclusive. + +This feature is especially useful for ranges of ASCII character codes: + +@example +case 'A' ... 'Z': +@end example + +@strong{Be careful:} Write spaces around the @code{...}, for otherwise +it may be parsed wrong when you use it with integer values. For example, +write this: + +@example +case 1 ... 5: +@end example + +@noindent +rather than this: + +@example +case 1...5: +@end example + +@node Cast to Union +@section Cast to a Union Type +@cindex cast to a union +@cindex union, casting to a + +A cast to union type is similar to other casts, except that the type +specified is a union type. You can specify the type either with +@code{union @var{tag}} or with a typedef name. A cast to union is actually +a constructor though, not a cast, and hence does not yield an lvalue like +normal casts. (@xref{Constructors}.) + +The types that may be cast to the union type are those of the members +of the union. Thus, given the following union and variables: + +@example +union foo @{ int i; double d; @}; +int x; +double y; +@end example + +@noindent +both @code{x} and @code{y} can be cast to type @code{union} foo. + +Using the cast as the right-hand side of an assignment to a variable of +union type is equivalent to storing in a member of the union: + +@example +union foo u; +@dots{} +u = (union foo) x @equiv{} u.i = x +u = (union foo) y @equiv{} u.d = y +@end example + +You can also use the union cast as a function argument: + +@example +void hack (union foo); +@dots{} +hack ((union foo) x); +@end example + +@node Function Attributes +@section Declaring Attributes of Functions +@cindex function attributes +@cindex declaring attributes of functions +@cindex functions that never return +@cindex functions that have no side effects +@cindex functions in arbitrary sections +@cindex @code{volatile} applied to function +@cindex @code{const} applied to function +@cindex functions with @code{printf} or @code{scanf} style arguments + +In GNU C, you declare certain things about functions called in your program +which help the compiler optimize function calls and check your code more +carefully. + +The keyword @code{__attribute__} allows you to specify special +attributes when making a declaration. This keyword is followed by an +attribute specification inside double parentheses. Four attributes, +@code{noreturn}, @code{const}, @code{format}, and @code{section} are +currently defined for functions. Other attributes, including @code{section} +are supported for variables declarations +(@pxref{Variable Attributes}). + +You may also specify attributes with @samp{__} preceeding and following +each keyword. This allows you to use them in header files without +being concerned about a possible macro of the same name. For example, +you may use @code{__noreturn__} instead of @code{noreturn}. + +@table @code +@cindex @code{noreturn} function attribute +@item noreturn +A few standard library functions, such as @code{abort} and @code{exit}, +cannot return. GNU CC knows this automatically. Some programs define +their own functions that never return. You can declare them +@code{noreturn} to tell the compiler this fact. For example, + +@smallexample +void fatal () __attribute__ ((noreturn)); + +void +fatal (@dots{}) +@{ + @dots{} /* @r{Print error message.} */ @dots{} + exit (1); +@} +@end smallexample + +The @code{noreturn} keyword tells the compiler to assume that +@code{fatal} cannot return. It can then optimize without regard to what +would happen if @code{fatal} ever did return. This makes slightly +better code. More importantly, it helps avoid spurious warnings of +uninitialized variables. + +Do not assume that registers saved by the calling function are +restored before calling the @code{noreturn} function. + +It does not make sense for a @code{noreturn} function to have a return +type other than @code{void}. + +The attribute @code{noreturn} is not implemented in GNU C versions +earlier than 2.5. An alternative way to declare that a function does +not return, which works in the current version and in some older +versions, is as follows: + +@smallexample +typedef void voidfn (); + +volatile voidfn fatal; +@end smallexample + +@cindex @code{const} function attribute +@item const +Many functions do not examine any values except their arguments, and +have no effects except the return value. Such a function can be subject +to common subexpression elimination and loop optimization just as an +arithmetic operator would be. These functions should be declared +with the attribute @code{const}. For example, + +@smallexample +int square (int) __attribute__ ((const)); +@end smallexample + +@noindent +says that the hypothetical function @code{square} is safe to call +fewer times than the program says. + +The attribute @code{const} is not implemented in GNU C versions earlier +than 2.5. An alternative way to declare that a function has no side +effects, which works in the current version and in some older versions, +is as follows: + +@smallexample +typedef int intfn (); + +extern const intfn square; +@end smallexample + +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 pointer arguments +Note that a function that has pointer arguments and examines the data +pointed to must @emph{not} be declared @code{const}. Likewise, a +function that calls a non-@code{const} function usually must not be +@code{const}. It does not make sense for a @code{const} function to +return @code{void}. + +@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) +@cindex @code{format} function attribute +The @code{format} attribute specifies that a function takes @code{printf} +or @code{scanf} style arguments which should be type-checked against a +format string. For example, the declaration: + +@smallexample +extern int +my_printf (void *my_object, const char *my_format, ...) + __attribute__ ((format (printf, 2, 3))); +@end smallexample + +@noindent +causes the compiler to check the arguments in calls to @code{my_printf} +for consistency with the @code{printf} style format string argument +@code{my_format}. + +The parameter @var{archetype} determines how the format string is +interpreted, and should be either @code{printf} or @code{scanf}. The +parameter @var{string-index} specifies which argument is the format +string argument (starting from 1), while @var{first-to-check} is the +number of the first argument to check against the format string. For +functions where the arguments are not available to be checked (such as +@code{vprintf}), specify the third parameter as zero. In this case the +compiler only checks the format string for consistency. + +In the example above, the format string (@code{my_format}) is the second +argument of the function @code{my_print}, and the arguments to check +start with the third argument, so the correct parameters for the format +attribute are 2 and 3. + +The @code{format} attribute allows you to identify your own functions +which take format strings as arguments, so that GNU CC can check the +calls to these functions for errors. The compiler always checks formats +for the ANSI library functions @code{printf}, @code{fprintf}, +@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, +@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such +warnings are requested (using @samp{-Wformat}), so there is no need to +modify the header file @file{stdio.h}. + +@item section ("section-name") +@cindex @code{section} function attribute +Normally, the compiler places the code it generates in the @code{text} section. +Sometimes, however, you need additional sections, or you need certain +particular functions to appear in special sections. The @code{section} +attribute specifies that a function lives in a particular section. +For example, the declaration: + +@smallexample +extern void foobar (void) __attribute__ ((section (".init"))); +@end smallexample + +@noindent +puts the function @code{foobar} in the @code{.init} section. + +Some file formats do not support arbitrary sections so the @code{section} +attribute is not available on all platforms. +If you need to map the entire contents of a module to a particular +section, consider using the facilities of the linker instead. +@end table + +You can specify multiple attributes in a declaration by separating them +by commas within the double parentheses or by immediately following an +attribute declaration with another attribute declaration. + +@cindex @code{#pragma}, reason for not using +@cindex pragma, reason for not using +Some people object to the @code{__attribute__} feature, suggesting that ANSI C's +@code{#pragma} should be used instead. There are two reasons for not +doing this. + +@enumerate +@item +It is impossible to generate @code{#pragma} commands from a macro. + +@item +There is no telling what the same @code{#pragma} might mean in another +compiler. +@end enumerate + +These two reasons apply to almost any application that might be proposed +for @code{#pragma}. It is basically a mistake to use @code{#pragma} for +@emph{anything}. + +@node Function Prototypes +@section Prototypes and Old-Style Function Definitions +@cindex function prototype declarations +@cindex old-style function definitions +@cindex promotion of formal parameters + +GNU C extends ANSI C to allow a function prototype to override a later +old-style non-prototype definition. Consider the following example: + +@example +/* @r{Use prototypes unless the compiler is old-fashioned.} */ +#if __STDC__ +#define P(x) x +#else +#define P(x) () +#endif + +/* @r{Prototype function declaration.} */ +int isroot P((uid_t)); + +/* @r{Old-style function definition.} */ +int +isroot (x) /* ??? lossage here ??? */ + uid_t x; +@{ + return x == 0; +@} +@end example + +Suppose the type @code{uid_t} happens to be @code{short}. ANSI C does +not allow this example, because subword arguments in old-style +non-prototype definitions are promoted. Therefore in this example the +function definition's argument is really an @code{int}, which does not +match the prototype argument type of @code{short}. + +This restriction of ANSI C makes it hard to write code that is portable +to traditional C compilers, because the programmer does not know +whether the @code{uid_t} type is @code{short}, @code{int}, or +@code{long}. Therefore, in cases like these GNU C allows a prototype +to override a later old-style definition. More precisely, in GNU C, a +function prototype argument type overrides the argument type specified +by a later old-style definition if the former type is the same as the +latter type before promotion. Thus in GNU C the above example is +equivalent to the following: + +@example +int isroot (uid_t); + +int +isroot (uid_t x) +@{ + return x == 0; +@} +@end example + +GNU C++ does not support old-style function definitions, so this +extension is irrelevant. + +@node Dollar Signs +@section Dollar Signs in Identifier Names +@cindex $ +@cindex dollar signs in identifier names +@cindex identifier names, dollar signs in + +In GNU C, you may use dollar signs in identifier names. This is because +many traditional C implementations allow such identifiers. + +On some machines, dollar signs are allowed in identifiers if you specify +@w{@samp{-traditional}}. On a few systems they are allowed by default, +even if you do not use @w{@samp{-traditional}}. But they are never +allowed if you specify @w{@samp{-ansi}}. + +There are certain ANSI C programs (obscure, to be sure) that would +compile incorrectly if dollar signs were permitted in identifiers. For +example: + +@example +#define foo(a) #a +#define lose(b) foo (b) +#define test$ +lose (test) +@end example + +@node Character Escapes +@section The Character @key{ESC} in Constants + +You can use the sequence @samp{\e} in a string or character constant to +stand for the ASCII character @key{ESC}. + +@node Alignment +@section Inquiring on Alignment of Types or Variables +@cindex alignment +@cindex type alignment +@cindex variable alignment + +The keyword @code{__alignof__} allows you to inquire about how an object +is aligned, or the minimum alignment usually required by a type. Its +syntax is just like @code{sizeof}. + +For example, if the target machine requires a @code{double} value to be +aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. +This is true on many RISC machines. On more traditional machine +designs, @code{__alignof__ (double)} is 4 or even 2. + +Some machines never actually require alignment; they allow reference to any +data type even at an odd addresses. For these machines, @code{__alignof__} +reports the @emph{recommended} alignment of a type. + +When the operand of @code{__alignof__} is an lvalue rather than a type, the +value is the largest alignment that the lvalue is known to have. It may +have this alignment as a result of its data type, or because it is part of +a structure and inherits alignment from that structure. For example, after +this declaration: + +@example +struct foo @{ int x; char y; @} foo1; +@end example + +@noindent +the value of @code{__alignof__ (foo1.y)} is probably 2 or 4, the same as +@code{__alignof__ (int)}, even though the data type of @code{foo1.y} +does not itself demand any alignment.@refill + +A related feature which lets you specify the alignment of an object is +@code{__attribute__ ((aligned (@var{alignment})))}; see the following +section. + +@node Variable Attributes +@section Specifying Attributes of Variables +@cindex attribute of variables +@cindex variable attributes + +The keyword @code{__attribute__} allows you to specify special +attributes of variables or structure fields. This keyword is followed +by an attribute specification inside double parentheses. Four +attributes are currently defined for variables: @code{aligned}, +@code{mode}, @code{packed}, and @code{section}. Other attributes are +defined for functions, and thus not documented here; +see @ref{Function Attributes}. + +You may also specify attributes with @samp{__} preceeding and following +each keyword. This allows you to use them in header files without +being concerned about a possible macro of the same name. For example, +you may use @code{__aligned__} instead of @code{aligned}. + +@table @code +@cindex @code{aligned} attribute +@item aligned (@var{alignment}) +This attribute specifies a minimum alignment for the variable or +structure field, measured in bytes. For example, the declaration: + +@smallexample +int x __attribute__ ((aligned (16))) = 0; +@end smallexample + +@noindent +causes the compiler to allocate the global variable @code{x} on a +16-byte boundary. On a 68040, this could be used in conjunction with +an @code{asm} expression to access the @code{move16} instruction which +requires 16-byte aligned operands. + +You can also specify the alignment of structure fields. For example, to +create a double-word aligned @code{int} pair, you could write: + +@smallexample +struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; +@end smallexample + +@noindent +This is an alternative to creating a union with a @code{double} member +that forces the union to be double-word aligned. + +It is not possible to specify the alignment of functions; the alignment +of functions is determined by the machine's requirements and cannot be +changed. You cannot specify alignment for a typedef name because such a +name is just an alias, not a distinct type. + +The @code{aligned} attribute can only increase the alignment; but you +can decrease it by specifying @code{packed} as well. See below. + +The linker of your operating system imposes a maximum alignment. If the +linker aligns each object file on a four byte boundary, then it is +beyond the compiler's power to cause anything to be aligned to a larger +boundary than that. For example, if the linker happens to put this object +file at address 136 (eight more than a multiple of 64), then the compiler +cannot guarantee an alignment of more than 8 just by aligning variables in +the object file. + +@item mode (@var{mode}) +@cindex @code{mode} attribute +This attribute specifies the data type for the declaration---whichever +type corresponds to the mode @var{mode}. This in effect lets you +request an integer or floating point type according to its width. + +@item packed +@cindex @code{packed} attribute +The @code{packed} attribute specifies that a variable or structure field +should have the smallest possible alignment---one byte for a variable, +and one bit for a field, unless you specify a larger value with the +@code{aligned} attribute. + +Here is a structure in which the field @code{x} is packed, so that it +immediately follows @code{a}: + +@example +struct foo +@{ + char a; + int x[2] __attribute__ ((packed)); +@}; +@end example + +@item section ("section-name") +@cindex @code{section} variable attribute +Normally, the compiler places the objects it generates in sections like +@code{data} and @code{bss}. Sometimes, however, you need additional sections, +or you need certain particular variables to appear in special sections, +for example to map to special hardware. The @code{section} +attribute specifies that a variable (or function) lives in a particular +section. For example, this small program uses several specific section names: + +@smallexample +struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; +struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; +char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; +int init_data_copy __attribute__ ((section ("INITDATACOPY"))) = 0; + +main() +@{ + /* Initialize stack pointer */ + init_sp (stack + sizeof (stack)); + + /* Initialize initialized data */ + memcpy (&init_data_copy, &data, &edata - &data); + + /* Turn on the serial ports */ + init_duart (&a); + init_duart (&b); +@} +@end smallexample + +@noindent +Use the @code{section} attribute with an @emph{initialized} definition +of a @emph{global} variable, as shown in the example. GNU CC issues +a warning and otherwise ignores the @code{section} attribute in +uninitialized variable declarations. + +You may only use the @code{section} attribute with a fully initialized +global definition because of the way linkers work. +The linker requires each object be defined once, with the exception that +uninitialized variables tentatively go in the @code{common} (or @code{bss}) +section and can be multiply "defined". + +Some file formats do not support arbitrary sections so the @code{section} +attribute is not available on all platforms. +If you need to map the entire contents of a module to a particular +section, consider using the facilities of the linker instead. + +@item transparent_union +This attribute, attached to a function argument variable which is a +union, means to pass the argument in the same way that the first union +alternative would be passed. You can also use this attribute on a +@code{typedef} for a union data type; then it applies to all function +arguments with that type. +@end table + +To specify multiple attributes, separate them by commas within the +double parentheses: for example, @samp{__attribute__ ((aligned (16), +packed))}. + +@node Inline +@section An Inline Function is As Fast As a Macro +@cindex inline functions +@cindex integrating function code +@cindex open coding +@cindex macros, inline alternative + +By declaring a function @code{inline}, you can direct GNU CC to +integrate that function's code into the code for its callers. This +makes execution faster by eliminating the function-call overhead; in +addition, if any of the actual argument values are constant, their known +values may permit simplifications at compile time so that not all of the +inline function's code needs to be included. The effect on code size is +less predictable; object code may be larger or smaller with function +inlining, depending on the particular case. Inlining of functions is an +optimization and it really ``works'' only in optimizing compilation. If +you don't use @samp{-O}, no function is really inline. + +To declare a function inline, use the @code{inline} keyword in its +declaration, like this: + +@example +inline int +inc (int *a) +@{ + (*a)++; +@} +@end example + +(If you are writing a header file to be included in ANSI C programs, write +@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.) + +You can also make all ``simple enough'' functions inline with the option +@samp{-finline-functions}. Note that certain usages in a function +definition can make it unsuitable for inline substitution. + +Note that in C and Objective C, unlike C++, the @code{inline} keyword +does not affect the linkage of the function. + +@cindex automatic @code{inline} for C++ member fns +@cindex @code{inline} automatic for C++ member fns +@cindex member fns, automatically @code{inline} +@cindex C++ member fns, automatically @code{inline} +GNU CC automatically inlines member functions defined within the class +body of C++ programs even if they are not explicitly declared +@code{inline}. (You can override this with @samp{-fno-default-inline}; +@pxref{C++ Dialect Options,,Options Controlling C++ Dialect}.) + +@cindex inline functions, omission of +When a function is both inline and @code{static}, if all calls to the +function are integrated into the caller, and the function's address is +never used, then the function's own assembler code is never referenced. +In this case, GNU CC does not actually output assembler code for the +function, unless you specify the option @samp{-fkeep-inline-functions}. +Some calls cannot be integrated for various reasons (in particular, +calls that precede the function's definition cannot be integrated, and +neither can recursive calls within the definition). If there is a +nonintegrated call, then the function is compiled to assembler code as +usual. The function must also be compiled as usual if the program +refers to its address, because that can't be inlined. + +@cindex non-static inline function +When an inline function is not @code{static}, then the compiler must assume +that there may be calls from other source files; since a global symbol can +be defined only once in any program, the function must not be defined in +the other source files, so the calls therein cannot be integrated. +Therefore, a non-@code{static} inline function is always compiled on its +own in the usual fashion. + +If you specify both @code{inline} and @code{extern} in the function +definition, then the definition is used only for inlining. In no case +is the function compiled on its own, not even if you refer to its +address explicitly. Such an address becomes an external reference, as +if you had only declared the function, and had not defined it. + +This combination of @code{inline} and @code{extern} has almost the +effect of a macro. The way to use it is to put a function definition in +a header file with these keywords, and put another copy of the +definition (lacking @code{inline} and @code{extern}) in a library file. +The definition in the header file will cause most calls to the function +to be inlined. If any uses of the function remain, they will refer to +the single copy in the library. + +GNU C does not inline any functions when not optimizing. It is not +clear whether it is better to inline or not, in this case, but we found +that a correct implementation when not optimizing was difficult. So we +did the easy thing, and turned it off. + +@node Extended Asm +@section Assembler Instructions with C Expression Operands +@cindex extended @code{asm} +@cindex @code{asm} expressions +@cindex assembler instructions +@cindex registers + +In an assembler instruction using @code{asm}, you can now specify the +operands of the instruction using C expressions. This means no more +guessing which registers or memory locations will contain the data you want +to use. + +You must specify an assembler instruction template much like what appears +in a machine description, plus an operand constraint string for each +operand. + +For example, here is how to use the 68881's @code{fsinx} instruction: + +@example +asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); +@end example + +@noindent +Here @code{angle} is the C expression for the input operand while +@code{result} is that of the output operand. Each has @samp{"f"} as its +operand constraint, saying that a floating point register is required. The +@samp{=} in @samp{=f} indicates that the operand is an output; all output +operands' constraints must use @samp{=}. The constraints use the same +language used in the machine description (@pxref{Constraints}). + +Each operand is described by an operand-constraint string followed by the C +expression in parentheses. A colon separates the assembler template from +the first output operand, and another separates the last output operand +from the first input, if any. Commas separate output operands and separate +inputs. The total number of operands is limited to ten or to the maximum +number of operands in any instruction pattern in the machine description, +whichever is greater. + +If there are no output operands, and there are input operands, then there +must be two consecutive colons surrounding the place where the output +operands would go. + +Output operand expressions must be lvalues; the compiler can check this. +The input operands need not be lvalues. The compiler cannot check whether +the operands have data types that are reasonable for the instruction being +executed. It does not parse the assembler instruction template and does +not know what it means, or whether it is valid assembler input. The +extended @code{asm} feature is most often used for machine instructions +that the compiler itself does not know exist. + +The output operands must be write-only; GNU CC will assume that the values +in these operands before the instruction are dead and need not be +generated. Extended asm does not support input-output or read-write +operands. For this reason, the constraint character @samp{+}, which +indicates such an operand, may not be used. + +When the assembler instruction has a read-write operand, or an operand +in which only some of the bits are to be changed, you must logically +split its function into two separate operands, one input operand and one +write-only output operand. The connection between them is expressed by +constraints which say they need to be in the same location when the +instruction executes. You can use the same C expression for both +operands, or different expressions. For example, here we write the +(fictitious) @samp{combine} instruction with @code{bar} as its read-only +source operand and @code{foo} as its read-write destination: + +@example +asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); +@end example + +@noindent +The constraint @samp{"0"} for operand 1 says that it must occupy the same +location as operand 0. A digit in constraint is allowed only in an input +operand, and it must refer to an output operand. + +Only a digit in the constraint can guarantee that one operand will be in +the same place as another. The mere fact that @code{foo} is the value of +both operands is not enough to guarantee that they will be in the same +place in the generated assembler code. The following would not work: + +@example +asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); +@end example + +Various optimizations or reloading could cause operands 0 and 1 to be in +different registers; GNU CC knows no reason not to do so. For example, the +compiler might find a copy of the value of @code{foo} in one register and +use it for operand 1, but generate the output operand 0 in a different +register (copying it afterward to @code{foo}'s own address). Of course, +since the register for operand 1 is not even mentioned in the assembler +code, the result will not work, but GNU CC can't tell that. + +Some instructions clobber specific hard registers. To describe this, write +a third colon after the input operands, followed by the names of the +clobbered hard registers (given as strings). Here is a realistic example +for the Vax: + +@example +asm volatile ("movc3 %0,%1,%2" + : /* no outputs */ + : "g" (from), "g" (to), "g" (count) + : "r0", "r1", "r2", "r3", "r4", "r5"); +@end example + +If you refer to a particular hardware register from the assembler code, +then you will probably have to list the register after the third colon +to tell the compiler that the register's value is modified. In many +assemblers, the register names begin with @samp{%}; to produce one +@samp{%} in the assembler code, you must write @samp{%%} in the input. + +If your assembler instruction can alter the condition code register, +add @samp{cc} to the list of clobbered registers. GNU CC on some +machines represents the condition codes as a specific hardware +register; @samp{cc} serves to name this register. On other machines, +the condition code is handled differently, and specifying @samp{cc} +has no effect. But it is valid no matter what the machine. + +If your assembler instruction modifies memory in an unpredictable +fashion, add @samp{memory} to the list of clobbered registers. +This will cause GNU CC to not keep memory values cached in +registers across the assembler instruction. + +You can put multiple assembler instructions together in a single @code{asm} +template, separated either with newlines (written as @samp{\n}) or with +semicolons if the assembler allows such semicolons. The GNU assembler +allows semicolons and all Unix assemblers seem to do so. The input +operands are guaranteed not to use any of the clobbered registers, and +neither will the output operands' addresses, so you can read and write the +clobbered registers as many times as you like. Here is an example of +multiple instructions in a template; it assumes that the subroutine +@code{_foo} accepts arguments in registers 9 and 10: + +@example +asm ("movl %0,r9;movl %1,r10;call _foo" + : /* no outputs */ + : "g" (from), "g" (to) + : "r9", "r10"); +@end example + +Unless an output operand has the @samp{&} constraint modifier, GNU CC may +allocate it in the same register as an unrelated input operand, on the +assumption that the inputs are consumed before the outputs are produced. +This assumption may be false if the assembler code actually consists of +more than one instruction. In such a case, use @samp{&} for each output +operand that may not overlap an input. +@xref{Modifiers}. + +If you want to test the condition code produced by an assembler instruction, +you must include a branch and a label in the @code{asm} construct, as follows: + +@example +asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:" + : "g" (result) + : "g" (input)); +@end example + +@noindent +This assumes your assembler supports local labels, as the GNU assembler +and most Unix assemblers do. + +Speaking of labels, jumps from one @code{asm} to another are not +supported. The compiler's optimizers do not know about these jumps, +and therefore they cannot take account of them when deciding how to +optimize. + +@cindex macros containing @code{asm} +Usually the most convenient way to use these @code{asm} instructions is to +encapsulate them in macros that look like functions. For example, + +@example +#define sin(x) \ +(@{ double __value, __arg = (x); \ + asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ + __value; @}) +@end example + +@noindent +Here the variable @code{__arg} is used to make sure that the instruction +operates on a proper @code{double} value, and to accept only those +arguments @code{x} which can convert automatically to a @code{double}. + +Another way to make sure the instruction operates on the correct data type +is to use a cast in the @code{asm}. This is different from using a +variable @code{__arg} in that it converts more different types. For +example, if the desired type were @code{int}, casting the argument to +@code{int} would accept a pointer with no complaint, while assigning the +argument to an @code{int} variable named @code{__arg} would warn about +using a pointer unless the caller explicitly casts it. + +If an @code{asm} has output operands, GNU CC assumes for optimization +purposes that the instruction has no side effects except to change the +output operands. This does not mean that instructions with a side effect +cannot be used, but you must be careful, because the compiler may eliminate +them if the output operands aren't used, or move them out of loops, or +replace two with one if they constitute a common subexpression. Also, if +your instruction does have a side effect on a variable that otherwise +appears not to change, the old value of the variable may be reused later if +it happens to be found in a register. + +You can prevent an @code{asm} instruction from being deleted, moved +significantly, or combined, by writing the keyword @code{volatile} after +the @code{asm}. For example: + +@example +#define set_priority(x) \ +asm volatile ("set_priority %0": /* no outputs */ : "g" (x)) +@end example + +@noindent +An instruction without output operands will not be deleted or moved +significantly, regardless, unless it is unreachable. + +Note that even a volatile @code{asm} instruction can be moved in ways +that appear insignificant to the compiler, such as across jump +instructions. You can't expect a sequence of volatile @code{asm} +instructions to remain perfectly consecutive. If you want consecutive +output, use a single @code{asm}. + +It is a natural idea to look for a way to give access to the condition +code left by the assembler instruction. However, when we attempted to +implement this, we found no way to make it work reliably. The problem +is that output operands might need reloading, which would result in +additional following ``store'' instructions. On most machines, these +instructions would alter the condition code before there was time to +test it. This problem doesn't arise for ordinary ``test'' and +``compare'' instructions because they don't have any output operands. + +If you are writing a header file that should be includable in ANSI C +programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate +Keywords}. + +@ifclear INTERNALS +@c Show the details on constraints if they do not appear elsewhere in +@c the manual +@include md.texi +@end ifclear + +@node Asm Labels +@section Controlling Names Used in Assembler Code +@cindex assembler names for identifiers +@cindex names used in assembler code +@cindex identifiers, names in assembler code + +You can specify the name to be used in the assembler code for a C +function or variable by writing the @code{asm} (or @code{__asm__}) +keyword after the declarator as follows: + +@example +int foo asm ("myfoo") = 2; +@end example + +@noindent +This specifies that the name to be used for the variable @code{foo} in +the assembler code should be @samp{myfoo} rather than the usual +@samp{_foo}. + +On systems where an underscore is normally prepended to the name of a C +function or variable, this feature allows you to define names for the +linker that do not start with an underscore. + +You cannot use @code{asm} in this way in a function @emph{definition}; but +you can get the same effect by writing a declaration for the function +before its definition and putting @code{asm} there, like this: + +@example +extern func () asm ("FUNC"); + +func (x, y) + int x, y; +@dots{} +@end example + +It is up to you to make sure that the assembler names you choose do not +conflict with any other assembler symbols. Also, you must not use a +register name; that would produce completely invalid assembler code. GNU +CC does not as yet have the ability to store static variables in registers. +Perhaps that will be added. + +@node Explicit Reg Vars +@section Variables in Specified Registers +@cindex explicit register variables +@cindex variables in specified registers +@cindex specified registers +@cindex registers, global allocation + +GNU C allows you to put a few global variables into specified hardware +registers. You can also specify the register in which an ordinary +register variable should be allocated. + +@itemize @bullet +@item +Global register variables reserve registers throughout the program. +This may be useful in programs such as programming language +interpreters which have a couple of global variables that are accessed +very often. + +@item +Local register variables in specific registers do not reserve the +registers. The compiler's data flow analysis is capable of determining +where the specified registers contain live values, and where they are +available for other uses. + +These local variables are sometimes convenient for use with the extended +@code{asm} feature (@pxref{Extended Asm}), if you want to write one +output of the assembler instruction directly into a particular register. +(This will work provided the register you specify fits the constraints +specified for that operand in the @code{asm}.) +@end itemize + +@menu +* Global Reg Vars:: +* Local Reg Vars:: +@end menu + +@node Global Reg Vars +@subsection Defining Global Register Variables +@cindex global register variables +@cindex registers, global variables in + +You can define a global register variable in GNU C like this: + +@example +register int *foo asm ("a5"); +@end example + +@noindent +Here @code{a5} is the name of the register which should be used. Choose a +register which is normally saved and restored by function calls on your +machine, so that library routines will not clobber it. + +Naturally the register name is cpu-dependent, so you would need to +conditionalize your program according to cpu type. The register +@code{a5} would be a good choice on a 68000 for a variable of pointer +type. On machines with register windows, be sure to choose a ``global'' +register that is not affected magically by the function call mechanism. + +In addition, operating systems on one type of cpu may differ in how they +name the registers; then you would need additional conditionals. For +example, some 68000 operating systems call this register @code{%a5}. + +Eventually there may be a way of asking the compiler to choose a register +automatically, but first we need to figure out how it should choose and +how to enable you to guide the choice. No solution is evident. + +Defining a global register variable in a certain register reserves that +register entirely for this use, at least within the current compilation. +The register will not be allocated for any other purpose in the functions +in the current compilation. The register will not be saved and restored by +these functions. Stores into this register are never deleted even if they +would appear to be dead, but references may be deleted or moved or +simplified. + +It is not safe to access the global register variables from signal +handlers, or from more than one thread of control, because the system +library routines may temporarily use the register for other things (unless +you recompile them specially for the task at hand). + +@cindex @code{qsort}, and global register variables +It is not safe for one function that uses a global register variable to +call another such function @code{foo} by way of a third function +@code{lose} that was compiled without knowledge of this variable (i.e. in a +different source file in which the variable wasn't declared). This is +because @code{lose} might save the register and put some other value there. +For example, you can't expect a global register variable to be available in +the comparison-function that you pass to @code{qsort}, since @code{qsort} +might have put something else in that register. (If you are prepared to +recompile @code{qsort} with the same global register variable, you can +solve this problem.) + +If you want to recompile @code{qsort} or other source files which do not +actually use your global register variable, so that they will not use that +register for any other purpose, then it suffices to specify the compiler +option @samp{-ffixed-@var{reg}}. You need not actually add a global +register declaration to their source code. + +A function which can alter the value of a global register variable cannot +safely be called from a function compiled without this variable, because it +could clobber the value the caller expects to find there on return. +Therefore, the function which is the entry point into the part of the +program that uses the global register variable must explicitly save and +restore the value which belongs to its caller. + +@cindex register variable after @code{longjmp} +@cindex global register after @code{longjmp} +@cindex value after @code{longjmp} +@findex longjmp +@findex setjmp +On most machines, @code{longjmp} will restore to each global register +variable the value it had at the time of the @code{setjmp}. On some +machines, however, @code{longjmp} will not change the value of global +register variables. To be portable, the function that called @code{setjmp} +should make other arrangements to save the values of the global register +variables, and to restore them in a @code{longjmp}. This way, the same +thing will happen regardless of what @code{longjmp} does. + +All global register variable declarations must precede all function +definitions. If such a declaration could appear after function +definitions, the declaration would be too late to prevent the register from +being used for other purposes in the preceding functions. + +Global register variables may not have initial values, because an +executable file has no means to supply initial contents for a register. + +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. + +On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7. +Of course, it will not do to use more than a few of those. + +@node Local Reg Vars +@subsection Specifying Registers for Local Variables +@cindex local variables, specifying registers +@cindex specifying registers for local variables +@cindex registers for local variables + +You can define a local register variable with a specified register +like this: + +@example +register int *foo asm ("a5"); +@end example + +@noindent +Here @code{a5} is the name of the register which should be used. Note +that this is the same syntax used for defining global register +variables, but for a local variable it would appear within a function. + +Naturally the register name is cpu-dependent, but this is not a +problem, since specific registers are most often useful with explicit +assembler instructions (@pxref{Extended Asm}). Both of these things +generally require that you conditionalize your program according to +cpu type. + +In addition, operating systems on one type of cpu may differ in how they +name the registers; then you would need additional conditionals. For +example, some 68000 operating systems call this register @code{%a5}. + +Eventually there may be a way of asking the compiler to choose a register +automatically, but first we need to figure out how it should choose and +how to enable you to guide the choice. No solution is evident. + +Defining such a register variable does not reserve the register; it +remains available for other uses in places where flow control determines +the variable's value is not live. However, these registers are made +unavailable for use in the reload pass. I would not be surprised if +excessive use of this feature leaves the compiler too few available +registers to compile certain functions. + +@node Alternate Keywords +@section Alternate Keywords +@cindex alternate keywords +@cindex keywords, alternate + +The option @samp{-traditional} disables certain keywords; @samp{-ansi} +disables certain others. This causes trouble when you want to use GNU C +extensions, or ANSI C features, in a general-purpose header file that +should be usable by all programs, including ANSI C programs and traditional +ones. The keywords @code{asm}, @code{typeof} and @code{inline} cannot be +used since they won't work in a program compiled with @samp{-ansi}, while +the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof} +and @code{inline} won't work in a program compiled with +@samp{-traditional}.@refill + +The way to solve these problems is to put @samp{__} at the beginning and +end of each problematical keyword. For example, use @code{__asm__} +instead of @code{asm}, @code{__const__} instead of @code{const}, and +@code{__inline__} instead of @code{inline}. + +Other C compilers won't accept these alternative keywords; if you want to +compile with another compiler, you can define the alternate keywords as +macros to replace them with the customary keywords. It looks like this: + +@example +#ifndef __GNUC__ +#define __asm__ asm +#endif +@end example + +@samp{-pedantic} causes warnings for many GNU C extensions. You can +prevent such warnings within one expression by writing +@code{__extension__} before the expression. @code{__extension__} has no +effect aside from this. + +@node Incomplete Enums +@section Incomplete @code{enum} Types + +You can define an @code{enum} tag without specifying its possible values. +This results in an incomplete type, much like what you get if you write +@code{struct foo} without describing the elements. A later declaration +which does specify the possible values completes the type. + +You can't allocate variables or storage using the type while it is +incomplete. However, you can work with pointers to that type. + +This extension may not be very useful, but it makes the handling of +@code{enum} more consistent with the way @code{struct} and @code{union} +are handled. + +This extension is not supported by GNU C++. + +@node Function Names +@section Function Names as Strings + +GNU CC predefines two string variables to be the name of the current function. +The variable @code{__FUNCTION__} is the name of the function as it appears +in the source. The variable @code{__PRETTY_FUNCTION__} is the name of +the function pretty printed in a language specific fashion. + +These names are always the same in a C function, but in a C++ function +they may be different. For example, this program: + +@smallexample +extern "C" @{ +extern int printf (char *, ...); +@} + +class a @{ + public: + sub (int i) + @{ + printf ("__FUNCTION__ = %s\n", __FUNCTION__); + printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); + @} +@}; + +int +main (void) +@{ + a ax; + ax.sub (0); + return 0; +@} +@end smallexample + +@noindent +gives this output: + +@smallexample +__FUNCTION__ = sub +__PRETTY_FUNCTION__ = int a::sub (int) +@end smallexample + +@node C++ Extensions +@chapter Extensions to the C++ Language +@cindex extensions, C++ language +@cindex C++ language extensions + +The GNU compiler provides these extensions to the C++ language (and you +can also use most of the C language extensions in your C++ programs). If you +want to write code that checks whether these features are available, you can +test for the GNU compiler the same way as for C programs: check for a +predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to +test specifically for GNU C++ (@pxref{Standard Predefined,,Standard +Predefined Macros,cpp.info,The C Preprocessor}). + +@menu +* Naming Results:: Giving a name to C++ function return values. +* Min and Max:: C++ Minimum and maximum operators. +* Destructors and Goto:: Goto is safe to use in C++ even when destructors + are needed. +* C++ Interface:: You can use a single C++ header file for both + declarations and definitions. +* Template Instantiation:: Methods for ensuring that exactly one copy of + each needed template instantiation is emitted. +* C++ Signatures:: You can specify abstract types to get subtype + polymorphism independent from inheritance. +@end menu + +@node Naming Results +@section Named Return Values in C++ + +@cindex @code{return}, in C++ function header +@cindex return value, named, in C++ +@cindex named return value in C++ +@cindex C++ named return value +GNU C++ extends the function-definition syntax to allow you to specify a +name for the result of a function outside the body of the definition, in +C++ programs: + +@example +@group +@var{type} +@var{functionname} (@var{args}) return @var{resultname}; +@{ + @dots{} + @var{body} + @dots{} +@} +@end group +@end example + +You can use this feature to avoid an extra constructor call when +a function result has a class type. For example, consider a function +@code{m}, declared as @w{@samp{X v = m ();}}, whose result is of class +@code{X}: + +@example +X +m () +@{ + X b; + b.a = 23; + return b; +@} +@end example + +@cindex implicit argument: return value +Although @code{m} appears to have no arguments, in fact it has one implicit +argument: the address of the return value. At invocation, the address +of enough space to hold @code{v} is sent in as the implicit argument. +Then @code{b} is constructed and its @code{a} field is set to the value +23. Finally, a copy constructor (a constructor of the form @samp{X(X&)}) +is applied to @code{b}, with the (implicit) return value location as the +target, so that @code{v} is now bound to the return value. + +But this is wasteful. The local @code{b} is declared just to hold +something that will be copied right out. While a compiler that +combined an ``elision'' algorithm with interprocedural data flow +analysis could conceivably eliminate all of this, it is much more +practical to allow you to assist the compiler in generating +efficient code by manipulating the return value explicitly, +thus avoiding the local variable and copy constructor altogether. + +Using the extended GNU C++ function-definition syntax, you can avoid the +temporary allocation and copying by naming @code{r} as your return value +as the outset, and assigning to its @code{a} field directly: + +@example +X +m () return r; +@{ + r.a = 23; +@} +@end example + +@noindent +The declaration of @code{r} is a standard, proper declaration, whose effects +are executed @strong{before} any of the body of @code{m}. + +Functions of this type impose no additional restrictions; in particular, +you can execute @code{return} statements, or return implicitly by +reaching the end of the function body (``falling off the edge''). +Cases like + +@example +X +m () return r (23); +@{ + return; +@} +@end example + +@noindent +(or even @w{@samp{X m () return r (23); @{ @}}}) are unambiguous, since +the return value @code{r} has been initialized in either case. The +following code may be hard to read, but also works predictably: + +@example +X +m () return r; +@{ + X b; + return b; +@} +@end example + +The return value slot denoted by @code{r} is initialized at the outset, +but the statement @samp{return b;} overrides this value. The compiler +deals with this by destroying @code{r} (calling the destructor if there +is one, or doing nothing if there is not), and then reinitializing +@code{r} with @code{b}. + +This extension is provided primarily to help people who use overloaded +operators, where there is a great need to control not just the +arguments, but the return values of functions. For classes where the +copy constructor incurs a heavy performance penalty (especially in the +common case where there is a quick default constructor), this is a major +savings. The disadvantage of this extension is that you do not control +when the default constructor for the return value is called: it is +always called at the beginning. + +@node Min and Max +@section Minimum and Maximum Operators in C++ + +It is very convenient to have operators which return the ``minimum'' or the +``maximum'' of two arguments. In GNU C++ (but not in GNU C), + +@table @code +@item @var{a} <? @var{b} +@findex <? +@cindex minimum operator +is the @dfn{minimum}, returning the smaller of the numeric values +@var{a} and @var{b}; + +@item @var{a} >? @var{b} +@findex >? +@cindex maximum operator +is the @dfn{maximum}, returning the larger of the numeric values @var{a} +and @var{b}. +@end table + +These operations are not primitive in ordinary C++, since you can +use a macro to return the minimum of two things in C++, as in the +following example. + +@example +#define MIN(X,Y) ((X) < (Y) ? : (X) : (Y)) +@end example + +@noindent +You might then use @w{@samp{int min = MIN (i, j);}} to set @var{min} to +the minimum value of variables @var{i} and @var{j}. + +However, side effects in @code{X} or @code{Y} may cause unintended +behavior. For example, @code{MIN (i++, j++)} will fail, incrementing +the smaller counter twice. A GNU C extension allows you to write safe +macros that avoid this kind of problem (@pxref{Naming Types,,Naming an +Expression's Type}). However, writing @code{MIN} and @code{MAX} as +macros also forces you to use function-call notation notation for a +fundamental arithmetic operation. Using GNU C++ extensions, you can +write @w{@samp{int min = i <? j;}} instead. + +Since @code{<?} and @code{>?} are built into the compiler, they properly +handle expressions with side-effects; @w{@samp{int min = i++ <? j++;}} +works correctly. + +@node Destructors and Goto +@section @code{goto} and Destructors in GNU C++ + +@cindex @code{goto} in C++ +@cindex destructors vs @code{goto} +In C++ programs, you can safely use the @code{goto} statement. When you +use it to exit a block which contains aggregates requiring destructors, +the destructors will run before the @code{goto} transfers control. (In +ANSI C++, @code{goto} is restricted to targets within the current +block.) + +@cindex constructors vs @code{goto} +The compiler still forbids using @code{goto} to @emph{enter} a scope +that requires constructors. + +@node C++ Interface +@section Declarations and Definitions in One Header + +@cindex interface and implementation headers, C++ +@cindex C++ interface and implementation headers +C++ object definitions can be quite complex. In principle, your source +code will need two kinds of things for each object that you use across +more than one source file. First, you need an @dfn{interface} +specification, describing its structure with type declarations and +function prototypes. Second, you need the @dfn{implementation} itself. +It can be tedious to maintain a separate interface description in a +header file, in parallel to the actual implementation. It is also +dangerous, since separate interface and implementation definitions may +not remain parallel. + +@cindex pragmas, interface and implementation +With GNU C++, you can use a single header file for both purposes. + +@quotation +@emph{Warning:} The mechanism to specify this is in transition. For the +nonce, you must use one of two @code{#pragma} commands; in a future +release of GNU C++, an alternative mechanism will make these +@code{#pragma} commands unnecessary. +@end quotation + +The header file contains the full definitions, but is marked with +@samp{#pragma interface} in the source code. This allows the compiler +to use the header file only as an interface specification when ordinary +source files incorporate it with @code{#include}. In the single source +file where the full implementation belongs, you can use either a naming +convention or @samp{#pragma implementation} to indicate this alternate +use of the header file. + +@table @code +@item #pragma interface +@itemx #pragma interface "@var{subdir}/@var{objects}.h" +@kindex #pragma interface +Use this directive in @emph{header files} that define object classes, to save +space in most of the object files that use those classes. Normally, +local copies of certain information (backup copies of inline member +functions, debugging information, and the internal tables that implement +virtual functions) must be kept in each object file that includes class +definitions. You can use this pragma to avoid such duplication. When a +header file containing @samp{#pragma interface} is included in a +compilation, this auxiliary information will not be generated (unless +the main input source file itself uses @samp{#pragma implementation}). +Instead, the object files will contain references to be resolved at link +time. + +The second form of this directive is useful for the case where you have +multiple headers with the same name in different directories. If you +use this form, you must specify the same string to @samp{#pragma +implementation}. + +@item #pragma implementation +@itemx #pragma implementation "@var{objects}.h" +@kindex #pragma implementation +Use this pragma in a @emph{main input file}, when you want full output from +included header files to be generated (and made globally visible). The +included header file, in turn, should use @samp{#pragma interface}. +Backup copies of inline member functions, debugging information, and the +internal tables used to implement virtual functions are all generated in +implementation files. + +@cindex implied @code{#pragma implementation} +@cindex @code{#pragma implementation}, implied +@cindex naming convention, implementation headers +If you use @samp{#pragma implementation} with no argument, it applies to +an include file with the same basename@footnote{A file's @dfn{basename} +was the name stripped of all leading path information and of trailing +suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source +file. For example, in @file{allclass.cc}, @samp{#pragma implementation} +by itself is equivalent to @samp{#pragma implementation "allclass.h"}. + +In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as +an implementation file whenever you would include it from +@file{allclass.cc} even if you never specified @samp{#pragma +implementation}. This was deemed to be more trouble than it was worth, +however, and disabled. + +If you use an explicit @samp{#pragma implementation}, it must appear in +your source file @emph{before} you include the affected header files. + +Use the string argument if you want a single implementation file to +include code from multiple header files. (You must also use +@samp{#include} to include the header file; @samp{#pragma +implementation} only specifies how to use the file---it doesn't actually +include it.) + +There is no way to split up the contents of a single header file into +multiple implementation files. +@end table + +@cindex inlining and C++ pragmas +@cindex C++ pragmas, effect on inlining +@cindex pragmas in C++, effect on inlining +@samp{#pragma implementation} and @samp{#pragma interface} also have an +effect on function inlining. + +If you define a class in a header file marked with @samp{#pragma +interface}, the effect on a function defined in that class is similar to +an explicit @code{extern} declaration---the compiler emits no code at +all to define an independent version of the function. Its definition +is used only for inlining with its callers. + +Conversely, when you include the same header file in a main source file +that declares it as @samp{#pragma implementation}, the compiler emits +code for the function itself; this defines a version of the function +that can be found via pointers (or by callers compiled without +inlining). If all calls to the function can be inlined, you can avoid +emitting the function by compiling with @samp{-fno-implement-inlines}. +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 +intelligence from the environment than one usually finds on a UNIX +system. Somehow the compiler and linker have to make sure that each +template instance occurs exactly once in the executable if it is needed, +and not at all otherwise. There are two basic approaches to this +problem, which I will refer to as the Borland model and the Cfront model. + +@table @asis +@item Borland model +Borland C++ solved the template instantiation problem by adding the code +equivalent of common blocks to their linker; template instances +are emitted in each translation unit that uses them, and they are +collapsed together at run time. The advantage of this model is that the +linker only has to consider the object files themselves; there is no +external complexity to worry about. This disadvantage is that +compilation time is increased because the template code is being +compiled repeatedly. Code written for this model tends to include +definitions of all member templates in the header file, since they must +be seen to be compiled. + +@item Cfront model +The AT&T C++ translator, Cfront, solved the template instantiation +problem by creating the notion of a template repository, an +automatically maintained place where template instances are stored. As +individual object files are built, notes are placed in the repository to +record where templates and potential type arguments were seen so that +the subsequent instantiation step knows where to find them. At link +time, any needed instances are generated and linked in. The advantages +of this model are more optimal compilation speed and the ability to use +the system linker; to implement the Borland model a compiler vendor also +needs to replace the linker. The disadvantages are vastly increased +complexity, and thus potential for error; theoretically, this should be +just as transparent, but in practice it has been very difficult to build +multiple programs in one directory and one program in multiple +directories using Cfront. Code written for this model tends to separate +definitions of non-inline member templates into a separate file, which +is magically found by the link preprocessor when a template needs to be +instantiated. +@end table + +Currently, g++ implements neither automatic model. The g++ team hopes +to have a repository working for 2.7.0. In the mean time, you have +three options for dealing with template instantiations: + +@enumerate +@item +Do nothing. Pretend g++ does implement automatic instantiation +management. Code written for the Borland model will work fine, but +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 +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 -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. + +A slight variation on this approach is to use the flag +-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. + +@item +Explicitly instantiate all the template instances you use, and compile +with -fno-implicit-templates. This is probably your best bet; it may +require more knowledge of exactly which templates you are using, but +it's less mysterious than the previous approach, and it doesn't require +any @samp{#pragma}s or other g++-specific code. You can scatter the +instantiations throughout your program, you can create one big file to +do all the instantiations, or you can create tiny files like + +@example +#include "Foo.h" +#include "Foo.cc" + +template class Foo<int>; +@end example + +for each instance you need, and create a template instantiation library +from those. I'm partial to the last, but your mileage may vary. If you +are using Cfront-model code, you can probably get away with not using +-fno-implicit-templates when compiling files that don't @samp{#include} +the member template definitions. +@end enumerate + +@node C++ Signatures +@section Type Abstraction using Signatures + +@findex signature +@cindex type abstraction, C++ +@cindex C++ type abstraction +@cindex subtype polymorphism, C++ +@cindex C++ subtype polymorphism +@cindex signatures, C++ +@cindex C++ signatures + +In GNU C++, you can use the keyword @code{signature} to define a +completely abstract class interface as a datatype. You can connect this +abstraction with actual classes using signature pointers. If you want +to use signatures, run the GNU compiler with the +@samp{-fhandle-signatures} command-line option. (With this option, the +compiler reserves a second keyword @code{sigof} as well, for a future +extension.) + +Roughly, signatures are type abstractions or interfaces of classes. +Some other languages have similar facilities. C++ signatures are +related to ML's signatures, Haskell's type classes, definition modules +in Modula-2, interface modules in Modula-3, abstract types in Emerald, +type modules in Trellis/Owl, categories in Scratchpad II, and types in +POOL-I. For a more detailed discussion of signatures, see +@cite{Signatures: A C++ Extension for Type Abstraction and Subtype +Polymorphism} by @w{Gerald} Baumgartner and Vincent F. Russo (Tech report +CSD--TR--93--059, Dept. of Computer Sciences, Purdue University, +September 1993, to appear in @emph{Software Practice & Experience}). +You can get the tech report by anonymous FTP from +@code{ftp.cs.purdue.edu} in @file{pub/reports/TR93-059.PS.Z}. + +Syntactically, a signature declaration is a collection of +member function declarations and nested type declarations. +For example, this signature declaration defines a new abstract type +@code{S} with member functions @samp{int foo ()} and @samp{int bar (int)}: + +@example +signature S +@{ + int foo (); + int bar (int); +@}; +@end example + +Since signature types do not include implementation definitions, you +cannot write an instance of a signature directly. Instead, you can +define a pointer to any class that contains the required interfaces as a +@dfn{signature pointer}. Such a class @dfn{implements} the signature +type. +@c Eventually signature references should work too. + +To use a class as an implementation of @code{S}, you must ensure that +the class has public member functions @samp{int foo ()} and @samp{int +bar (int)}. The class can have other member functions as well, public +or not; as long as it offers what's declared in the signature, it is +suitable as an implementation of that signature type. + +For example, suppose that @code{C} is a class that meets the +requirements of signature @code{S} (@code{C} @dfn{conforms to} +@code{S}). Then + +@example +C obj; +S * p = &obj; +@end example + +@noindent +defines a signature pointer @code{p} and initializes it to point to an +object of type @code{C}. +The member function call @w{@samp{int i = p->foo ();}} +executes @samp{obj.foo ()}. + +@cindex @code{signature} in C++, advantages +Abstract virtual classes provide somewhat similar facilities in standard +C++. There are two main advantages to using signatures instead: + +@enumerate +@item +Subtyping becomes independent from inheritance. A class or signature +type @code{T} is a subtype of a signature type @code{S} independent of +any inheritance hierarchy as long as all the member functions declared +in @code{S} are also found in @code{T}. So you can define a subtype +hierarchy that is completely independent from any inheritance +(implementation) hierarchy, instead of being forced to use types that +mirror the class inheritance hierarchy. + +@item +Signatures allow you to work with existing class hierarchies as +implementations of a signature type. If those class hierarchies are +only available in compiled form, you're out of luck with abstract virtual +classes, since an abstract virtual class cannot be retrofitted on top of +existing class hierarchies. So you would be required to write interface +classes as subtypes of the abstract virtual class. +@end enumerate + +@cindex default implementation, signature member function +@cindex signature member function default implemention +There is one more detail about signatures. A signature declaration can +contain member function @emph{definitions} as well as member function +declarations. A signature member function with a full definition is +called a @emph{default implementation}; classes need not contain that +particular interface in order to conform. For example, a +class @code{C} can conform to the signature + +@example +signature T +@{ + int f (int); + int f0 () @{ return f (0); @}; +@}; +@end example + +@noindent +whether or not @code{C} implements the member function @samp{int f0 ()}. +If you define @code{C::f0}, that definition takes precedence; +otherwise, the default implementation @code{S::f0} applies. + +@ignore +There will be more support for signatures in the future. +Add to this doc as the implementation grows. +In particular, the following features are planned but not yet +implemented: +@itemize @bullet +@item signature references, +@item signature inheritance, +@item the @code{sigof} construct for extracting the signature information + of a class, +@item views for renaming member functions when matching a class type + with a signature type, +@item specifying exceptions with signature member functions, and +@item signature templates. +@end itemize +This list is roughly in the order in which we intend to implement +them. Watch this space for updates. +@end ignore diff --git a/gnu/usr.bin/cc/doc/gcc.texi b/gnu/usr.bin/cc/doc/gcc.texi new file mode 100644 index 0000000..3523ae5 --- /dev/null +++ b/gnu/usr.bin/cc/doc/gcc.texi @@ -0,0 +1,4525 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename gcc.info +@c @setfilename usegcc.info +@c @setfilename portgcc.info +@c To produce the full manual, use the "gcc.info" setfilename, and +@c make sure the following do NOT begin with '@c' (and the @clear lines DO) +@set INTERNALS +@set USING +@c To produce a user-only manual, use the "usegcc.info" setfilename, and +@c make sure the following does NOT begin with '@c': +@c @clear INTERNALS +@c To produce a porter-only manual, use the "portgcc.info" setfilename, +@c and make sure the following does NOT begin with '@c': +@c @clear USING + +@c i have commented out the smallbook command below, and reformatted +@c this manual in the regular book size for distribution. in addition, +@c i commented out the commands that shift the text to one or the other +@c side of the page for smallbook printing (which makes it easier for +@c the photocopying people to handle...). -mew, 15june93 + +@c (For FSF printing, turn on smallbook, comment out finalout below; +@c that is all that is needed.) + +@c smallbook + +@c i also commented out the finalout command, so if there *are* any +@c overfulls, you'll (hopefully) see the rectangle in the right hand +@c margin. -mew 15june93 +@c finalout + +@c NOTE: checks/things to do: +@c +@c -have bob do a search in all seven files for "mew" (ideally --mew, +@c but i may have forgotten the occasional "--"..). +@c -item/itemx, text after all (sub/sub)section titles, etc.. +@c -consider putting the lists of options on pp 17--> etc in columns or +@c somesuch. +@c -spellcheck +@c -continuity of phrasing; ie, bit-field vs bitfield in rtl.texi +@c -overfulls. do a search for "mew" in the files, and you will see +@c overfulls that i noted but could not deal with. +@c -have to add text: beginning of chapter 8 + +@c +@c anything else? --mew 10feb93 + + + +@ifset INTERNALS +@ifset USING +@settitle Using and Porting GNU CC +@end ifset +@end ifset +@c seems reasonable to assume at least one of INTERNALS or USING is set... +@ifclear INTERNALS +@settitle Using GNU CC +@end ifclear +@ifclear USING +@settitle Porting GNU CC +@end ifclear + +@syncodeindex fn cp +@syncodeindex vr cp +@c %**end of header + +@c Use with @@smallbook. + +@c Cause even numbered pages to be printed on the left hand side of +@c the page and odd numbered pages to be printed on the right hand +@c side of the page. Using this, you can print on both sides of a +@c sheet of paper and have the text on the same part of the sheet. + +@c The text on right hand pages is pushed towards the right hand +@c margin and the text on left hand pages is pushed toward the left +@c hand margin. +@c (To provide the reverse effect, set bindingoffset to -0.75in.) + +@c @tex +@c \global\bindingoffset=0.75in +@c \global\normaloffset =0.75in +@c @end tex + +@ifinfo +@ifset INTERNALS +@ifset USING +This file documents the use and the internals of the GNU compiler. +@end ifset +@end ifset +@ifclear USING +This file documents the internals of the GNU compiler. +@end ifclear +@ifclear INTERNALS +This file documents the use of the GNU compiler. +@end ifclear + +Published by the Free Software Foundation +675 Massachusetts Avenue +Cambridge, MA 02139 USA + +Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``GNU General Public License,'' ``Funding for Free +Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the sections entitled ``GNU General Public License,'' +``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look +And Feel'@w{}'', and this permission notice, may be included in +translations approved by the Free Software Foundation instead of in the +original English. +@end ifinfo + +@setchapternewpage odd + +@titlepage +@ifset INTERNALS +@ifset USING +@center @titlefont{Using and Porting GNU CC} + +@end ifset +@end ifset +@ifclear INTERNALS +@title Using GNU CC +@end ifclear +@ifclear USING +@title Porting GNU CC +@end ifclear +@sp 2 +@center Richard M. Stallman +@sp 3 +@center Last updated 19 September 1994 +@sp 1 +@c The version number appears twice more in this file. + +@center for version 2.6 +@c @center (preliminary draft, which will change) +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1988, 89, 92, 93, 1994 Free Software Foundation, Inc. +@sp 2 +For GCC Version 2.6.@* +@c Printed November, 1994.@* + +@c ISBN 1-882114-35-3 +@sp 1 +Published by the Free Software Foundation @* +675 Massachusetts Avenue @* +Cambridge, MA 02139 USA +@sp 1 +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``GNU General Public License,'' ``Funding for Free +Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the sections entitled ``GNU General Public License,'' +``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look +And Feel'@w{}'', and this permission notice, may be included in +translations approved by the Free Software Foundation instead of in the +original English. +@end titlepage +@page + +@ifinfo + +@node Top, Copying,, (DIR) +@top Introduction +@cindex introduction + +@ifset INTERNALS +@ifset USING +This manual documents how to run, install and port the GNU +compiler, as well as its new features and incompatibilities, and how to +report bugs. It corresponds to GNU CC version 2.6. +@end ifset +@end ifset + +@ifclear INTERNALS +This manual documents how to run and install the GNU compiler, +as well as its new features and incompatibilities, and how to report +bugs. It corresponds to GNU CC version 2.6. +@end ifclear +@ifclear USING +This manual documents how to port the GNU compiler, +as well as its new features and incompatibilities, and how to report +bugs. It corresponds to GNU CC version 2.6. +@end ifclear + +@end ifinfo +@menu +* Copying:: GNU General Public License says + how you can copy and share GNU CC. +* Contributors:: People who have contributed to GNU CC. +* Funding:: How to help assure funding for free software. +* Look and Feel:: Protect your freedom---fight ``look and feel''. +@ifset USING +* G++ and GCC:: You can compile C or C++ programs. +* Invoking GCC:: Command options supported by @samp{gcc}. +* Installation:: How to configure, compile and install GNU CC. +* C Extensions:: GNU extensions to the C language family. +* C++ Extensions:: GNU extensions to the C++ language. +* Trouble:: If you have trouble installing GNU CC. +* Bugs:: How, why and where to report bugs. +* Service:: How to find suppliers of support for GNU CC. +* VMS:: Using GNU CC on VMS. +@end ifset +@ifset INTERNALS +* Portability:: Goals of GNU CC's portability features. +* Interface:: Function-call interface of GNU CC output. +* Passes:: Order of passes, what they do, and what each file is for. +* RTL:: The intermediate representation that most passes work on. +* Machine Desc:: How to write machine description instruction patterns. +* Target Macros:: How to write the machine description C macros. +* Config:: Writing the @file{xm-@var{machine}.h} file. +@end ifset + +* Index:: Index of concepts and symbol names. +@end menu + +@node Copying +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +675 Mass Ave, Cambridge, MA 02139, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `show c' for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@smallexample +Yoyodyne, Inc., hereby disclaims all copyright interest in the program +`Gnomovision' (which makes passes at compilers) written by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end smallexample + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +@node Contributors +@unnumbered Contributors to GNU CC +@cindex contributors + +In addition to Richard Stallman, several people have written parts +of GNU CC. + +@itemize @bullet +@item +The idea of using RTL and some of the optimization ideas came from the +program PO written at the University of Arizona by Jack Davidson and +Christopher Fraser. See ``Register Allocation and Exhaustive Peephole +Optimization'', Software Practice and Experience 14 (9), Sept. 1984, +857-866. + +@item +Paul Rubin wrote most of the preprocessor. + +@item +Leonard Tower wrote parts of the parser, RTL generator, and RTL +definitions, and of the Vax machine description. + +@item +Ted Lemon wrote parts of the RTL reader and printer. + +@item +Jim Wilson implemented loop strength reduction and some other +loop optimizations. + +@item +Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed +the support for the Sony NEWS machine. + +@item +Charles LaBrec contributed the support for the Integrated Solutions +68020 system. + +@item +Michael Tiemann of Cygnus Support wrote the front end for C++, as well +as the support for inline functions and instruction scheduling. Also +the descriptions of the National Semiconductor 32000 series cpu, the +SPARC cpu and part of the Motorola 88000 cpu. + +@item +Gerald Baumgartner added the signature extension to the C++ front-end. + +@item +Jan Stein of the Chalmers Computer Society provided support for +Genix, as well as part of the 32000 machine description. + +@item +Randy Smith finished the Sun FPA support. + +@item +Robert Brown implemented the support for Encore 32000 systems. + +@item +David Kashtan of SRI adapted GNU CC to the Vomit-Making System (VMS). + +@item +Alex Crain provided changes for the 3b1. + +@item +Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for +the 9000 series 300. + +@item +William Schelter did most of the work on the Intel 80386 support. + +@item +Christopher Smith did the port for Convex machines. + +@item +Paul Petersen wrote the machine description for the Alliant FX/8. + +@item +Dario Dariol contributed the four varieties of sample programs +that print a copy of their source. + +@item +Alain Lichnewsky ported GNU CC to the Mips cpu. + +@item +Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the Tahoe. + +@item +Jonathan Stone wrote the machine description for the Pyramid computer. + +@item +Gary Miller ported GNU CC to Charles River Data Systems machines. + +@item +Richard Kenner of the New York University Ultracomputer Research +Laboratory wrote the machine descriptions for the AMD 29000, the DEC +Alpha, the IBM RT PC, and the IBM RS/6000 as well as the support for +instruction attributes. He also made changes to better support RISC +processors including changes to common subexpression elimination, +strength reduction, function calling sequence handling, and condition +code support, in addition to generalizing the code for frame pointer +elimination. + +@item +Richard Kenner and Michael Tiemann jointly developed reorg.c, the delay +slot scheduler. + +@item +Mike Meissner and Tom Wood of Data General finished the port to the +Motorola 88000. + +@item +Masanobu Yuhara of Fujitsu Laboratories implemented the machine +description for the Tron architecture (specifically, the Gmicro). + +@item +NeXT, Inc.@: donated the front end that supports the Objective C +language. +@c We need to be careful to make it clear that "Objective C" +@c is the name of a language, not that of a program or product. + +@item +James van Artsdalen wrote the code that makes efficient use of +the Intel 80387 register stack. + +@item +Mike Meissner at the Open Software Foundation finished the port to the +MIPS cpu, including adding ECOFF debug support, and worked on the +Intel port for the Intel 80386 cpu. + +@item +Ron Guilmette implemented the @code{protoize} and @code{unprotoize} +tools, the support for Dwarf symbolic debugging information, and much of +the support for System V Release 4. He has also worked heavily on the +Intel 386 and 860 support. + +@item +Torbjorn Granlund of the Swedish Institute of Computer Science +implemented multiply-by-constant optimization and better long long +support, and improved leaf function register allocation. + +@item +Mike Stump implemented the support for Elxsi 64 bit CPU. + +@item +John Wehle added the machine description for the Western Electric 32000 +processor used in several 3b series machines (no relation to the +National Semiconductor 32000 processor). + +@ignore @c These features aren't advertised yet, since they don't fully work. +@item +Analog Devices helped implement the support for complex data types +and iterators. +@end ignore + +@item +Holger Teutsch provided the support for the Clipper cpu. + +@item +Kresten Krab Thorup wrote the run time support for the Objective C +language. + +@item +Stephen Moshier contributed the floating point emulator that assists in +cross-compilation and permits support for floating point numbers wider +than 64 bits. + +@item +David Edelsohn contributed the changes to RS/6000 port to make it +support the PowerPC and POWER2 architectures. + +@item +Steve Chamberlain wrote the support for the Hitachi SH processor. + +@item +Peter Schauer wrote the code to allow debugging to work on the Alpha. + +@item +Oliver M. Kellogg of Deutsche Aerospace contributed the port to the +MIL-STD-1750A. +@end itemize + +@node Funding +@chapter Funding Free Software + +If you want to have more free software a few years from now, it makes +sense for you to help encourage people to contribute funds for its +development. The most effective approach known is to encourage +commercial redistributors to donate. + +Users of free software systems can boost the pace of development by +encouraging for-a-fee distributors to donate part of their selling price +to free software developers---the Free Software Foundation, and others. + +The way to convince distributors to do this is to demand it and expect +it from them. So when you compare distributors, judge them partly by +how much they give to free software development. Show distributors +they must compete to be the one who gives the most. + +To make this approach work, you must insist on numbers that you can +compare, such as, ``We will donate ten dollars to the Frobnitz project +for each disk sold.'' Don't be satisfied with a vague promise, such as +``A portion of the profits are donated,'' since it doesn't give a basis +for comparison. + +Even a precise fraction ``of the profits from this disk'' is not very +meaningful, since creative accounting and unrelated business decisions +can greatly alter what fraction of the sales price counts as profit. +If the price you pay is $50, ten percent of the profit is probably +less than a dollar; it might be a few cents, or nothing at all. + +Some redistributors do development work themselves. This is useful too; +but to keep everyone honest, you need to inquire how much they do, and +what kind. Some kinds of development make much more long-term +difference than others. For example, maintaining a separate version of +a program contributes very little; maintaining the standard version of a +program for the whole community contributes much. Easy new ports +contribute little, since someone else would surely do them; difficult +ports such as adding a new CPU to the GNU C compiler contribute more; +major new features or packages contribute the most. + +By establishing the idea that supporting further development is ``the +proper thing to do'' when distributing free software for a fee, we can +assure a steady flow of resources into making more free software. + +@display +Copyright (C) 1994 Free Software Foundation, Inc. +Verbatim copying and redistribution of this section is permitted +without royalty; alteration is not permitted. +@end display + +@node Look and Feel +@chapter Protect Your Freedom---Fight ``Look And Feel'' +@c the above chapter heading overflows onto the next line. --mew 1/26/93 + +@quotation +@i{This section is a political message from the League for Programming +Freedom to the users of GNU CC. We have included it here because the +issue of interface copyright is important to the GNU project.} +@end quotation + +Apple and Lotus have tried to create a new form of legal monopoly: a +copyright on a user interface. + +An interface is a kind of language---a set of conventions for +communication between two entities, human or machine. Until a few years +ago, the law seemed clear: interfaces were outside the domain of +copyright, so programmers could program freely and implement whatever +interface the users demanded. Imitating de-facto standard interfaces, +sometimes with improvements, was standard practice in the computer +field. These improvements, if accepted by the users, caught on and +became the norm; in this way, much progress took place. + +Computer users, and most software developers, were happy with this state +of affairs. However, large companies such as Apple and Lotus would +prefer a different system---one in which they can own interfaces and +thereby rid themselves of all serious competitors. They hope that +interface copyright will give them, in effect, monopolies on major +classes of software. + +Other large companies such as IBM and Digital also favor interface +monopolies, for the same reason: if languages become property, they +expect to own many de-facto standard languages. But Apple and Lotus are +the ones who have actually sued. Lotus has won lawsuits against two +small companies, which were thus put out of business. Then they sued +Borland; this case is now before the court of appeals. Apple's lawsuit +against HP and Microsoft is also being decided by an appeals court. +Widespread rumors that Apple had lost the case are untrue; as of July +1994, the final outcome is unknown. + +If the monopolists get their way, they will hobble the software field: + +@itemize @bullet +@item +Gratuitous incompatibilities will burden users. Imagine if each car +manufacturer had to design a different way to start, stop, and steer a +car. + +@item +Users will be ``locked in'' to whichever interface they learn; then they +will be prisoners of one supplier, who will charge a monopolistic price. + +@item +Large companies have an unfair advantage wherever lawsuits become +commonplace. Since they can afford to sue, they can intimidate smaller +developers with threats even when they don't really have a case. + +@item +Interface improvements will come slower, since incremental evolution +through creative partial imitation will no longer occur. +@end itemize + +If interface monopolies are accepted, other large companies are waiting +to grab theirs: + +@itemize @bullet +@item +Adobe is expected to claim a monopoly on the interfaces of various popular +application programs, if Borland's appeal against Lotus fails. + +@item +Open Computing magazine reported a Microsoft vice president as threatening +to sue people who copy the interface of Windows. +@end itemize + +Users invest a great deal of time and money in learning to use computer +interfaces. Far more, in fact, than software developers invest in +developing @emph{and even implementing} the interfaces. Whoever can own +an interface, has made its users into captives, and misappropriated +their investment. + +To protect our freedom from monopolies like these, a group of +programmers and users have formed a grass-roots political organization, +the League for Programming Freedom. + +The purpose of the League is to oppose monopolistic practices such as +interface copyright and software patents. The League calls for a return +to the legal policies of the recent past, in which programmers could +program freely. The League is not concerned with free software as an +issue, and is not affiliated with the Free Software Foundation. + +The League's activities include publicizing the issue, as is being done +here, and filing friend-of-the-court briefs on behalf of defendants sued +by monopolists. Recently the League filed a friend-of-the-court brief +for Borland in its appeal against Lotus. + +The League's membership rolls include John McCarthy, inventor of Lisp, +Marvin Minsky, founder of the MIT Artificial Intelligence lab, Guy L. +Steele, Jr., author of well-known books on Lisp and C, as well as +Richard Stallman, the developer of GNU CC. Please join and add your +name to the list. Membership dues in the League are $42 per year for +programmers, managers and professionals; $10.50 for students; $21 for +others. + +Activist members are especially important, but members who have no time +to give are also important. Surveys at major ACM conferences have +indicated a vast majority of attendees agree with the League. If just +ten percent of the programmers who agree with the League join the +League, we will probably triumph. + +To join, or for more information, phone (617) 243-4091 or write to: + +@display +League for Programming Freedom +1 Kendall Square #143 +P.O. Box 9171 +Cambridge, MA 02139 +@end display + +You can also send electronic mail to @code{lpf@@uunet.uu.net}. + +In addition to joining the League, here are some suggestions from the +League for other things you can do to protect your freedom to write +programs: + +@itemize @bullet +@item +Tell your friends and colleagues about this issue and how it threatens +to ruin the computer industry. + +@item +Mention that you are a League member in your @file{.signature}, and +mention the League's email address for inquiries. + +@item +Ask the companies you consider working for or working with to make +statements against software monopolies, and give preference to those +that do. + +@item +When employers ask you to sign contracts giving them copyright or patent +rights, insist on clauses saying they can use these rights only +defensively. Don't rely on ``company policy,'' since that can change at +any time; don't rely on an individual executive's private word, since +that person may be replaced. Get a commitment just as binding as the +commitment they get from you. + +@item +Write to Congress to explain the importance of this issue. + +@display +House Subcommittee on Intellectual Property +2137 Rayburn Bldg +Washington, DC 20515 + +Senate Subcommittee on Patents, Trademarks and Copyrights +United States Senate +Washington, DC 20510 +@end display + +(These committees have received lots of mail already; let's give them +even more.) +@end itemize + +Democracy means nothing if you don't use it. Stand up and be counted! +@ifset USING +@node G++ and GCC +@chapter Compile C, C++, or Objective C + +@cindex Objective C +The C, C++, and Objective C versions of the compiler are integrated; the +GNU C compiler can compile programs written in C, C++, or Objective C. + +@cindex GCC +``GCC'' is a common shorthand term for the GNU C compiler. This is both +the most general name for the compiler, and the name used when the +emphasis is on compiling C programs. + +@cindex C++ +@cindex G++ +When referring to C++ compilation, it is usual to call the compiler +``G++''. Since there is only one compiler, it is also accurate to call +it ``GCC'' no matter what the language context; however, the term +``G++'' is more useful when the emphasis is on compiling C++ programs. + +We use the name ``GNU CC'' to refer to the compilation system as a +whole, and more specifically to the language-independent part of the +compiler. For example, we refer to the optimization options as +affecting the behavior of ``GNU CC'' or sometimes just ``the compiler''. + +Front ends for other languages, such as Ada 9X, Fortran, Modula-3, and +Pascal, are under development. These front-ends, like that for C++, are +built in subdirectories of GNU CC and link to it. The result is an +integrated compiler that can compile programs written in C, C++, +Objective C, or any of the languages for which you have installed front +ends. + +In this manual, we only discuss the options for the C, Objective-C, and +C++ compilers and those of the GNU CC core. Consult the documentation +of the other front ends for the options to use when compiling programs +written in other languages. + +@cindex compiler compared to C++ preprocessor +@cindex intermediate C version, nonexistent +@cindex C intermediate output, nonexistent +G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object +code directly from your C++ program source. There is no intermediate C +version of the program. (By contrast, for example, some other +implementations use a program that generates a C program from your C++ +source.) Avoiding an intermediate C representation of the program means +that you get better object code, and better debugging information. The +GNU debugger, GDB, works with this information in the object code to +give you comprehensive C++ source-level editing capabilities +(@pxref{C,,C and C++,gdb.info, Debugging with GDB}). + +@c FIXME! Someone who knows something about Objective C ought to put in +@c a paragraph or two about it here, and move the index entry down when +@c there is more to point to than the general mention in the 1st par. + +@include invoke.texi + +@include install.texi + +@include extend.texi + +@node Trouble +@chapter Known Causes of Trouble with GNU CC +@cindex bugs, known +@cindex installation trouble +@cindex known causes of trouble + +This section describes known problems that affect users of GNU CC. Most +of these are not GNU CC bugs per se---if they were, we would fix them. +But the result for a user may be like the result of a bug. + +Some of these problems are due to bugs in other software, some are +missing features that are too much work to add, and some are places +where people's opinions differ as to what is best. + +@menu +* Actual Bugs:: Bugs we will fix later. +* Installation Problems:: Problems that manifest when you install GNU CC. +* Cross-Compiler Problems:: Common problems of cross compiling with GNU CC. +* Interoperation:: Problems using GNU CC with other compilers, + and with certain linkers, assemblers and debuggers. +* External Bugs:: Problems compiling certain programs. +* Incompatibilities:: GNU CC is incompatible with traditional C. +* Fixed Headers:: GNU C uses corrected versions of system header files. + This is necessary, but doesn't always work smoothly. +* Disappointments:: Regrettable things we can't change, but not quite bugs. +* C++ Misunderstandings:: Common misunderstandings with GNU C++. +* Protoize Caveats:: Things to watch out for when using @code{protoize}. +* Non-bugs:: Things we think are right, but some others disagree. +* Warnings and Errors:: Which problems in your code get warnings, + and which get errors. +@end menu + +@node Actual Bugs +@section Actual Bugs We Haven't Fixed Yet + +@itemize @bullet +@item +The @code{fixincludes} script interacts badly with automounters; if the +directory of system header files is automounted, it tends to be +unmounted while @code{fixincludes} is running. This would seem to be a +bug in the automounter. We don't know any good way to work around it. + +@item +The @code{fixproto} script will sometimes add prototypes for the +@code{sigsetjmp} and @code{siglongjmp} functions that reference the +@code{jmp_buf} type before that type is defined. To work around this, +edit the offending file and place the typedef in front of the +prototypes. + +@item +There are several obscure case of mis-using struct, union, and +enum tags that are not detected as errors by the compiler. + +@item +When @samp{-pedantic-errors} is specified, GNU C will incorrectly give +an error message when a function name is specified in an expression +involving the comma operator. + +@item +Loop unrolling doesn't work properly for certain C++ programs. This is +a bug in the C++ front end. It sometimes emits incorrect debug info, and +the loop unrolling code is unable to recover from this error. +@end itemize + +@node Installation Problems +@section Installation Problems + +This is a list of problems (and some apparent problems which don't +really mean anything is wrong) that show up during installation of GNU +CC. + +@itemize @bullet +@item +On certain systems, defining certain environment variables such as +@code{CC} can interfere with the functioning of @code{make}. + +@item +If you encounter seemingly strange errors when trying to build the +compiler in a directory other than the source directory, it could be +because you have previously configured the compiler in the source +directory. Make sure you have done all the necessary preparations. +@xref{Other Dir}. + +@item +If you build GNU CC on a BSD system using a directory stored in a System +V file system, problems may occur in running @code{fixincludes} if the +System V file system doesn't support symbolic links. These problems +result in a failure to fix the declaration of @code{size_t} in +@file{sys/types.h}. If you find that @code{size_t} is a signed type and +that type mismatches occur, this could be the cause. + +The solution is not to use such a directory for building GNU CC. + +@item +In previous versions of GNU CC, the @code{gcc} driver program looked for +@code{as} and @code{ld} in various places; for example, in files +beginning with @file{/usr/local/lib/gcc-}. GNU CC version 2 looks for +them in the directory +@file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}. + +Thus, to use a version of @code{as} or @code{ld} that is not the system +default, for example @code{gas} or GNU @code{ld}, you must put them in +that directory (or make links to them from that directory). + +@item +Some commands executed when making the compiler may fail (return a +non-zero status) and be ignored by @code{make}. These failures, which +are often due to files that were not found, are expected, and can safely +be ignored. + +@item +It is normal to have warnings in compiling certain files about +unreachable code and about enumeration type clashes. These files' names +begin with @samp{insn-}. Also, @file{real.c} may get some warnings that +you can ignore. + +@item +Sometimes @code{make} recompiles parts of the compiler when installing +the compiler. In one case, this was traced down to a bug in +@code{make}. Either ignore the problem or switch to GNU Make. + +@item +If you have installed a program known as purify, you may find that it +causes errors while linking @code{enquire}, which is part of building +GNU CC. The fix is to get rid of the file @code{real-ld} which purify +installs---so that GNU CC won't try to use it. + +@item +On Linux SLS 1.01, there is a problem with @file{libc.a}: it does not +contain the obstack functions. However, GNU CC assumes that the obstack +functions are in @file{libc.a} when it is the GNU C library. To work +around this problem, change the @code{__GNU_LIBRARY__} conditional +around line 31 to @samp{#if 1}. + +@item +On some 386 systems, building the compiler never finishes because +@code{enquire} hangs due to a hardware problem in the motherboard---it +reports floating point exceptions to the kernel incorrectly. You can +install GNU CC except for @file{float.h} by patching out the command to +run @code{enquire}. You may also be able to fix the problem for real by +getting a replacement motherboard. This problem was observed in +Revision E of the Micronics motherboard, and is fixed in Revision F. +It has also been observed in the MYLEX MXA-33 motherboard. + +If you encounter this problem, you may also want to consider removing +the FPU from the socket during the compilation. Alternatively, if you +are running SCO Unix, you can reboot and force the FPU to be ignored. +To do this, type @samp{hd(40)unix auto ignorefpu}. + +@item +On some 386 systems, GNU CC crashes trying to compile @file{enquire.c}. +This happens on machines that don't have a 387 FPU chip. On 386 +machines, the system kernel is supposed to emulate the 387 when you +don't have one. The crash is due to a bug in the emulator. + +One of these systems is the Unix from Interactive Systems: 386/ix. +On this system, an alternate emulator is provided, and it does work. +To use it, execute this command as super-user: + +@example +ln /etc/emulator.rel1 /etc/emulator +@end example + +@noindent +and then reboot the system. (The default emulator file remains present +under the name @file{emulator.dflt}.) + +Try using @file{/etc/emulator.att}, if you have such a problem on the +SCO system. + +Another system which has this problem is Esix. We don't know whether it +has an alternate emulator that works. + +On NetBSD 0.8, a similar problem manifests itself as these error messages: + +@example +enquire.c: In function `fprop': +enquire.c:2328: floating overflow +@end example + +@item +On SCO systems, when compiling GNU CC with the system's compiler, +do not use @samp{-O}. Some versions of the system's compiler miscompile +GNU CC with @samp{-O}. + +@cindex @code{genflags}, crash on Sun 4 +@item +Sometimes on a Sun 4 you may observe a crash in the program +@code{genflags} or @code{genoutput} while building GNU CC. This is said to +be due to a bug in @code{sh}. You can probably get around it by running +@code{genflags} or @code{genoutput} manually and then retrying the +@code{make}. + +@item +On Solaris 2, executables of GNU CC version 2.0.2 are commonly +available, but they have a bug that shows up when compiling current +versions of GNU CC: undefined symbol errors occur during assembly if you +use @samp{-g}. + +The solution is to compile the current version of GNU CC without +@samp{-g}. That makes a working compiler which you can use to recompile +with @samp{-g}. + +@item +Solaris 2 comes with a number of optional OS packages. Some of these +packages are needed to use GNU CC fully. If you did not install all +optional packages when installing Solaris, you will need to verify that +the packages that GNU CC needs are installed. + +To check whether an optional package is installed, use +the @code{pkginfo} command. To add an optional package, use the +@code{pkgadd} command. For further details, see the Solaris +documentation. + +For Solaris 2.0 and 2.1, GNU CC needs six packages: @samp{SUNWarc}, +@samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and +@samp{SUNWtoo}. + +For Solaris 2.2, GNU CC needs an additional seventh package: @samp{SUNWsprot}. + +@item +On Solaris 2, trying to use the linker and other tools in +@file{/usr/ucb} to install GNU CC has been observed to cause trouble. +For example, the linker may hang indefinitely. The fix is to remove +@file{/usr/ucb} from your @code{PATH}. + +@item +If you use the 1.31 version of the MIPS assembler (such as was shipped +with Ultrix 3.1), you will need to use the -fno-delayed-branch switch +when optimizing floating point code. Otherwise, the assembler will +complain when the GCC compiler fills a branch delay slot with a +floating point instruction, such as @code{add.d}. + +@item +If on a MIPS system you get an error message saying ``does not have gp +sections for all it's [sic] sectons [sic]'', don't worry about it. This +happens whenever you use GAS with the MIPS linker, but there is not +really anything wrong, and it is okay to use the output file. You can +stop such warnings by installing the GNU linker. + +It would be nice to extend GAS to produce the gp tables, but they are +optional, and there should not be a warning about their absence. + +@item +In Ultrix 4.0 on the MIPS machine, @file{stdio.h} does not work with GNU +CC at all unless it has been fixed with @code{fixincludes}. This causes +problems in building GNU CC. Once GNU CC is installed, the problems go +away. + +To work around this problem, when making the stage 1 compiler, specify +this option to Make: + +@example +GCC_FOR_TARGET="./xgcc -B./ -I./include" +@end example + +When making stage 2 and stage 3, specify this option: + +@example +CFLAGS="-g -I./include" +@end example + +@item +Users have reported some problems with version 2.0 of the MIPS +compiler tools that were shipped with Ultrix 4.1. Version 2.10 +which came with Ultrix 4.2 seems to work fine. + +Users have also reported some problems with version 2.20 of the +MIPS compiler tools that were shipped with RISC/os 4.x. The earlier +version 2.11 seems to work fine. + +@item +Some versions of the MIPS linker will issue an assertion failure +when linking code that uses @code{alloca} against shared +libraries on RISC-OS 5.0, and DEC's OSF/1 systems. This is a bug +in the linker, that is supposed to be fixed in future revisions. +To protect against this, GNU CC passes @samp{-non_shared} to the +linker unless you pass an explicit @samp{-shared} or +@samp{-call_shared} switch. + +@item +On System V release 3, you may get this error message +while linking: + +@smallexample +ld fatal: failed to write symbol name @var{something} + in strings table for file @var{whatever} +@end smallexample + +This probably indicates that the disk is full or your ULIMIT won't allow +the file to be as large as it needs to be. + +This problem can also result because the kernel parameter @code{MAXUMEM} +is too small. If so, you must regenerate the kernel and make the value +much larger. The default value is reported to be 1024; a value of 32768 +is said to work. Smaller values may also work. + +@item +On System V, if you get an error like this, + +@example +/usr/local/lib/bison.simple: In function `yyparse': +/usr/local/lib/bison.simple:625: virtual memory exhausted +@end example + +@noindent +that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}. + +@item +Current GNU CC versions probably do not work on version 2 of the NeXT +operating system. + +@item +On NeXTStep 3.0, the Objective C compiler does not work, due, +apparently, to a kernel bug that it happens to trigger. This problem +does not happen on 3.1. + +@item +On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not +allowed to have more than one megabyte of memory. GNU CC cannot compile +itself (or many other programs) with @samp{-O} in that much memory. + +To solve this problem, reconfigure the kernel adding the following line +to the configuration file: + +@smallexample +MAXUMEM = 4096 +@end smallexample + +@item +On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug +in the assembler that must be fixed before GNU CC can be built. This +bug manifests itself during the first stage of compilation, while +building @file{libgcc2.a}: + +@smallexample +_floatdisf +cc1: warning: `-g' option not supported on this version of GCC +cc1: warning: `-g1' option not supported on this version of GCC +./xgcc: Internal compiler error: program as got fatal signal 11 +@end smallexample + +A patched version of the assembler is available by anonymous ftp from +@code{altdorf.ai.mit.edu} as the file +@file{archive/cph/hpux-8.0-assembler}. If you have HP software support, +the patch can also be obtained directly from HP, as described in the +following note: + +@quotation +This is the patched assembler, to patch SR#1653-010439, where the +assembler aborts on floating point constants. + +The bug is not really in the assembler, but in the shared library +version of the function ``cvtnum(3c)''. The bug on ``cvtnum(3c)'' is +SR#4701-078451. Anyway, the attached assembler uses the archive +library version of ``cvtnum(3c)'' and thus does not exhibit the bug. +@end quotation + +This patch is also known as PHCO_4484. + +@item +On HP-UX version 8.05, but not on 8.07 or more recent versions, +the @code{fixproto} shell script triggers a bug in the system shell. +If you encounter this problem, upgrade your operating system or +use BASH (the GNU shell) to run @code{fixproto}. + +@item +Some versions of the Pyramid C compiler are reported to be unable to +compile GNU CC. You must use an older version of GNU CC for +bootstrapping. One indication of this problem is if you get a crash +when GNU CC compiles the function @code{muldi3} in file @file{libgcc2.c}. + +You may be able to succeed by getting GNU CC version 1, installing it, +and using it to compile GNU CC version 2. The bug in the Pyramid C +compiler does not seem to affect GNU CC version 1. + +@item +There may be similar problems on System V Release 3.1 on 386 systems. + +@item +On the Intel Paragon (an i860 machine), if you are using operating +system version 1.0, you will get warnings or errors about redefinition +of @code{va_arg} when you build GNU CC. + +If this happens, then you need to link most programs with the library +@file{iclib.a}. You must also modify @file{stdio.h} as follows: before +the lines + +@example +#if defined(__i860__) && !defined(_VA_LIST) +#include <va_list.h> +@end example + +@noindent +insert the line + +@example +#if __PGC__ +@end example + +@noindent +and after the lines + +@example +extern int vprintf(const char *, va_list ); +extern int vsprintf(char *, const char *, va_list ); +#endif +@end example + +@noindent +insert the line + +@example +#endif /* __PGC__ */ +@end example + +These problems don't exist in operating system version 1.1. + +@item +On the Altos 3068, programs compiled with GNU CC won't work unless you +fix a kernel bug. This happens using system versions V.2.2 1.0gT1 and +V.2.2 1.0e and perhaps later versions as well. See the file +@file{README.ALTOS}. + +@item +You will get several sorts of compilation and linking errors on the +we32k if you don't follow the special instructions. @xref{Configurations}. + +@item +A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto +program to report an error of the form: + +@example +./fixproto: sh internal 1K buffer overflow +@end example + +To fix this, change the first line of the fixproto script to look like: + +@example +#!/bin/ksh +@end example +@end itemize + +@node Cross-Compiler Problems +@section Cross-Compiler Problems + +You may run into problems with cross compilation on certain machines, +for several reasons. + +@itemize @bullet +@item +Cross compilation can run into trouble for certain machines because +some target machines' assemblers require floating point numbers to be +written as @emph{integer} constants in certain contexts. + +The compiler writes these integer constants by examining the floating +point value as an integer and printing that integer, because this is +simple to write and independent of the details of the floating point +representation. But this does not work if the compiler is running on +a different machine with an incompatible floating point format, or +even a different byte-ordering. + +In addition, correct constant folding of floating point values +requires representing them in the target machine's format. +(The C standard does not quite require this, but in practice +it is the only way to win.) + +It is now possible to overcome these problems by defining macros such +as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of +work for each target machine. +@ifset INTERNALS +@xref{Cross-compilation}. +@end ifset +@ifclear INTERNALS +@xref{Cross-compilation,,Cross Compilation and Floating Point Format, +gcc.info, Using and Porting GCC}. +@end ifclear + +@item +At present, the program @file{mips-tfile} which adds debug +support to object files on MIPS systems does not work in a cross +compile environment. +@end itemize + +@node Interoperation +@section Interoperation + +This section lists various difficulties encountered in using GNU C or +GNU C++ together with other compilers or with the assemblers, linkers, +libraries and debuggers on certain systems. + +@itemize @bullet +@item +Objective C does not work on the RS/6000. + +@item +GNU C++ does not do name mangling in the same way as other C++ +compilers. This means that object files compiled with one compiler +cannot be used with another. + +This effect is intentional, to protect you from more subtle problems. +Compilers differ as to many internal details of C++ implementation, +including: how class instances are laid out, how multiple inheritance is +implemented, and how virtual function calls are handled. If the name +encoding were made the same, your programs would link against libraries +provided from other compilers---but the programs would then crash when +run. Incompatible libraries are then detected at link time, rather than +at run time. + +@item +Older GDB versions sometimes fail to read the output of GNU CC version +2. If you have trouble, get GDB version 4.4 or later. + +@item +@cindex DBX +DBX rejects some files produced by GNU CC, though it accepts similar +constructs in output from PCC. Until someone can supply a coherent +description of what is valid DBX input and what is not, there is +nothing I can do about these problems. You are on your own. + +@item +The GNU assembler (GAS) does not support PIC. To generate PIC code, you +must use some other assembler, such as @file{/bin/as}. + +@item +On some BSD systems, including some versions of Ultrix, use of profiling +causes static variable destructors (currently used only in C++) not to +be run. + +@item +Use of @samp{-I/usr/include} may cause trouble. + +Many systems come with header files that won't work with GNU CC unless +corrected by @code{fixincludes}. The corrected header files go in a new +directory; GNU CC searches this directory before @file{/usr/include}. +If you use @samp{-I/usr/include}, this tells GNU CC to search +@file{/usr/include} earlier on, before the corrected headers. The +result is that you get the uncorrected header files. + +Instead, you should use these options (when compiling C programs): + +@smallexample +-I/usr/local/lib/gcc-lib/@var{target}/@var{version}/include -I/usr/include +@end smallexample + +For C++ programs, GNU CC also uses a special directory that defines C++ +interfaces to standard C subroutines. This directory is meant to be +searched @emph{before} other standard include directories, so that it +takes precedence. If you are compiling C++ programs and specifying +include directories explicitly, use this option first, then the two +options above: + +@example +-I/usr/local/lib/g++-include +@end example + +@ignore +@cindex @code{vfork}, for the Sun-4 +@item +There is a bug in @code{vfork} on the Sun-4 which causes the registers +of the child process to clobber those of the parent. Because of this, +programs that call @code{vfork} are likely to lose when compiled +optimized with GNU CC when the child code alters registers which contain +C variables in the parent. This affects variables which are live in the +parent across the call to @code{vfork}. + +If you encounter this, you can work around the problem by declaring +variables @code{volatile} in the function that calls @code{vfork}, until +the problem goes away, or by not declaring them @code{register} and not +using @samp{-O} for those source files. +@end ignore + +@item +On some SGI systems, when you use @samp{-lgl_s} as an option, +it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}. +Naturally, this does not happen when you use GNU CC. +You must specify all three options explicitly. + +@item +On a Sparc, GNU CC 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. + +As a result, if a function compiled with Sun CC takes the address of an +argument of type @code{double} and passes this pointer of type +@code{double *} to a function compiled with GNU CC, dereferencing the +pointer may cause a fatal signal. + +One way to solve this problem is to compile your entire program with GNU +CC. Another solution is to modify the function that is compiled with +Sun CC to copy the argument into a local variable; local variables +are always properly aligned. A third solution is to modify the function +that uses the pointer to dereference it via the following function +@code{access_double} instead of directly with @samp{*}: + +@smallexample +inline double +access_double (double *unaligned_ptr) +@{ + union d2i @{ double d; int i[2]; @}; + + union d2i *p = (union d2i *) unaligned_ptr; + union d2i u; + + u.i[0] = p->i[0]; + u.i[1] = p->i[1]; + + return u.d; +@} +@end smallexample + +@noindent +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 GNU CC on the +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. + +The solution is to not use the @file{libmalloc.a} library. Use instead +@code{malloc} and related functions from @file{libc.a}; they do not have +this problem. + +@item +Sun forgot to include a static version of @file{libdl.a} with some +versions of SunOS (mainly 4.1). This results in undefined symbols when +linking static binaries (that is, if you use @samp{-static}). If you +see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen} +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 +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 doubles do not work +in Sun OS versions 4.0.3 and earlier, because the kernel eumulator uses an +obsolete and incompatible format. Long doubles do not work in Sun OS +versions 4.1.1 to 4.1.3 because of emululator bugs that cause random +unpredicatable failures. Long doubles appear to work in Sun OS 5.x +(Solaris 2.x). + +@item +On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not +compile GNU CC correctly. We do not yet know why. However, GNU CC +compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can +compile itself properly on 9.01. + +@item +On the HP PA machine, ADB sometimes fails to work on functions compiled +with GNU CC. Specifically, it fails to work on functions that use +@code{alloca} or variable-size arrays. This is because GNU CC doesn't +generate HP-UX unwind descriptors for such functions. It may even be +impossible to generate them. + +@item +Debugging (@samp{-g}) is not supported on the HP PA machine, unless you use +the preliminary GNU tools (@pxref{Installation}). + +@item +Taking the address of a label may generate errors from the HP-UX +PA assembler. GAS for the PA does not have this problem. + +@item +Using floating point parameters for indirect calls to static functions +will not work when using the HP assembler. There simply is no way for GCC +to specify what registers hold arguments for static functions when using +the HP assembler. GAS for the PA does not have this problem. + +@item +For some very large functions you may receive errors from the HP linker +complaining about an out of bounds unconditional branch offset. Fixing +this problem correctly requires fixing problems in GNU CC and GAS. We +hope to fix this in time for GNU CC 2.6. Until then you can work around +by making your function smaller, and if you are using GAS, splitting the +function into multiple source files may be necessary. + +@item +GNU CC compiled code sometimes emits warnings from the HP-UX assembler of +the form: + +@smallexample +(warning) Use of GR3 when + frame >= 8192 may cause conflict. +@end smallexample + +These warnings are harmless and can be safely ignored. + +@item +The current version of the assembler (@file{/bin/as}) for the RS/6000 +has certain problems that prevent the @samp{-g} option in GCC from +working. Note that @file{Makefile.in} uses @samp{-g} by default when +compiling @file{libgcc2.c}. + +IBM has produced a fixed version of the assembler. The upgraded +assembler unfortunately was not included in any of the AIX 3.2 update +PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request +PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277. +See the file @file{README.RS6000} for more details on these updates. + +You can test for the presense of a fixed assembler by using the +command + +@smallexample +as -u < /dev/null +@end smallexample + +@noindent +If the command exits normally, the assembler fix already is installed. +If the assembler complains that "-u" is an unknown flag, you need to +order the fix. + +@item +On the IBM RS/6000, compiling code of the form + +@smallexample +extern int foo; + +@dots{} foo @dots{} + +static int foo; +@end smallexample + +@noindent +will cause the linker to report an undefined symbol @code{foo}. +Although this behavior differs from most other systems, it is not a +bug because redefining an @code{extern} variable as @code{static} +is undefined in ANSI C. + +@item +AIX on the RS/6000 provides support (NLS) for environments outside of +the United States. Compilers and assemblers use NLS to support +locale-specific representations of various objects including +floating-point numbers ("." vs "," for separating decimal fractions). +There have been problems reported where the library linked with GCC does +not produce the same floating-point formats that the assembler accepts. +If you have this problem, set the LANG environment variable to "C" or +"En_US". + +@item +Even if you specify @samp{-fdollars-in-identifiers}, +you cannot successfully use @samp{$} in identifiers on the RS/6000 due +to a restriction in the IBM assembler. GAS supports these +identifiers. + +@item +On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC +version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2 +by requesting PTF 421749 from IBM. + +@item +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. GNU CC uses +@samp{fldcr} on the 88100 to serialize volatile memory references. Use +the option @samp{-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. @xref{VMS Install}. + +@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 GNU CC no matter +what options are used. + +@cindex RT PC +@cindex IBM RT PC +@item +On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different +convention for structure and union returning. Use the option +@samp{-mhc-struct-return} to tell GNU CC to use a convention compatible +with it. + +@cindex Vax calling convention +@cindex Ultrix calling convention +@item +On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved +by function calls. However, the C compiler uses conventions compatible +with BSD Unix: registers 2 through 5 may be clobbered by function calls. + +GNU CC uses the same convention as the Ultrix C compiler. You can use +these options to produce code compatible with the Fortran compiler: + +@smallexample +-fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5 +@end smallexample + +@item +On the WE32k, you may find that programs compiled with GNU CC do not +work with the standard shared C ilbrary. 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.6.0 -lgcc -lc_s +@end smallexample + +The first specifies where to find the library @file{libgcc.a} +specified with the @samp{-lgcc} option. + +GNU CC does linking by invoking @code{ld}, just as @code{cc} does, and +there is no reason why it @emph{should} matter which compilation program +you use to invoke @code{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. + +Or use the @samp{-noasmopt} option when you compile GNU CC 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 @samp{-O0} to the assembler, and never +passes @samp{-O2} or @samp{-O3}. +@end itemize + +@node External Bugs +@section Problems Compiling Certain Programs + +@c prevent bad page break with this line +Certain programs have problems compiling. + +@itemize @bullet +@item +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 +@samp{-I/usr/include/mit} to use the MIT versions of the header files, +using the @samp{-traditional} switch to turn off ANSI C, or fixing the +header files by adding this: + +@example +#ifdef __STDC__ +#define NeedFunctionPrototypes 0 +#endif +@end example + +@item +If you have trouble compiling Perl on a SunOS 4 system, it may be +because Perl specifies @samp{-I/usr/ucbinclude}. This accesses the +unfixed header files. Perl specifies the options + +@example +-traditional -Dvolatile=__volatile__ +-I/usr/include/sun -I/usr/ucbinclude +-fpcc-struct-return +@end example + +@noindent +most of which are unnecessary with GCC 2.4.5 and newer versions. You +can make a properly working Perl by setting @code{ccflags} to +@samp{-fwritable-strings} (implied by the @samp{-traditional} in the +original options) and @code{cppflags} to empty in @file{config.sh}, then +typing @samp{./doSH; make depend; make}. + +@item +On various 386 Unix systems derived from System V, including SCO, ISC, +and ESIX, you may get error messages about running out of virtual memory +while compiling certain programs. + +You can prevent this problem by linking GNU CC with the GNU malloc +(which thus replaces the malloc that comes with the system). GNU malloc +is available as a separate package, and also in the file +@file{src/gmalloc.c} in the GNU Emacs 19 distribution. + +If you have installed GNU malloc as a separate library package, use this +option when you relink GNU CC: + +@example +MALLOC=/usr/local/lib/libgmalloc.a +@end example + +Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy +the object file to @file{gmalloc.o} and use this option when you relink +GNU CC: + +@example +MALLOC=gmalloc.o +@end example +@end itemize + +@node Incompatibilities +@section Incompatibilities of GNU CC +@cindex incompatibilities of GNU CC + +There are several noteworthy incompatibilities between GNU C and most +existing (non-ANSI) versions of C. The @samp{-traditional} option +eliminates many of these incompatibilities, @emph{but not all}, by +telling GNU C to behave like the other C compilers. + +@itemize @bullet +@cindex string constants +@cindex read-only strings +@cindex shared strings +@item +GNU CC normally makes string constants read-only. If several +identical-looking string constants are used, GNU CC stores only one +copy of the string. + +@cindex @code{mktemp}, and constant strings +One consequence is that you cannot call @code{mktemp} with a string +constant argument. The function @code{mktemp} always alters the +string its argument points to. + +@cindex @code{sscanf}, and constant strings +@cindex @code{fscanf}, and constant strings +@cindex @code{scanf}, and constant strings +Another consequence is that @code{sscanf} does not work on some systems +when passed a string constant as its format control string or input. +This is because @code{sscanf} incorrectly tries to write into the string +constant. Likewise @code{fscanf} and @code{scanf}. + +The best solution to these problems is to change the program to use +@code{char}-array variables with initialization strings for these +purposes instead of string constants. But if this is not possible, +you can use the @samp{-fwritable-strings} flag, which directs GNU CC +to handle string constants the same way most C compilers do. +@samp{-traditional} also has this effect, among others. + +@item +@code{-2147483648} is positive. + +This is because 2147483648 cannot fit in the type @code{int}, so +(following the ANSI C rules) its data type is @code{unsigned long int}. +Negating this value yields 2147483648 again. + +@item +GNU CC does not substitute macro arguments when they appear inside of +string constants. For example, the following macro in GNU CC + +@example +#define foo(a) "a" +@end example + +@noindent +will produce output @code{"a"} regardless of what the argument @var{a} is. + +The @samp{-traditional} option directs GNU CC to handle such cases +(among others) in the old-fashioned (non-ANSI) fashion. + +@cindex @code{setjmp} incompatibilities +@cindex @code{longjmp} incompatibilities +@item +When you use @code{setjmp} and @code{longjmp}, the only automatic +variables guaranteed to remain valid are those declared +@code{volatile}. This is a consequence of automatic register +allocation. Consider this function: + +@example +jmp_buf j; + +foo () +@{ + int a, b; + + a = fun1 (); + if (setjmp (j)) + return a; + + a = fun2 (); + /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */ + return a + fun3 (); +@} +@end example + +Here @code{a} may or may not be restored to its first value when the +@code{longjmp} occurs. If @code{a} is allocated in a register, then +its first value is restored; otherwise, it keeps the last value stored +in it. + +If you use the @samp{-W} option with the @samp{-O} option, you will +get a warning when GNU CC thinks such a problem might be possible. + +The @samp{-traditional} option directs GNU C to put variables in +the stack by default, rather than in registers, in functions that +call @code{setjmp}. This results in the behavior found in +traditional C compilers. + +@item +Programs that use preprocessor directives in the middle of macro +arguments do not work with GNU CC. For example, a program like this +will not work: + +@example +foobar ( +#define luser + hack) +@end example + +ANSI C does not permit such a construct. It would make sense to support +it when @samp{-traditional} is used, but it is too much work to +implement. + +@cindex external declaration scope +@cindex scope of external declarations +@cindex declaration scope +@item +Declarations of external variables and functions within a block apply +only to the block containing the declaration. In other words, they +have the same scope as any other declaration in the same place. + +In some other C compilers, a @code{extern} declaration affects all the +rest of the file even if it happens within a block. + +The @samp{-traditional} option directs GNU C to treat all @code{extern} +declarations as global, like traditional compilers. + +@item +In traditional C, you can combine @code{long}, etc., with a typedef name, +as shown here: + +@example +typedef int foo; +typedef long foo bar; +@end example + +In ANSI C, this is not allowed: @code{long} and other type modifiers +require an explicit @code{int}. Because this criterion is expressed +by Bison grammar rules rather than C code, the @samp{-traditional} +flag cannot alter it. + +@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. + +@cindex whitespace +@item +PCC allows whitespace in the middle of compound assignment operators +such as @samp{+=}. GNU CC, following the ANSI standard, does not +allow this. The difficulty described immediately above applies here +too. + +@cindex apostrophes +@cindex ' +@item +GNU CC complains about unterminated character constants inside of +preprocessor conditionals that fail. Some programs have English +comments enclosed in conditionals that are guaranteed to fail; if these +comments contain apostrophes, GNU CC will probably report an error. For +example, this code would produce an error: + +@example +#if 0 +You can't expect this to work. +#endif +@end example + +The best solution to such a problem is to put the text into an actual +C comment delimited by @samp{/*@dots{}*/}. However, +@samp{-traditional} suppresses these error messages. + +@item +Many user programs contain the declaration @samp{long time ();}. In the +past, the system header files on many systems did not actually declare +@code{time}, so it did not matter what type your program declared it to +return. But in systems with ANSI C headers, @code{time} is declared to +return @code{time_t}, and if that is not the same as @code{long}, then +@samp{long time ();} is erroneous. + +The solution is to change your program to use @code{time_t} as the return +type of @code{time}. + +@cindex @code{float} as function value type +@item +When compiling functions that return @code{float}, PCC converts it to +a double. GNU CC actually returns a @code{float}. If you are concerned +with PCC compatibility, you should declare your functions to return +@code{double}; you might as well say what you mean. + +@cindex structures +@cindex unions +@item +When compiling functions that return structures or unions, GNU CC +output code normally uses a method different from that used on most +versions of Unix. As a result, code compiled with GNU CC cannot call +a structure-returning function compiled with PCC, and vice versa. + +The method used by GNU CC is as follows: a structure or union which is +1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union +with any other size is stored into an address supplied by the caller +(usually in a special, fixed register, but on some machines it is passed +on the stack). The machine-description macros @code{STRUCT_VALUE} and +@code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address. + +By contrast, PCC on most target machines returns structures and unions +of any size by copying the data into an area of static storage, and then +returning the address of that storage as if it were a pointer value. +The caller must copy the data from that memory area to the place where +the value is wanted. GNU CC does not use this method because it is +slower and nonreentrant. + +On some newer machines, PCC uses a reentrant convention for all +structure and union returning. GNU CC on most of these machines uses a +compatible convention when returning structures and unions in memory, +but still returns small structures and unions in registers. + +You can tell GNU CC to use a compatible convention for all structure and +union returning with the option @samp{-fpcc-struct-return}. + +@cindex preprocessing tokens +@cindex preprocessing numbers +@item +GNU C complains about program fragments such as @samp{0x74ae-0x4000} +which appear to be two hexadecimal constants separated by the minus +operator. Actually, this string is a single @dfn{preprocessing token}. +Each such token must correspond to one token in C. Since this does not, +GNU C prints an error message. Although it may appear obvious that what +is meant is an operator and two values, the ANSI C standard specifically +requires that this be treated as erroneous. + +A @dfn{preprocessing token} is a @dfn{preprocessing number} if it +begins with a digit and is followed by letters, underscores, digits, +periods and @samp{e+}, @samp{e-}, @samp{E+}, or @samp{E-} character +sequences. + +To make the above program fragment valid, place whitespace in front of +the minus sign. This whitespace will end the preprocessing number. +@end itemize + +@node Fixed Headers +@section Fixed Header Files + +GNU CC needs to install corrected versions of some system header files. +This is because most target systems have some header files that won't +work with GNU CC unless they are changed. Some have bugs, some are +incompatible with ANSI C, and some depend on special features of other +compilers. + +Installing GNU CC automatically creates and installs the fixed header +files, by running a program called @code{fixincludes} (or for certain +targets an alternative such as @code{fixinc.svr4}). Normally, you +don't need to pay attention to this. But there are cases where it +doesn't do the right thing automatically. + +@itemize @bullet +@item +If you update the system's header files, such as by installing a new +system version, the fixed header files of GNU CC are not automatically +updated. The easiest way to update them is to reinstall GNU CC. (If +you want to be clever, look in the makefile and you can find a +shortcut.) + +@item +On some systems, in particular SunOS 4, header file directories contain +machine-specific symbolic links in certain places. This makes it +possible to share most of the header files among hosts running the +same version of SunOS 4 on different machine models. + +The programs that fix the header files do not understand this special +way of using symbolic links; therefore, the directory of fixed header +files is good only for the machine model used to build it. + +In SunOS 4, only programs that look inside the kernel will notice the +difference between machine models. Therefore, for most purposes, you +need not be concerned about this. + +It is possible to make separate sets of fixed header files for the +different machine models, and arrange a structure of symbolic links so +as to use the proper set, but you'll have to do this by hand. + +@item +On Lynxos, GNU CC by default does not fix the header files. This is +because bugs in the shell cause the @code{fixincludes} script to fail. + +This means you will encounter problems due to bugs in the system header +files. It may be no comfort that they aren't GNU CC's fault, but it +does mean that there's nothing for us to do about them. +@end itemize + +@node Disappointments +@section Disappointments and Misunderstandings + +These problems are perhaps regrettable, but we don't know any practical +way around them. + +@itemize @bullet +@item +Certain local variables aren't recognized by debuggers when you compile +with optimization. + +This occurs because sometimes GNU CC optimizes the variable out of +existence. There is no way to tell the debugger how to compute the +value such a variable ``would have had'', and it is not clear that would +be desirable anyway. So GNU CC simply does not mention the eliminated +variable when it writes debugging information. + +You have to expect a certain amount of disagreement between the +executable and your source code, when you use optimization. + +@cindex conflicting types +@cindex scope of declaration +@item +Users often think it is a bug when GNU CC reports an error for code +like this: + +@example +int foo (struct mumble *); + +struct mumble @{ @dots{} @}; + +int foo (struct mumble *x) +@{ @dots{} @} +@end example + +This code really is erroneous, because the scope of @code{struct +mumble} in the prototype is limited to the argument list containing it. +It does not refer to the @code{struct mumble} defined with file scope +immediately below---they are two unrelated types with similar names in +different scopes. + +But in the definition of @code{foo}, the file-scope type is used +because that is available to be inherited. Thus, the definition and +the prototype do not match, and you get an error. + +This behavior may seem silly, but it's what the ANSI standard specifies. +It is easy enough for you to make your code work by moving the +definition of @code{struct mumble} above the prototype. It's not worth +being incompatible with ANSI C just to avoid an error for the example +shown above. + +@item +Accesses to bitfields even in volatile objects works by accessing larger +objects, such as a byte or a word. You cannot rely on what size of +object is accessed in order to read or write the bitfield; it may even +vary for a given bitfield according to the precise usage. + +If you care about controlling the amount of memory that is accessed, use +volatile but do not use bitfields. + +@item +GNU CC comes with shell scripts to fix certain known problems in system +header files. They install corrected copies of various header files in +a special directory where only GNU CC will normally look for them. The +scripts adapt to various systems by searching all the system header +files for the problem cases that we know about. + +If new system header files are installed, nothing automatically arranges +to update the corrected header files. You will have to reinstall GNU CC +to fix the new header files. More specifically, go to the build +directory and delete the files @file{stmp-fixinc} and +@file{stmp-headers}, and the subdirectory @code{include}; then do +@samp{make install} again. + +@item +On 68000 systems, you can get paradoxical results if you test the +precise values of floating point numbers. For example, you can find +that a floating point value which is not a NaN is not equal to itself. +This results from the fact that the the floating point registers hold a +few more bits of precision than fit in a @code{double} in memory. +Compiled code moves values between memory and floating point registers +at its convenience, and moving them into memory truncates them. + +You can partially avoid this problem by using the @samp{-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 ANSI standard @file{stdarg.h} +method of variable arguments, and the prototype is in scope at +the time of the call, everything will work fine. +@end itemize + +@node C++ Misunderstandings +@section Common Misunderstandings with GNU C++ + +@cindex misunderstandings in C++ +@cindex surprises in C++ +@cindex C++ misunderstandings +C++ is a complex language and an evolving one, and its standard definition +(the ANSI C++ draft standard) is also evolving. As a result, +your C++ compiler may occasionally surprise you, even when its behavior is +correct. This section discusses some areas that frequently give rise to +questions of this sort. + +@menu +* Static Definitions:: Static member declarations are not definitions +* Temporaries:: Temporaries may vanish before you expect +@end menu + +@node Static Definitions +@subsection Declare @emph{and} Define Static Members + +@cindex C++ static data, declaring and defining +@cindex static data in C++, declaring and defining +@cindex declaring static data in C++ +@cindex defining static data in C++ +When a class has static data members, it is not enough to @emph{declare} +the static member; you must also @emph{define} it. For example: + +@example +class Foo +@{ + @dots{} + void method(); + static int bar; +@}; +@end example + +This declaration only establishes that the class @code{Foo} has an +@code{int} named @code{Foo::bar}, and a member function named +@code{Foo::method}. But you still need to define @emph{both} +@code{method} and @code{bar} elsewhere. According to the draft ANSI +standard, you must supply an initializer in one (and only one) source +file, such as: + +@example +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, +you may discover that a program that appeared to work correctly in fact +does not conform to the standard: @code{g++} reports as undefined +symbols any static data members that lack definitions. + +@node Temporaries +@subsection Temporaries May Vanish Before You Expect + +@cindex temporaries, lifetime of +@cindex portions of temporary objects, pointers to +It is dangerous to use pointers or references to @emph{portions} of a +temporary object. The compiler may very well delete the object before +you expect it to, leaving a pointer to garbage. The most common place +where this problem crops up is in classes like the libg++ +@code{String} class, that define a conversion function to type +@code{char *} or @code{const char *}. However, any class that returns +a pointer to some internal structure is potentially subject to this +problem. + +For example, a program may use a function @code{strfunc} that returns +@code{String} objects, and another function @code{charfunc} that +operates on pointers to @code{char}: + +@example +String strfunc (); +void charfunc (const char *); +@end example + +@noindent +In this situation, it may seem natural to write @w{@samp{charfunc +(strfunc ());}} based on the knowledge that class @code{String} has an +explicit conversion to @code{char} pointers. However, what really +happens is akin to @samp{charfunc (@w{strfunc ()}.@w{convert ()});}, +where the @code{convert} method is a function to do the same data +conversion normally performed by a cast. Since the last use of the +temporary @code{String} object is the call to the conversion function, +the compiler may delete that object before actually calling +@code{charfunc}. The compiler has no way of knowing that deleting the +@code{String} object will invalidate the pointer. The pointer then +points to garbage, so that by the time @code{charfunc} is called, it +gets an invalid argument. + +Code like this may run successfully under some other compilers, +especially those that delete temporaries relatively late. However, the +GNU C++ behavior is also standard-conformant, so if your program depends +on late destruction of temporaries it is not portable. + +If you think this is surprising, you should be aware that the ANSI C++ +committee continues to debate the lifetime-of-temporaries problem. + +For now, at least, the safe way to write such code is to give the +temporary a name, which forces it to remain until the end of the scope of +the name. For example: + +@example +String& tmp = strfunc (); +charfunc (tmp); +@end example + +@node Protoize Caveats +@section Caveats of using @code{protoize} + +The conversion programs @code{protoize} and @code{unprotoize} can +sometimes change a source file in a way that won't work unless you +rearrange it. + +@itemize @bullet +@item +@code{protoize} can insert references to a type name or type tag before +the definition, or in a file where they are not defined. + +If this happens, compiler error messages should show you where the new +references are, so fixing the file by hand is straightforward. + +@item +There are some C constructs which @code{protoize} cannot figure out. +For example, it can't determine argument types for declaring a +pointer-to-function variable; this you must do by hand. @code{protoize} +inserts a comment containing @samp{???} each time it finds such a +variable; so you can find all such variables by searching for this +string. ANSI C does not require declaring the argument types of +pointer-to-function types. + +@item +Using @code{unprotoize} can easily introduce bugs. If the program +relied on prototypes to bring about conversion of arguments, these +conversions will not take place in the program without prototypes. +One case in which you can be sure @code{unprotoize} is safe is when +you are removing prototypes that were made with @code{protoize}; if +the program worked before without any prototypes, it will work again +without them. + +You can find all the places where this problem might occur by compiling +the program with the @samp{-Wconversion} option. It prints a warning +whenever an argument is converted. + +@item +Both conversion programs can be confused if there are macro calls in and +around the text to be converted. In other words, the standard syntax +for a declaration or definition must not result from expanding a macro. +This problem is inherent in the design of C and cannot be fixed. If +only a few functions have confusing macro calls, you can easily convert +them manually. + +@item +@code{protoize} cannot get the argument types for a function whose +definition was not actually compiled due to preprocessor conditionals. +When this happens, @code{protoize} changes nothing in regard to such +a function. @code{protoize} tries to detect such instances and warn +about them. + +You can generally work around this problem by using @code{protoize} step +by step, each time specifying a different set of @samp{-D} options for +compilation, until all of the functions have been converted. There is +no automatic way to verify that you have got them all, however. + +@item +Confusion may result if there is an occasion to convert a function +declaration or definition in a region of source code where there is more +than one formal parameter list present. Thus, attempts to convert code +containing multiple (conditionally compiled) versions of a single +function header (in the same vicinity) may not produce the desired (or +expected) results. + +If you plan on converting source files which contain such code, it is +recommended that you first make sure that each conditionally compiled +region of source code which contains an alternative function header also +contains at least one additional follower token (past the final right +parenthesis of the function header). This should circumvent the +problem. + +@item +@code{unprotoize} can become confused when trying to convert a function +definition or declaration which contains a declaration for a +pointer-to-function formal argument which has the same name as the +function being defined or declared. We recommand you avoid such choices +of formal parameter names. + +@item +You might also want to correct some of the indentation by hand and break +long lines. (The conversion programs don't write lines longer than +eighty characters in any case.) +@end itemize + +@node Non-bugs +@section Certain Changes We Don't Want to Make + +This section lists changes that people frequently request, but which +we do not make because we think GNU CC is better without them. + +@itemize @bullet +@item +Checking the number and type of arguments to a function which has an +old-fashioned definition and no prototype. + +Such a feature would work only occasionally---only for calls that appear +in the same file as the called function, following the definition. The +only way to check all calls reliably is to add a prototype for the +function. But adding a prototype eliminates the motivation for this +feature. So the feature is not worthwhile. + +@item +Warning about using an expression whose type is signed as a shift count. + +Shift count operands are probably signed more often than unsigned. +Warning about this would cause far more annoyance than good. + +@item +Warning about assigning a signed value to an unsigned variable. + +Such assignments must be very common; warning about them would cause +more annoyance than good. + +@item +Warning about unreachable code. + +It's very common to have unreachable code in machine-generated +programs. For example, this happens normally in some files of GNU C +itself. + +@item +Warning when a non-void function value is ignored. + +Coming as I do from a Lisp background, I balk at the idea that there is +something dangerous about discarding a value. There are functions that +return values which some callers may find useful; it makes no sense to +clutter the program with a cast to @code{void} whenever the value isn't +useful. + +@item +Assuming (for optimization) that the address of an external symbol is +never zero. + +This assumption is false on certain systems when @samp{#pragma weak} is +used. + +@item +Making @samp{-fshort-enums} the default. + +This would cause storage layout to be incompatible with most other C +compilers. And it doesn't seem very important, given that you can get +the same result in other ways. The case where it matters most is when +the enumeration-valued object is inside a structure, and in that case +you can specify a field width explicitly. + +@item +Making bitfields unsigned by default on particular machines where ``the +ABI standard'' says to do so. + +The ANSI C standard leaves it up to the implementation whether a bitfield +declared plain @code{int} is signed or not. This in effect creates two +alternative dialects of C. + +The GNU C compiler supports both dialects; you can specify the signed +dialect with @samp{-fsigned-bitfields} and the unsigned dialect with +@samp{-funsigned-bitfields}. However, this leaves open the question of +which dialect to use by default. + +Currently, the preferred dialect makes plain bitfields signed, because +this is simplest. Since @code{int} is the same as @code{signed int} in +every other context, it is cleanest for them to be the same in bitfields +as well. + +Some computer manufacturers have published Application Binary Interface +standards which specify that plain bitfields should be unsigned. It is +a mistake, however, to say anything about this issue in an ABI. This is +because the handling of plain bitfields distinguishes two dialects of C. +Both dialects are meaningful on every type of machine. Whether a +particular object file was compiled using signed bitfields or unsigned +is of no concern to other object files, even if they access the same +bitfields in the same data structures. + +A given program is written in one or the other of these two dialects. +The program stands a chance to work on most any machine if it is +compiled with the proper dialect. It is unlikely to work at all if +compiled with the wrong dialect. + +Many users appreciate the GNU C compiler because it provides an +environment that is uniform across machines. These users would be +inconvenienced if the compiler treated plain bitfields differently on +certain machines. + +Occasionally users write programs intended only for a particular machine +type. On these occasions, the users would benefit if the GNU C compiler +were to support by default the same dialect as the other compilers on +that machine. But such applications are rare. And users writing a +program to run on more than one type of machine cannot possibly benefit +from this kind of compatibility. + +This is why GNU CC does and will treat plain bitfields in the same +fashion on all types of machines (by default). + +There are some arguments for making bitfields unsigned by default on all +machines. If, for example, this becomes a universal de facto standard, +it would make sense for GNU CC to go along with it. This is something +to be considered in the future. + +(Of course, users strongly concerned about portability should indicate +explicitly in each bitfield whether it is signed or not. In this way, +they write programs which have the same meaning in both C dialects.) + +@item +Undefining @code{__STDC__} when @samp{-ansi} is not used. + +Currently, GNU CC defines @code{__STDC__} as long as you don't use +@samp{-traditional}. This provides good results in practice. + +Programmers normally use conditionals on @code{__STDC__} to ask whether +it is safe to use certain features of ANSI C, such as function +prototypes or ANSI token concatenation. Since plain @samp{gcc} supports +all the features of ANSI C, the correct answer to these questions is +``yes''. + +Some users try to use @code{__STDC__} to check for the availability of +certain library facilities. This is actually incorrect usage in an ANSI +C program, because the ANSI C standard says that a conforming +freestanding implementation should define @code{__STDC__} even though it +does not have the library facilities. @samp{gcc -ansi -pedantic} is a +conforming freestanding implementation, and it is therefore required to +define @code{__STDC__}, even though it does not come with an ANSI C +library. + +Sometimes people say that defining @code{__STDC__} in a compiler that +does not completely conform to the ANSI C standard somehow violates the +standard. This is illogical. The standard is a standard for compilers +that claim to support ANSI C, such as @samp{gcc -ansi}---not for other +compilers such as plain @samp{gcc}. Whatever the ANSI C standard says +is relevant to the design of plain @samp{gcc} without @samp{-ansi} only +for pragmatic reasons, not as a requirement. + +@item +Undefining @code{__STDC__} in C++. + +Programs written to compile with C++-to-C translators get the +value of @code{__STDC__} that goes with the C compiler that is +subsequently used. These programs must test @code{__STDC__} +to determine what kind of C preprocessor that compiler uses: +whether they should concatenate tokens in the ANSI C fashion +or in the traditional fashion. + +These programs work properly with GNU C++ if @code{__STDC__} is defined. +They would not work otherwise. + +In addition, many header files are written to provide prototypes in ANSI +C but not in traditional C. Many of these header files can work without +change in C++ provided @code{__STDC__} is defined. If @code{__STDC__} +is not defined, they will all fail, and will all need to be changed to +test explicitly for C++ as well. + +@item +Deleting ``empty'' loops. + +GNU CC does not delete ``empty'' loops because the most likely reason +you would put one in a program is to have a delay. Deleting them will +not make real programs run any faster, so it would be pointless. + +It would be different if optimization of a nonempty loop could produce +an empty one. But this generally can't happen. + +@item +Making side effects happen in the same order as in some other compiler. + +@cindex side effects, order of evaluation +@cindex order of evaluation, side effects +It is never safe to depend on the order of evaluation of side effects. +For example, a function call like this may very well behave differently +from one compiler to another: + +@example +void func (int, int); + +int i = 2; +func (i++, i++); +@end example + +There is no guarantee (in either the C or the C++ standard language +definitions) that the increments will be evaluated in any particular +order. Either increment might happen first. @code{func} might get the +arguments @samp{3, 4}, or it might get @samp{4, 3}, or even @samp{3, 3}. + +@item +Not allowing structures with volatile fields in registers. + +Strictly speaking, there is no prohibition in the ANSI C standard +against allowing structures with volatile fields in registers, but +it does not seem to make any sense and is probably not what you wanted +to do. So the compiler will give an error message in this case. +@end itemize + +@node Warnings and Errors +@section Warning Messages and Error Messages + +@cindex error messages +@cindex warnings vs errors +@cindex messages, warning and error +The GNU compiler can produce two kinds of diagnostics: errors and +warnings. Each kind has a different purpose: + +@itemize @w{} +@item +@emph{Errors} report problems that make it impossible to compile your +program. GNU CC reports errors with the source file name and line +number where the problem is apparent. + +@item +@emph{Warnings} report other unusual conditions in your code that +@emph{may} indicate a problem, although compilation can (and does) +proceed. Warning messages also report the source file name and line +number, but include the text @samp{warning:} to distinguish them +from error messages. +@end itemize + +Warnings may indicate danger points where you should check to make sure +that your program really does what you intend; or the use of obsolete +features; or the use of nonstandard features of GNU C or C++. Many +warnings are issued only if you ask for them, with one of the @samp{-W} +options (for instance, @samp{-Wall} requests a variety of useful +warnings). + +GNU CC always tries to compile your program if possible; it never +gratuituously rejects a program whose meaning is clear merely because +(for instance) it fails to conform to a standard. In some cases, +however, the C and C++ standards specify that certain extensions are +forbidden, and a diagnostic @emph{must} be issued by a conforming +compiler. The @samp{-pedantic} option tells GNU CC to issue warnings in +such cases; @samp{-pedantic-errors} says to make them errors instead. +This does not mean that @emph{all} non-ANSI constructs get warnings +or errors. + +@xref{Warning Options,,Options to Request or Suppress Warnings}, for +more detail on these and related command-line options. + +@node Bugs +@chapter Reporting Bugs +@cindex bugs +@cindex reporting bugs + +Your bug reports play an essential role in making GNU CC reliable. + +When you encounter a problem, the first thing to do is to see if it is +already known. @xref{Trouble}. If it isn't known, then you should +report the problem. + +Reporting a bug may help you by bringing a solution to your problem, or +it may not. (If it does not, look in the service directory; see +@ref{Service}.) In any case, the principal function of a bug report is +to help the entire community by making the next version of GNU CC work +better. Bug reports are your contribution to the maintenance of GNU CC. + +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. +* Patches: Sending Patches. How to send a patch for GNU CC. +* Known: Trouble. Known problems. +* Help: Service. Where to ask for help. +@end menu + +@node Bug Criteria +@section Have You Found a Bug? +@cindex bug criteria + +If you are not sure whether you have found a bug, here are some guidelines: + +@itemize @bullet +@cindex fatal signal +@cindex core dump +@item +If the compiler gets a fatal signal, for any input whatever, that is a +compiler bug. Reliable compilers never crash. + +@cindex invalid assembly code +@cindex assembly code, invalid +@item +If the compiler produces invalid assembly code, for any input whatever +(except an @code{asm} statement), that is a compiler bug, unless the +compiler reports errors (not just warnings) which would ordinarily +prevent the assembler from being run. + +@cindex undefined behavior +@cindex undefined function value +@cindex increment operators +@item +If the compiler produces valid assembly code that does not correctly +execute the input source code, that is a compiler bug. + +However, you must double-check to make sure, because you may have run +into an incompatibility between GNU C and traditional C +(@pxref{Incompatibilities}). These incompatibilities might be considered +bugs, but they are inescapable consequences of valuable features. + +Or you may have a program whose behavior is undefined, which happened +by chance to give the desired results with another C 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 +results. But the value of the function is undefined if @code{return} +is omitted; it is not a bug when GNU CC produces different results. + +Problems often result from expressions with two increment operators, +as in @code{f (*p++, *p++)}. Your previous compiler might have +interpreted that expression the way you intended; GNU CC might +interpret it another way. Neither compiler is wrong. The bug is +in your code. + +After you have localized the error to a single source line, it should +be easy to check for these things. If your program is correct and +well defined, you have found a compiler bug. + +@item +If the compiler produces an error message for valid input, that is a +compiler bug. + +@cindex invalid input +@item +If the compiler does not produce an error message for invalid input, +that is a compiler bug. However, you should note that your idea of +``invalid input'' might be my idea of ``an extension'' or ``support +for traditional practice''. + +@item +If you are an experienced user of C or C++ compilers, your suggestions +for improvement of GNU CC or GNU C++ are welcome in any case. +@end itemize + +@node Bug Lists +@section Where to Report Bugs +@cindex bug report mailing lists +@kindex bug-gcc@@prep.ai.mit.edu +Send bug reports for GNU C to @samp{bug-gcc@@prep.ai.mit.edu}. + +@kindex bug-g++@@prep.ai.mit.edu +@kindex bug-libg++@@prep.ai.mit.edu +Send bug reports for GNU C++ to @samp{bug-g++@@prep.ai.mit.edu}. +If your bug involves the C++ class library libg++, send mail to +@samp{bug-lib-g++@@prep.ai.mit.edu}. If you're not sure, you can send +the bug report to both lists. + +@strong{Do not send bug reports to @samp{help-gcc@@prep.ai.mit.edu} or +to the newsgroup @samp{gnu.gcc.help}.} Most users of GNU CC do not want +to receive bug reports. Those that do, have asked to be on +@samp{bug-gcc} and/or @samp{bug-g++}. + +The mailing lists @samp{bug-gcc} and @samp{bug-g++} both have newsgroups +which serve as repeaters: @samp{gnu.gcc.bug} and @samp{gnu.g++.bug}. +Each mailing list and its newsgroup carry exactly the same messages. + +Often people think of posting bug reports to the newsgroup instead of +mailing them. This appears to work, but it has one problem which can be +crucial: a newsgroup posting does not contain a mail path back to the +sender. Thus, if maintainers need more information, they may be unable +to reach you. For this reason, you should always send bug reports by +mail to the proper mailing list. + +As a last resort, send bug reports on paper to: + +@example +GNU Compiler Bugs +Free Software Foundation +675 Mass Ave +Cambridge, MA 02139 +@end example + +@node Bug Reporting +@section How 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 GNU CC. You can get this by running it with the +@samp{-v} option. + +Without this, we won't know whether there is any point in looking for +the bug in the current version of GNU CC. + +@item +A complete input file that will reproduce the bug. If the bug is in the +C preprocessor, send a source file and any header files that it +requires. If the bug is in the compiler proper (@file{cc1}), run your +source file through the C preprocessor by doing @samp{gcc -E +@var{sourcefile} > @var{outfile}}, then include the contents of +@var{outfile} in the bug report. (When you do this, use the same +@samp{-I}, @samp{-D} or @samp{-U} options that you used in actual +compilation.) + +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 GNU CC 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 GNU CC 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 GNU CC or GNU C++ to compile that example +and observe the bug. For example, did you use @samp{-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 +GNU CC. + +@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 GNU CC 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 GNU CC or GNU C++, +please use @samp{-g} when you make them. The debugging information +includes source line numbers which are essential for correlating the +output with the input. + +@item +If you wish to mention something in the GNU CC 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 GNU CC because the compiler is largely data-driven; the same +functions are called over and over for different RTL insns, doing +different things depending on the details of the insn. + +Most of the arguments listed in the backtrace are useless because they +are pointers to RTL list structure. The numeric values of the +pointers, which the debugger prints in the backtrace, have no +significance whatever; all that matters is the contents of the objects +they point to (and most of the contents are other such pointers). + +In addition, most compiler passes consist of one or more loops that +scan the RTL insn sequence. The most vital piece of information about +such a loop---which insn it has reached---is usually in a local variable, +not in an argument. + +@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 GNU CC bugs involve just one function, so the most straightforward +way to simplify an example is to delete all the function definitions +except the one where the bug occurs. Those earlier in the file may be +replaced by external declarations if the crucial function depends on +them. (Exception: inline functions may affect compilation of functions +defined later in the file.) + +However, simplification is not vital; if you don't want to do this, +report the bug anyway and send 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 GNU CC it is very hard to +construct an example that will make the program follow a certain path +through the code. If you don't send 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. + +@xref{Sending Patches}, 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 Sending Patches,, Bug Reporting, Bugs +@section Sending Patches for GNU CC + +If you would like to write bug fixes or improvements for the GNU C +compiler, that is very helpful. When you send your changes, please +follow these guidelines to avoid causing extra work for us in studying +the patches. + +If you don't follow these guidelines, your information might still be +useful, but using it will take extra work. Maintaining GNU C is a lot +of work in the best of circumstances, and we can't keep up unless you do +your best to help. + +@itemize @bullet +@item +Send an explanation with your changes of what problem they fix or what +improvement they bring about. For a bug fix, just include a copy of the +bug report, and explain why the change fixes the bug. + +(Referring to a bug report is not as good as including it, because then +we will have to look it up, and we have probably already deleted it if +we've already fixed the bug.) + +@item +Always include a proper bug report for the problem you think you have +fixed. We need to convince ourselves that the change is right before +installing it. Even if it is right, we might have trouble judging it if +we don't have a way to reproduce the problem. + +@item +Include all the comments that are appropriate to help people reading the +source in the future understand why this change was needed. + +@item +Don't mix together changes made for different reasons. +Send them @emph{individually}. + +If you make two changes for separate reasons, then we might not want to +install them both. We might want to install just one. If you send them +all jumbled together in a single set of diffs, we have to do extra work +to disentangle them---to figure out which parts of the change serve +which purpose. If we don't have time for this, we might have to ignore +your changes entirely. + +If you send each change as soon as you have written it, with its own +explanation, then the two changes never get tangled up, and we can +consider each one properly without any extra work to disentangle them. + +Ideally, each change you send should be impossible to subdivide into +parts that we might want to consider separately, because each of its +parts gets its motivation from the other parts. + +@item +Send each change as soon as that change is finished. Sometimes people +think they are helping us by accumulating many changes to send them all +together. As explained above, this is absolutely the worst thing you +could do. + +Since you should send each change separately, you might as well send it +right away. That gives us the option of installing it immediately if it +is important. + +@item +Use @samp{diff -c} to make your diffs. Diffs without context are hard +for us to install reliably. More than that, they make it hard for us to +study the diffs to decide whether we want to install them. Unidiff +format is better than contextless diffs, but not as easy to read as +@samp{-c} format. + +If you have GNU diff, use @samp{diff -cp}, which shows the name of the +function that each change occurs in. + +@item +Write the change log entries for your changes. We get lots of changes, +and we don't have time to do all the change log writing ourselves. + +Read the @file{ChangeLog} file to see what sorts of information to put +in, and to learn the style that we use. The purpose of the change log +is to show people where to find what was changed. So you need to be +specific about what functions you changed; in large functions, it's +often helpful to indicate where within the function the change was. + +On the other hand, once you have shown people where to find the change, +you need not explain its purpose. Thus, if you add a new function, all +you need to say about it is that it is new. If you feel that the +purpose needs explaining, it probably does---but the explanation will be +much more useful if you put it in comments in the code. + +If you would like your name to appear in the header line for who made +the change, send us the header line. + +@item +When you write the fix, keep in mind that we can't install a change that +would break other systems. + +People often suggest fixing a problem by changing machine-independent +files such as @file{toplev.c} to do something special that a particular +system needs. Sometimes it is totally obvious that such changes would +break GNU CC for almost all users. We can't possibly make a change like +that. At best it might tell us how to write another patch that would +solve the problem acceptably. + +Sometimes people send fixes that @emph{might} be an improvement in +general---but it is hard to be sure of this. It's hard to install +such changes because we have to study them very carefully. Of course, +a good explanation of the reasoning by which you concluded the change +was correct can help convince us. + +The safest changes are changes to the configuration files for a +particular machine. These are safe because they can't create new bugs +on other machines. + +Please help us keep up with the workload by designing the patch in a +form that is good to install. +@end itemize + +@node Service +@chapter How To Get Help with GNU CC + +If you need help installing, using or changing GNU CC, there are two +ways to find it: + +@itemize @bullet +@item +Send a message to a suitable network mailing list. First try +@code{bug-gcc@@prep.ai.mit.edu}, and if that brings no response, try +@code{help-gcc@@prep.ai.mit.edu}. + +@item +Look in the service directory for someone who might help you for a fee. +The service directory is found in the file named @file{SERVICE} in the +GNU CC distribution. +@end itemize + +@node VMS +@chapter Using GNU CC on VMS + +@c prevent bad page break with this line +Here is how to use GNU CC on VMS. + +@menu +* Include Files and VMS:: Where the preprocessor looks for the include files. +* Global Declarations:: How to do globaldef, globalref and globalvalue with + GNU CC. +* VMS Misc:: Misc information. +@end menu + +@node Include Files and VMS +@section Include Files and VMS + +@cindex include files and VMS +@cindex VMS and include files +@cindex header files and VMS +Due to the differences between the filesystems of Unix and VMS, GNU CC +attempts to translate file names in @samp{#include} into names that VMS +will understand. The basic strategy is to prepend a prefix to the +specification of the include file, convert the whole filename to a VMS +filename, and then try to open the file. GNU CC tries various prefixes +one by one until one of them succeeds: + +@enumerate +@item +The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is +where GNU C header files are traditionally stored. If you wish to store +header files in non-standard locations, then you can assign the logical +@samp{GNU_CC_INCLUDE} to be a search list, where each element of the +list is suitable for use with a rooted logical. + +@item +The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where +VAX-C header files are traditionally stored. + +@item +If the include file specification by itself is a valid VMS filename, the +preprocessor then uses this name with no prefix in an attempt to open +the include file. + +@item +If the file specification is not a valid VMS filename (i.e. does not +contain a device or a directory specifier, and contains a @samp{/} +character), the preprocessor tries to convert it from Unix syntax to +VMS syntax. + +Conversion works like this: the first directory name becomes a device, +and the rest of the directories are converted into VMS-format directory +names. For example, the name @file{X11/foobar.h} is +translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h}, +whichever one can be opened. This strategy allows you to assign a +logical name to point to the actual location of the header files. + +@item +If none of these strategies succeeds, the @samp{#include} fails. +@end enumerate + +Include directives of the form: + +@example +#include foobar +@end example + +@noindent +are a common source of incompatibility between VAX-C and GNU CC. VAX-C +treats this much like a standard @code{#include <foobar.h>} directive. +That is incompatible with the ANSI C behavior implemented by GNU CC: to +expand the name @code{foobar} as a macro. Macro expansion should +eventually yield one of the two standard formats for @code{#include}: + +@example +#include "@var{file}" +#include <@var{file}> +@end example + +If you have this problem, the best solution is to modify the source to +convert the @code{#include} directives to one of the two standard forms. +That will work with either compiler. If you want a quick and dirty fix, +define the file names as macros with the proper expansion, like this: + +@example +#define stdio <stdio.h> +@end example + +@noindent +This will work, as long as the name doesn't conflict with anything else +in the program. + +Another source of incompatibility is that VAX-C assumes that: + +@example +#include "foobar" +@end example + +@noindent +is actually asking for the file @file{foobar.h}. GNU CC does not +make this assumption, and instead takes what you ask for literally; +it tries to read the file @file{foobar}. The best way to avoid this +problem is to always specify the desired file extension in your include +directives. + +GNU CC for VMS is distributed with a set of include files that is +sufficient to compile most general purpose programs. Even though the +GNU CC distribution does not contain header files to define constants +and structures for some VMS system-specific functions, there is no +reason why you cannot use GNU CC with any of these functions. You first +may have to generate or create header files, either by using the public +domain utility @code{UNSDL} (which can be found on a DECUS tape), or by +extracting the relevant modules from one of the system macro libraries, +and using an editor to construct a C header file. + +A @code{#include} file name cannot contain a DECNET node name. The +preprocessor reports an I/O error if you attempt to use a node name, +whether explicitly, or implicitly via a logical name. + +@node Global Declarations +@section Global Declarations and VMS + +@findex GLOBALREF +@findex GLOBALDEF +@findex GLOBALVALUEDEF +@findex GLOBALVALUEREF +GNU CC does not provide the @code{globalref}, @code{globaldef} and +@code{globalvalue} keywords of VAX-C. You can get the same effect with +an obscure feature of GAS, the GNU assembler. (This requires GAS +version 1.39 or later.) The following macros allow you to use this +feature in a fairly natural way: + +@smallexample +#ifdef __GNUC__ +#define GLOBALREF(TYPE,NAME) \ + TYPE NAME \ + asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) +#define GLOBALDEF(TYPE,NAME,VALUE) \ + TYPE NAME \ + asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \ + = VALUE +#define GLOBALVALUEREF(TYPE,NAME) \ + const TYPE NAME[1] \ + asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) +#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ + const TYPE NAME[1] \ + asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \ + = @{VALUE@} +#else +#define GLOBALREF(TYPE,NAME) \ + globalref TYPE NAME +#define GLOBALDEF(TYPE,NAME,VALUE) \ + globaldef TYPE NAME = VALUE +#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ + globalvalue TYPE NAME = VALUE +#define GLOBALVALUEREF(TYPE,NAME) \ + globalvalue TYPE NAME +#endif +@end smallexample + +@noindent +(The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the +name is removed by the assembler, after it has modified the attributes +of the symbol). These macros are provided in the VMS binaries +distribution in a header file @file{GNU_HACKS.H}. An example of the +usage is: + +@example +GLOBALREF (int, ijk); +GLOBALDEF (int, jkl, 0); +@end example + +The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used +straightforwardly for arrays, since there is no way to insert the array +dimension into the declaration at the right place. However, you can +declare an array with these macros if you first define a typedef for the +array type, like this: + +@example +typedef int intvector[10]; +GLOBALREF (intvector, foo); +@end example + +Array and structure initializers will also break the macros; you can +define the initializer to be a macro of its own, or you can expand the +@code{GLOBALDEF} macro by hand. You may find a case where you wish to +use the @code{GLOBALDEF} macro with a large array, but you are not +interested in explicitly initializing each element of the array. In +such cases you can use an initializer like: @code{@{0,@}}, which will +initialize the entire array to @code{0}. + +A shortcoming of this implementation is that a variable declared with +@code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For +example, the declaration: + +@example +GLOBALVALUEREF(int, ijk); +@end example + +@noindent +declares the variable @code{ijk} as an array of type @code{int [1]}. +This is done because a globalvalue is actually a constant; its ``value'' +is what the linker would normally consider an address. That is not how +an integer value works in C, but it is how an array works. So treating +the symbol as an array name gives consistent results---with the +exception that the value seems to have the wrong type. @strong{Don't +try to access an element of the array.} It doesn't have any elements. +The array ``address'' may not be the address of actual storage. + +The fact that the symbol is an array may lead to warnings where the +variable is used. Insert type casts to avoid the warnings. Here is an +example; it takes advantage of the ANSI C feature allowing macros that +expand to use the same name as the macro itself. + +@example +GLOBALVALUEREF (int, ss$_normal); +GLOBALVALUEDEF (int, xyzzy,123); +#ifdef __GNUC__ +#define ss$_normal ((int) ss$_normal) +#define xyzzy ((int) xyzzy) +#endif +@end example + +Don't use @code{globaldef} or @code{globalref} with a variable whose +type is an enumeration type; this is not implemented. Instead, make the +variable an integer, and use a @code{globalvaluedef} for each of the +enumeration values. An example of this would be: + +@example +#ifdef __GNUC__ +GLOBALDEF (int, color, 0); +GLOBALVALUEDEF (int, RED, 0); +GLOBALVALUEDEF (int, BLUE, 1); +GLOBALVALUEDEF (int, GREEN, 3); +#else +enum globaldef color @{RED, BLUE, GREEN = 3@}; +#endif +@end example + +@node VMS Misc +@section Other VMS Issues + +@cindex exit status and VMS +@cindex return value of @code{main} +@cindex @code{main} and the exit status +GNU CC automatically arranges for @code{main} to return 1 by default if +you fail to specify an explicit return value. This will be interpreted +by VMS as a status code indicating a normal successful completion. +Version 1 of GNU CC did not provide this default. + +GNU CC on VMS works only with the GNU assembler, GAS. You need version +1.37 or later of GAS in order to produce value debugging information for +the VMS debugger. Use the ordinary VMS linker with the object files +produced by GAS. + +@cindex shared VMS run time system +@cindex @file{VAXCRTL} +Under previous versions of GNU CC, the generated code would occasionally +give strange results when linked to the sharable @file{VAXCRTL} library. +Now this should work. + +A caveat for use of @code{const} global variables: the @code{const} +modifier must be specified in every external declaration of the variable +in all of the source files that use that variable. Otherwise the linker +will issue warnings about conflicting attributes for the variable. Your +program will still work despite the warnings, but the variable will be +placed in writable storage. + +@cindex name augmentation +@cindex case sensitivity and VMS +@cindex VMS and case sensitivity +Although the VMS linker does distinguish between upper and lower case +letters in global symbols, most VMS compilers convert all such symbols +into upper case and most run-time library routines also have upper case +names. To be able to reliably call such routines, GNU CC (by means of +the assembler GAS) converts global symbols into upper case like other +VMS compilers. However, since the usual practice in C is to distinguish +case, GNU CC (via GAS) tries to preserve usual C behavior by augmenting +each name that is not all lower case. This means truncating the name +to at most 23 characters and then adding more characters at the end +which encode the case pattern of those 23. Names which contain at +least one dollar sign are an exception; they are converted directly into +upper case without augmentation. + +Name augmentation yields bad results for programs that use precompiled +libraries (such as Xlib) which were generated by another compiler. You +can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation; +it makes external C functions and variables case-independent as is usual +on VMS. Alternatively, you could write all references to the functions +and variables in such libraries using lower case; this will work on VMS, +but is not portable to other systems. The compiler option @samp{/NAMES} +also provides control over global name handling. + +Function and variable names are handled somewhat differently with GNU +C++. The GNU C++ compiler performs @dfn{name mangling} on function +names, which means that it adds information to the function name to +describe the data types of the arguments that the function takes. One +result of this is that the name of a function can become very long. +Since the VMS linker only recognizes the first 31 characters in a name, +special action is taken to ensure that each function and variable has a +unique name that can be represented in 31 characters. + +If the name (plus a name augmentation, if required) is less than 32 +characters in length, then no special action is performed. If the name +is longer than 31 characters, the assembler (GAS) will generate a +hash string based upon the function name, truncate the function name to +23 characters, and append the hash string to the truncated name. If the +@samp{/VERBOSE} compiler option is used, the assembler will print both +the full and truncated names of each symbol that is truncated. + +The @samp{/NOCASE_HACK} compiler option should not be used when you are +compiling programs that use libg++. libg++ has several instances of +objects (i.e. @code{Filebuf} and @code{filebuf}) which become +indistinguishable in a case-insensitive environment. This leads to +cases where you need to inhibit augmentation selectively (if you were +using libg++ and Xlib in the same program, for example). There is no +special feature for doing this, but you can get the result by defining a +macro for each mixed case symbol for which you wish to inhibit +augmentation. The macro should expand into the lower case equivalent of +itself. For example: + +@example +#define StuDlyCapS studlycaps +@end example + +These macro definitions can be placed in a header file to minimize the +number of changes to your source code. +@end ifset + +@ifset INTERNALS +@node Portability +@chapter GNU CC and Portability +@cindex portability +@cindex GNU CC and portability + +The main goal of GNU CC was to make a good, fast compiler for machines in +the class that the GNU system aims to run on: 32-bit machines that address +8-bit bytes and have several general registers. Elegance, theoretical +power and simplicity are only secondary. + +GNU CC gets most of the information about the target machine from a machine +description which gives an algebraic formula for each of the machine's +instructions. This is a very clean way to describe the target. But when +the compiler needs information that is difficult to express in this +fashion, I have not hesitated to define an ad-hoc parameter to the machine +description. The purpose of portability is to reduce the total work needed +on the compiler; it was not of interest for its own sake. + +@cindex endianness +@cindex autoincrement addressing, availability +@findex abort +GNU CC does not contain machine dependent code, but it does contain code +that depends on machine parameters such as endianness (whether the most +significant byte has the highest or lowest address of the bytes in a word) +and the availability of autoincrement addressing. In the RTL-generation +pass, it is often necessary to have multiple strategies for generating code +for a particular kind of syntax tree, strategies that are usable for different +combinations of parameters. Often I have not tried to address all possible +cases, but only the common ones or only the ones that I have encountered. +As a result, a new target may require additional strategies. You will know +if this happens because the compiler will call @code{abort}. Fortunately, +the new strategies can be added in a machine-independent fashion, and will +affect only the target machines that need them. +@end ifset + +@ifset INTERNALS +@node Interface +@chapter Interfacing to GNU CC Output +@cindex interfacing to GNU CC output +@cindex run-time conventions +@cindex function call conventions +@cindex conventions, run-time + +GNU CC is normally configured to use the same function calling convention +normally in use on the target system. This is done with the +machine-description macros described (@pxref{Target Macros}). + +@cindex unions, returning +@cindex structures, returning +@cindex returning structures and unions +However, returning of structure and union values is done differently on +some target machines. As a result, functions compiled with PCC +returning such types cannot be called from code compiled with GNU CC, +and vice versa. This does not cause trouble often because few Unix +library routines return structures or unions. + +GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes +long in the same registers used for @code{int} or @code{double} return +values. (GNU CC typically allocates variables of such types in +registers also.) Structures and unions of other sizes are returned by +storing them into an address passed by the caller (usually in a +register). The machine-description macros @code{STRUCT_VALUE} and +@code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address. + +By contrast, PCC on most target machines returns structures and unions +of any size by copying the data into an area of static storage, and then +returning the address of that storage as if it were a pointer value. +The caller must copy the data from that memory area to the place where +the value is wanted. This is slower than the method used by GNU CC, and +fails to be reentrant. + +On some target machines, such as RISC machines and the 80386, the +standard system convention is to pass to the subroutine the address of +where to return the value. On these machines, GNU CC has been +configured to be compatible with the standard compiler, when this method +is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes. + +@cindex argument passing +@cindex passing arguments +GNU CC uses the system's standard convention for passing arguments. On +some machines, the first few arguments are passed in registers; in +others, all are passed on the stack. It would be possible to use +registers for argument passing on any machine, and this would probably +result in a significant speedup. But the result would be complete +incompatibility with code that follows the standard convention. So this +change is practical only if you are switching to GNU CC as the sole C +compiler for the system. We may implement register argument passing on +certain machines once we have a complete GNU system so that we can +compile the libraries with GNU CC. + +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. + +@cindex @code{longjmp} and automatic variables +If you use @code{longjmp}, beware of automatic variables. ANSI C says that +automatic variables that are not declared @code{volatile} have undefined +values after a @code{longjmp}. And this is all GNU CC promises to do, +because it is very difficult to restore register variables correctly, and +one of GNU CC's features is that it can put variables in registers without +your asking it to. + +If you want a variable to be unaltered by @code{longjmp}, and you don't +want to write @code{volatile} because old C compilers don't accept it, +just take the address of the variable. If a variable's address is ever +taken, even if just to compute it and ignore it, then the variable cannot +go in a register: + +@example +@{ + int careful; + &careful; + @dots{} +@} +@end example + +@cindex arithmetic libraries +@cindex math libraries +Code compiled with GNU CC may call certain library routines. Most of +them handle arithmetic for which there are no instructions. This +includes multiply and divide on some machines, and floating point +operations on any machine for which floating point support is disabled +with @samp{-msoft-float}. Some standard parts of the C library, such as +@code{bcopy} or @code{memcpy}, are also called automatically. The usual +function call interface is used for calling the library routines. + +These library routines should be defined in the library @file{libgcc.a}, +which GNU CC automatically searches whenever it links a program. On +machines that have multiply and divide instructions, if hardware +floating point is in use, normally @file{libgcc.a} is not needed, but it +is searched just in case. + +Each arithmetic function is defined in @file{libgcc1.c} to use the +corresponding C arithmetic operator. As long as the file is compiled +with another C compiler, which supports all the C arithmetic operators, +this file will work portably. However, @file{libgcc1.c} does not work if +compiled with GNU CC, because each arithmetic function would compile +into a call to itself! +@end ifset + +@ifset INTERNALS +@node Passes +@chapter Passes and Files of the Compiler +@cindex passes and files of the compiler +@cindex files and passes of the compiler +@cindex compiler passes and files + +@cindex top level of compiler +The overall control structure of the compiler is in @file{toplev.c}. This +file is responsible for initialization, decoding arguments, opening and +closing files, and sequencing the passes. + +@cindex parsing pass +The parsing pass is invoked only once, to parse the entire input. The RTL +intermediate code for a function is generated as the function is parsed, a +statement at a time. Each statement is read in as a syntax tree and then +converted to RTL; then the storage for the tree for the statement is +reclaimed. Storage for types (and the expressions for their sizes), +declarations, and a representation of the binding contours and how they nest, +remain until the function is finished being compiled; these are all needed +to output the debugging information. + +@findex rest_of_compilation +@findex rest_of_decl_compilation +Each time the parsing pass reads a complete function definition or +top-level declaration, it calls either the function +@code{rest_of_compilation}, or the function +@code{rest_of_decl_compilation} in @file{toplev.c}, which are +responsible for all further processing necessary, ending with output of +the assembler language. All other compiler passes run, in sequence, +within @code{rest_of_compilation}. When that function returns from +compiling a function definition, the storage used for that function +definition's compilation is entirely freed, unless it is an inline +function +@ifset USING +(@pxref{Inline,,An Inline Function is As Fast As a Macro}). +@end ifset +@ifclear USING +(@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}). +@end ifclear + +Here is a list of all the passes of the compiler and their source files. +Also included is a description of where debugging dumps can be requested +with @samp{-d} options. + +@itemize @bullet +@item +Parsing. This pass reads the entire text of a function definition, +constructing partial syntax trees. This and RTL generation are no longer +truly separate passes (formerly they were), but it is easier to think +of them as separate. + +The tree representation does not entirely follow C syntax, because it is +intended to support other languages as well. + +Language-specific data type analysis is also done in this pass, and every +tree node that represents an expression has a data type attached. +Variables are represented as declaration nodes. + +@cindex constant folding +@cindex arithmetic simplifications +@cindex simplifications, arithmetic +Constant folding and some arithmetic simplifications are also done +during this pass. + +The language-independent source files for parsing are +@file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}. +There are also header files @file{tree.h} and @file{tree.def} +which define the format of the tree representation.@refill + +@c Avoiding overfull is tricky here. +The source files to parse C are +@file{c-parse.in}, +@file{c-decl.c}, +@file{c-typeck.c}, +@file{c-aux-info.c}, +@file{c-convert.c}, +and @file{c-lang.c} +along with header files +@file{c-lex.h}, and +@file{c-tree.h}. + +The source files for parsing C++ are @file{cp-parse.y}, +@file{cp-class.c},@* +@file{cp-cvt.c}, @file{cp-decl.c}, @file{cp-decl2.c}, +@file{cp-dem.c}, @file{cp-except.c},@* +@file{cp-expr.c}, @file{cp-init.c}, @file{cp-lex.c}, +@file{cp-method.c}, @file{cp-ptree.c},@* +@file{cp-search.c}, @file{cp-tree.c}, @file{cp-type2.c}, and +@file{cp-typeck.c}, along with header files @file{cp-tree.def}, +@file{cp-tree.h}, and @file{cp-decl.h}. + +The special source files for parsing Objective C are +@file{objc-parse.y}, @file{objc-actions.c}, @file{objc-tree.def}, and +@file{objc-actions.h}. Certain C-specific files are used for this as +well. + +The file @file{c-common.c} is also used for all of the above languages. + +@cindex RTL generation +@item +RTL generation. This is the conversion of syntax tree into RTL code. +It is actually done statement-by-statement during parsing, but for +most purposes it can be thought of as a separate pass. + +@cindex target-parameter-dependent code +This is where the bulk of target-parameter-dependent code is found, +since often it is necessary for strategies to apply only when certain +standard kinds of instructions are available. The purpose of named +instruction patterns is to provide this information to the RTL +generation pass. + +@cindex tail recursion optimization +Optimization is done in this pass for @code{if}-conditions that are +comparisons, boolean operations or conditional expressions. Tail +recursion is detected at this time also. Decisions are made about how +best to arrange loops and how to output @code{switch} statements. + +@c Avoiding overfull is tricky here. +The source files for RTL generation include +@file{stmt.c}, +@file{calls.c}, +@file{expr.c}, +@file{explow.c}, +@file{expmed.c}, +@file{function.c}, +@file{optabs.c} +and @file{emit-rtl.c}. +Also, the file +@file{insn-emit.c}, generated from the machine description by the +program @code{genemit}, is used in this pass. The header file +@file{expr.h} is used for communication within this pass.@refill + +@findex genflags +@findex gencodes +The header files @file{insn-flags.h} and @file{insn-codes.h}, +generated from the machine description by the programs @code{genflags} +and @code{gencodes}, tell this pass which standard names are available +for use and which patterns correspond to them.@refill + +Aside from debugging information output, none of the following passes +refers to the tree structure representation of the function (only +part of which is saved). + +@cindex inline, automatic +The decision of whether the function can and should be expanded inline +in its subsequent callers is made at the end of rtl generation. The +function must meet certain criteria, currently related to the size of +the function and the types and number of parameters it has. Note that +this function may contain loops, recursive calls to itself +(tail-recursive functions can be inlined!), gotos, in short, all +constructs supported by GNU CC. The file @file{integrate.c} contains +the code to save a function's rtl for later inlining and to inline that +rtl when the function is called. The header file @file{integrate.h} +is also used for this purpose. + +The option @samp{-dr} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.rtl} to +the input file name. + +@cindex jump optimization +@cindex unreachable code +@cindex dead code +@item +Jump optimization. This pass simplifies jumps to the following +instruction, jumps across jumps, and jumps to jumps. It deletes +unreferenced labels and unreachable code, except that unreachable code +that contains a loop is not recognized as unreachable in this pass. +(Such loops are deleted later in the basic block analysis.) It also +converts some code originally written with jumps into sequences of +instructions that directly set values from the results of comparisons, +if the machine has such instructions. + +Jump optimization is performed two or three times. The first time is +immediately following RTL generation. The second time is after CSE, +but only if CSE says repeated jump optimization is needed. The +last time is right before the final pass. That time, cross-jumping +and deletion of no-op move instructions are done together with the +optimizations described above. + +The source file of this pass is @file{jump.c}. + +The option @samp{-dj} causes a debugging dump of the RTL code after +this pass is run for the first time. This dump file's name is made by +appending @samp{.jump} to the input file name. + +@cindex register use analysis +@item +Register scan. This pass finds the first and last use of each +register, as a guide for common subexpression elimination. Its source +is in @file{regclass.c}. + +@cindex jump threading +@item +Jump threading. This pass detects a condition jump that branches to an +identical or inverse test. Such jumps can be @samp{threaded} through +the second conditional test. The source code for this pass is in +@file{jump.c}. This optimization is only performed if +@samp{-fthread-jumps} is enabled. + +@cindex common subexpression elimination +@cindex constant propagation +@item +Common subexpression elimination. This pass also does constant +propagation. Its source file is @file{cse.c}. If constant +propagation causes conditional jumps to become unconditional or to +become no-ops, jump optimization is run again when CSE is finished. + +The option @samp{-ds} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.cse} to +the input file name. + +@cindex loop optimization +@cindex code motion +@cindex strength-reduction +@item +Loop optimization. This pass moves constant expressions out of loops, +and optionally does strength-reduction and loop unrolling as well. +Its source files are @file{loop.c} and @file{unroll.c}, plus the header +@file{loop.h} used for communication between them. Loop unrolling uses +some functions in @file{integrate.c} and the header @file{integrate.h}. + +The option @samp{-dL} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.loop} to +the input file name. + +@item +If @samp{-frerun-cse-after-loop} was enabled, a second common +subexpression elimination pass is performed after the loop optimization +pass. Jump threading is also done again at this time if it was specified. + +The option @samp{-dt} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.cse2} to +the input file name. + +@cindex register allocation, stupid +@cindex stupid register allocation +@item +Stupid register allocation is performed at this point in a +nonoptimizing compilation. It does a little data flow analysis as +well. When stupid register allocation is in use, the next pass +executed is the reloading pass; the others in between are skipped. +The source file is @file{stupid.c}. + +@cindex data flow analysis +@cindex analysis, data flow +@cindex basic blocks +@item +Data flow analysis (@file{flow.c}). This pass divides the program +into basic blocks (and in the process deletes unreachable loops); then +it computes which pseudo-registers are live at each point in the +program, and makes the first instruction that uses a value point at +the instruction that computed the value. + +@cindex autoincrement/decrement analysis +This pass also deletes computations whose results are never used, and +combines memory references with add or subtract instructions to make +autoincrement or autodecrement addressing. + +The option @samp{-df} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.flow} to +the input file name. If stupid register allocation is in use, this +dump file reflects the full results of such allocation. + +@cindex instruction combination +@item +Instruction combination (@file{combine.c}). This pass attempts to +combine groups of two or three instructions that are related by data +flow into single instructions. It combines the RTL expressions for +the instructions by substitution, simplifies the result using algebra, +and then attempts to match the result against the machine description. + +The option @samp{-dc} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.combine} +to the input file name. + +@cindex instruction scheduling +@cindex scheduling, instruction +@item +Instruction scheduling (@file{sched.c}). This pass looks for +instructions whose output will not be available by the time that it is +used in subsequent instructions. (Memory loads and floating point +instructions often have this behavior on RISC machines). It re-orders +instructions within a basic block to try to separate the definition and +use of items that otherwise would cause pipeline stalls. + +Instruction scheduling is performed twice. The first time is immediately +after instruction combination and the second is immediately after reload. + +The option @samp{-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 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 +hard registers to pseudo registers that are used only within one basic +block. Because the basic block is linear, it can use fast and +powerful techniques to do a very good job. + +The option @samp{-dl} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.lreg} to +the input file name. + +@cindex global register allocation +@item +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 reloading +@item +Reloading. This pass renumbers pseudo registers with the hardware +registers numbers they were allocated. Pseudo registers that did not +get hard registers are replaced with stack slots. Then it finds +instructions that are invalid because a value has failed to end up in +a register, or has ended up in a register of the wrong kind. It fixes +up these instructions by reloading the problematical values +temporarily into registers. Additional instructions are generated to +do the copying. + +The reload pass also optionally eliminates the frame pointer and inserts +instructions to save and restore call-clobbered registers around calls. + +Source files are @file{reload.c} and @file{reload1.c}, plus the header +@file{reload.h} used for communication between them. + +The option @samp{-dg} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.greg} to +the input file name. + +@cindex instruction scheduling +@cindex scheduling, instruction +@item +Instruction scheduling is repeated here to try to avoid pipeline stalls +due to memory loads generated for spilled pseudo registers. + +The option @samp{-dR} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.sched2} +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. + +The option @samp{-dJ} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.jump2} +to the input file name. + +@cindex delayed branch scheduling +@cindex scheduling, delayed branch +@item +Delayed branch scheduling. This optional pass attempts to find +instructions that can go into the delay slots of other instructions, +usually jumps and calls. The source file name is @file{reorg.c}. + +The option @samp{-dd} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.dbr} +to the input file name. + +@cindex register-to-stack conversion +@item +Conversion from usage of some hard registers to usage of a register +stack may be done at this point. Currently, this is supported only +for the floating-point registers of the Intel 80387 coprocessor. The +source file name is @file{reg-stack.c}. + +The options @samp{-dk} causes a debugging dump of the RTL code after +this pass. This dump file's name is made by appending @samp{.stack} +to the input file name. + +@cindex final pass +@cindex peephole optimization +@item +Final. This pass outputs the assembler code for the function. It is +also responsible for identifying spurious test and compare +instructions. Machine-specific peephole optimizations are performed +at the same time. The function entry and exit sequences are generated +directly as assembler code in this pass; they never exist as RTL. + +The source files are @file{final.c} plus @file{insn-output.c}; the +latter is generated automatically from the machine description by the +tool @file{genoutput}. The header file @file{conditions.h} is used +for communication between these files. + +@cindex debugging information generation +@item +Debugging information output. This is run after final because it must +output the stack slot offsets for pseudo registers that did not get +hard registers. Source files are @file{dbxout.c} for DBX symbol table +format, @file{sdbout.c} for SDB symbol table format, and +@file{dwarfout.c} for DWARF symbol table format. +@end itemize + +Some additional files are used by all or many passes: + +@itemize @bullet +@item +Every pass uses @file{machmode.def} and @file{machmode.h} which define +the machine modes. + +@item +Several passes use @file{real.h}, which defines the default +representation of floating point constants and how to operate on them. + +@item +All the passes that work with RTL use the header files @file{rtl.h} +and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools +@code{gen*} also use these files to read and work with the machine +description RTL. + +@findex genconfig +@item +Several passes refer to the header file @file{insn-config.h} which +contains a few parameters (C macro definitions) generated +automatically from the machine description RTL by the tool +@code{genconfig}. + +@cindex instruction recognizer +@item +Several passes use the instruction recognizer, which consists of +@file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c} +and @file{insn-extract.c} that are generated automatically from the +machine description by the tools @file{genrecog} and +@file{genextract}.@refill + +@item +Several passes use the header files @file{regs.h} which defines the +information recorded about pseudo register usage, and @file{basic-block.h} +which defines the information recorded about basic blocks. + +@item +@file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector +with a bit for each hard register, and some macros to manipulate it. +This type is just @code{int} if the machine has few enough hard registers; +otherwise it is an array of @code{int} and some of the macros expand +into loops. + +@item +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}.@refill +@end itemize +@end ifset + +@ifset INTERNALS +@include rtl.texi +@include md.texi +@include tm.texi +@end ifset + +@ifset INTERNALS +@node Config +@chapter The Configuration File +@cindex configuration file +@cindex @file{xm-@var{machine}.h} + +The configuration file @file{xm-@var{machine}.h} contains macro +definitions that describe the machine and system on which the compiler +is running, unlike the definitions in @file{@var{machine}.h}, which +describe the machine for which the compiler is producing output. Most +of the values in @file{xm-@var{machine}.h} are actually the same on all +machines that GNU CC runs on, so large parts of all configuration files +are identical. But there are some macros that vary: + +@table @code +@findex USG +@item USG +Define this macro if the host system is System V. + +@findex VMS +@item VMS +Define this macro if the host system is VMS. + +@findex FAILURE_EXIT_CODE +@item FAILURE_EXIT_CODE +A C expression for the status code to be returned when the compiler +exits after serious errors. + +@findex SUCCESS_EXIT_CODE +@item SUCCESS_EXIT_CODE +A C expression for the status code to be returned when the compiler +exits without serious errors. + +@findex HOST_WORDS_BIG_ENDIAN +@item HOST_WORDS_BIG_ENDIAN +Defined if the host machine stores words of multi-word values in +big-endian order. (GNU CC does not depend on the host byte ordering +within a word.) + +@findex HOST_FLOAT_WORDS_BIG_ENDIAN +@item HOST_FLOAT_WORDS_BIG_ENDIAN +Define this macro to be 1 if the host machine stores @code{DFmode}, +@code{XFmode} or @code{TFmode} floating point numbers in memory with the +word containing the sign bit at the lowest address; otherwise, define it +to be zero. + +This macro need not be defined if the ordering is the same as for +multi-word integers. + +@findex HOST_FLOAT_FORMAT +@item HOST_FLOAT_FORMAT +A numeric code distinguishing the floating point format for the host +machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the +alternatives and default. + +@findex HOST_BITS_PER_CHAR +@item HOST_BITS_PER_CHAR +A C expression for the number of bits in @code{char} on the host +machine. + +@findex HOST_BITS_PER_SHORT +@item HOST_BITS_PER_SHORT +A C expression for the number of bits in @code{short} on the host +machine. + +@findex HOST_BITS_PER_INT +@item HOST_BITS_PER_INT +A C expression for the number of bits in @code{int} on the host +machine. + +@findex HOST_BITS_PER_LONG +@item HOST_BITS_PER_LONG +A C expression for the number of bits in @code{long} on the host +machine. + +@findex ONLY_INT_FIELDS +@item ONLY_INT_FIELDS +Define this macro to indicate that the host compiler only supports +@code{int} bit fields, rather than other integral types, including +@code{enum}, as do most C compilers. + +@findex EXECUTABLE_SUFFIX +@item EXECUTABLE_SUFFIX +Define this macro if the host system uses a naming convention for +executable files that involves a common suffix (such as, in some +systems, @samp{.exe}) that must be mentioned explicitly when you run +the program. + +@findex OBSTACK_CHUNK_SIZE +@item OBSTACK_CHUNK_SIZE +A C expression for the size of ordinary obstack chunks. +If you don't define this, a usually-reasonable default is used. + +@findex OBSTACK_CHUNK_ALLOC +@item OBSTACK_CHUNK_ALLOC +The function used to allocate obstack chunks. +If you don't define this, @code{xmalloc} is used. + +@findex OBSTACK_CHUNK_FREE +@item OBSTACK_CHUNK_FREE +The function used to free obstack chunks. +If you don't define this, @code{free} is used. + +@findex USE_C_ALLOCA +@item USE_C_ALLOCA +Define this macro to indicate that the compiler is running with the +@code{alloca} implemented in C. This version of @code{alloca} can be +found in the file @file{alloca.c}; to use it, you must also alter the +@file{Makefile} variable @code{ALLOCA}. (This is done automatically +for the systems on which we know it is needed.) + +If you do define this macro, you should probably do it as follows: + +@example +#ifndef __GNUC__ +#define USE_C_ALLOCA +#else +#define alloca __builtin_alloca +#endif +@end example + +@noindent +so that when the compiler is compiled with GNU CC it uses the more +efficient built-in @code{alloca} function. + +@item FUNCTION_CONVERSION_BUG +@findex FUNCTION_CONVERSION_BUG +Define this macro to indicate that the host compiler does not properly +handle converting a function value to a pointer-to-function when it is +used in an expression. + +@findex HAVE_VPRINTF +@findex vprintf +@item HAVE_VPRINTF +Define this if the library function @code{vprintf} is available on your +system. + +@findex MULTIBYTE_CHARS +@item MULTIBYTE_CHARS +Define this macro to enable support for multibyte characters in the +input to GNU CC. This requires that the host system support the ANSI C +library functions for converting multibyte characters to wide +characters. + +@findex HAVE_PUTENV +@findex putenv +@item HAVE_PUTENV +Define this if the library function @code{putenv} is available on your +system. + +@findex NO_SYS_SIGLIST +@item NO_SYS_SIGLIST +Define this if your system @emph{does not} provide the variable +@code{sys_siglist}. + +@findex DONT_DECLARE_SYS_SIGLIST +@item DONT_DECLARE_SYS_SIGLIST +Define this if your system has the variable @code{sys_siglist}, and +there is already a declaration of it in the system header files. + +@findex USE_PROTOTYPES +@item USE_PROTOTYPES +Define this to be 1 if you know that the host compiler supports +prototypes, even if it doesn't define __STDC__, or define +it to be 0 if you do not want any prototypes used in compiling +GNU CC. If @samp{USE_PROTOTYPES} is not defined, it will be +determined automatically whether your compiler supports +prototypes by checking if @samp{__STDC__} is defined. + +@findex NO_MD_PROTOTYPES +@item NO_MD_PROTOTYPES +Define this if you wish suppression of prototypes generated from +the machine description file, but to use other prototypes within +GNU CC. If @samp{USE_PROTOTYPES} is defined to be 0, or the +host compiler does not support prototypes, this macro has no +effect. + +@findex MD_CALL_PROTOTYPES +@item MD_CALL_PROTOTYPES +Define this if you wish to generate prototypes for the +@code{gen_call} or @code{gen_call_value} functions generated from +the machine description file. If @samp{USE_PROTOTYPES} is +defined to be 0, or the host compiler does not support +prototypes, or @samp{NO_MD_PROTOTYPES} is defined, this macro has +no effect. As soon as all of the machine descriptions are +modified to have the appropriate number of arguments, this macro +will be removed. + +@vindex sys_siglist +Some systems do provide this variable, but with a different name such +as @code{_sys_siglist}. On these systems, you can define +@code{sys_siglist} as a macro which expands into the name actually +provided. + +@findex NO_STAB_H +@item NO_STAB_H +Define this if your system does not have the include file +@file{stab.h}. If @samp{USG} is defined, @samp{NO_STAB_H} is +assumed. + +@findex PATH_SEPARATOR +@item PATH_SEPARATOR +Define this macro to be a C character constant representing the +character used to separate components in paths. The default value is. +the colon character + +@findex DIR_SEPARATOR +@item DIR_SEPARATOR +If your system uses some character other than slash to separate +directory names within a file specification, define this macro to be a C +character constant specifying that character. When GNU CC displays file +names, the character you specify will be used. GNU CC will test for +both slash and the character you specify when parsing filenames. +@end table + +@findex bzero +@findex bcmp +In addition, configuration files for system V define @code{bcopy}, +@code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca} +as a macro when compiled with GNU CC, in order to take advantage of the +benefit of GNU CC's built-in @code{alloca}. + + +@node Index +@unnumbered Index +@end ifset + +@ifclear INTERNALS +@node Index +@unnumbered Index +@end ifclear + +@printindex cp +@summarycontents +@contents +@bye diff --git a/gnu/usr.bin/cc/doc/gpcompare.texi b/gnu/usr.bin/cc/doc/gpcompare.texi new file mode 100644 index 0000000..07a7ab5 --- /dev/null +++ b/gnu/usr.bin/cc/doc/gpcompare.texi @@ -0,0 +1,236 @@ +@node ANSI +@chapter @sc{gnu} C++ Conformance to @sc{ansi} C++ + +These changes in the @sc{gnu} C++ compiler were made to comply more +closely with the @sc{ansi} base document, @cite{The Annotated C++ +Reference Manual} (the @sc{arm}). Further reducing the divergences from +@sc{ansi} C++ is a continued goal of the @sc{gnu} C++ Renovation +Project. + +@b{Section 3.4}, @i{Start and Termination}. It is now illegal to take +the address of the function @samp{main()}. + +@b{Section 4.8}, @i{Pointers to Members}. The compiler produces +an error for trying to convert between a pointer to a member and the type +@samp{void *}. + +@b{Section 5.2.5}, @i{Increment and Decrement}. It is an error to use +the increment and decrement operators on an enumerated type. + +@b{Section 5.3.2}, @i{Sizeof}. Doing @code{sizeof} on a function is now +an error. + +@b{Section 5.3.4}, @i{Delete}. The syntax of a @i{cast-expression} is +now more strictly controlled. + +@b{Section 7.1.1}, @i{Storage Class Specifiers}. Using the +@code{static} and @code{extern} specifiers can now only be applied to +names of objects, functions, and anonymous unions. + +@b{Section 7.1.1}, @i{Storage Class Specifiers}. The compiler no longer complains +about taking the address of a variable which has been declared to have @code{register} +storage. + +@b{Section 7.1.2}, @i{Function Specifiers}. The compiler produces an +error when the @code{inline} or @code{virtual} specifiers are +used on anything other than a function. + +@b{Section 8.3}, @i{Function Definitions}. It is now an error to shadow +a parameter name with a local variable; in the past, the compiler only +gave a warning in such a situation. + +@b{Section 8.4.1}, @i{Aggregates}. The rules concerning declaration of +an aggregate are now all checked in the @sc{gnu} C++ compiler; they +include having no private or protected members and no base classes. + +@b{Section 8.4.3}, @i{References}. Declaring an array of references is +now forbidden. Initializing a reference with an initializer list is +also considered an error. + +@b{Section 9.5}, @i{Unions}. Global anonymous unions must be declared +@code{static}. + +@b{Section 11.4}, @i{Friends}. Declaring a member to be a friend of a +type that has not yet been defined is an error. + +@b{Section 12.1}, @i{Constructors}. The compiler generates a +default copy constructor for a class if no constructor has been declared. + +@ignore +@b{Section 12.4}, @i{Destructors}. In accordance with the @sc{ansi} C++ +draft standard working paper, a pure virtual destructor must now be +defined. +@end ignore + +@b{Section 12.6.2}, @i{Special Member Functions}. When using a +@i{mem-initializer} list, the compiler will now initialize class members +in declaration order, not in the order in which you specify them. +Also, the compiler enforces the rule that non-static @code{const} +and reference members must be initialized with a @i{mem-initializer} +list when their class does not have a constructor. + +@b{Section 12.8}, @i{Copying Class Objects}. The compiler generates +default copy constructors correctly, and supplies default assignment +operators compatible with user-defined ones. + +@b{Section 13.4}, @i{Overloaded Operators}. An overloaded operator may +no longer have default arguments. + +@b{Section 13.4.4}, @i{Function Call}. An overloaded @samp{operator ()} +must be a non-static member function. + +@b{Section 13.4.5}, @i{Subscripting}. An overloaded @samp{operator []} +must be a non-static member function. + +@b{Section 13.4.6}, @i{Class Member Access}. An overloaded @samp{operator ->} +must be a non-static member function. + +@b{Section 13.4.7}, @i{Increment and Decrement}. The compiler will now +make sure a postfix @samp{@w{operator ++}} or @samp{@w{operator --}} has an +@code{int} as its second argument. + + +@node Encoding +@chapter Name Encoding in @sc{gnu} C++ + +@c FIXME!! rewrite name encoding section +@c ...to give complete rules rather than diffs from ARM. +@c To avoid plagiarism, invent some different way of structuring the +@c description of the rules than what ARM uses. + +@cindex mangling +@cindex name encoding +@cindex encoding information in names +In order to support its strong typing rules and the ability to provide +function overloading, the C++ programming language @dfn{encodes} +information about functions and objects, so that conflicts across object +files can be detected during linking. @footnote{This encoding is also +sometimes called, whimsically enough, @dfn{mangling}; the corresponding +decoding is sometimes called @dfn{demangling}.} These rules tend to be +unique to each individual implementation of C++. + +The scheme detailed in the commentary for 7.2.1 of @cite{The Annotated +Reference Manual} offers a description of a possible implementation +which happens to closely resemble the @code{cfront} compiler. The +design used in @sc{gnu} C++ differs from this model in a number of ways: + +@itemize @bullet +@item +In addition to the basic types @code{void}, @code{char}, @code{short}, +@code{int}, @code{long}, @code{float}, @code{double}, and @code{long +double}, @sc{gnu} C++ supports two additional types: @code{wchar_t}, the wide +character type, and @code{long long} (if the host supports it). The +encodings for these are @samp{w} and @samp{x} respectively. + +@item +According to the @sc{arm}, qualified names (e.g., @samp{foo::bar::baz}) are +encoded with a leading @samp{Q}. Followed by the number of +qualifications (in this case, three) and the respective names, this +might be encoded as @samp{Q33foo3bar3baz}. @sc{gnu} C++ adds a leading +underscore to the list, producing @samp{_Q33foo3bar3baz}. + +@item +The operator @samp{*=} is encoded as @samp{__aml}, not @samp{__amu}, to +match the normal @samp{*} operator, which is encoded as @samp{__ml}. + +@c XXX left out ->(), __wr +@item +In addition to the normal operators, @sc{gnu} C++ also offers the minimum and +maximum operators @samp{>?} and @samp{<?}, encoded as @samp{__mx} and +@samp{__mn}, and the conditional operator @samp{?:}, encoded as @samp{__cn}. + +@cindex destructors, encoding of +@cindex constructors, encoding of +@item +Constructors are encoded as simply @samp{__@var{name}}, where @var{name} +is the encoded name (e.g., @code{3foo} for the @code{foo} class +constructor). Destructors are encoded as two leading underscores +separated by either a period or a dollar sign, depending on the +capabilities of the local host, followed by the encoded name. For +example, the destructor @samp{foo::~foo} is encoded as @samp{_$_3foo}. + +@item +Virtual tables are encoded with a prefix of @samp{_vt}, rather than +@samp{__vtbl}. The names of their classes are separated by dollar signs +(or periods), and not encoded as normal: the virtual table for +@code{foo} is @samp{__vt$foo}, and the table for @code{foo::bar} is +named @samp{__vt$foo$bar}. + +@item +Static members are encoded as a leading underscore, followed by the +encoded name of the class in which they appear, a separating dollar sign +or period, and finally the unencoded name of the variable. For example, +if the class @code{foo} contains a static member @samp{bar}, its +encoding would be @samp{_3foo$bar}. + +@item +@sc{gnu} C++ is not as aggressive as other compilers when it comes to always +generating @samp{Fv} for functions with no arguments. In particular, +the compiler does not add the sequence to conversion operators. The +function @samp{foo::bar()} is encoded as @samp{bar__3foo}, not +@samp{bar__3fooFv}. + +@item +The argument list for methods is not prefixed by a leading @samp{F}; it +is considered implied. + +@item +@sc{gnu} C++ approaches the task of saving space in encodings +differently from that noted in the @sc{arm}. It does use the +@samp{T@var{n}} and @samp{N@var{x}@var{y}} codes to signify copying the +@var{n}th argument's type, and making the next @var{x} arguments be the +type of the @var{y}th argument, respectively. However, the values for +@var{n} and @var{y} begin at zero with @sc{gnu} C++, whereas the +@sc{arm} describes them as starting at one. For the function @samp{foo +(bartype, bartype)}, @sc{gnu} C++ uses @samp{foo__7bartypeT0}, while +compilers following the @sc{arm} example generate @samp{foo__7bartypeT1}. + +@c Note it loses on `foo (int, int, int, int, int)'. +@item +@sc{gnu} C++ does not bother using the space-saving methods for types whose +encoding is a single character (like an integer, encoded as @samp{i}). +This is useful in the most common cases (two @code{int}s would result in +using three letters, instead of just @samp{ii}). +@end itemize + +@c @node Cfront +@c @chapter @code{cfront} Compared to @sc{gnu} C++ +@c +@c +@c FIXME!! Fill in. Consider points in the following: +@c +@c @display +@c Date: Thu, 2 Jan 92 21:35:20 EST +@c From: raeburn@@cygnus.com +@c Message-Id: <9201030235.AA10999@@cambridge.cygnus.com> +@c To: mrs@@charlie.secs.csun.edu +@c Cc: g++@@cygnus.com +@c Subject: Re: ARM and GNU C++ incompatabilities +@c +@c Along with that, we should probably describe how g++ differs from +@c cfront, in ways that the users will notice. (E.g., cfront supposedly +@c allows "free (new char[10])"; does g++? How do the template +@c implementations differ? "New" placement syntax?) +@c @end display +@c +@c XXX For next revision. +@c +@c GNU C++: +@c * supports expanding inline functions in many situations, +@c including those which have static objects, use `for' statements, +@c and other situations. Part of this versatility is due to is +@c ability to not always generate temporaries for assignments. +@c * deliberately allows divide by 0 and mod 0, since [according +@c to Wilson] there are actually situations where you'd like to allow +@c such things. Note on most systems it will cause some sort of trap +@c or bus error. Cfront considers it an error. +@c * does [appear to] support nested classes within templates. +@c * conversion functions among baseclasses are all usable by +@c a class that's derived from all of those bases. +@c * sizeof works even when the class is defined within its ()'s +@c * conditional expressions work with member fns and pointers to +@c members. +@c * can handle non-trivial declarations of variables within switch +@c statements. +@c +@c Cfront: diff --git a/gnu/usr.bin/cc/doc/gxxint.texi b/gnu/usr.bin/cc/doc/gxxint.texi new file mode 100644 index 0000000..2441da1 --- /dev/null +++ b/gnu/usr.bin/cc/doc/gxxint.texi @@ -0,0 +1,1271 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename g++int.info +@settitle G++ internals +@setchapternewpage odd +@c %**end of header + +@node Top, Limitations of g++, (dir), (dir) +@chapter Internal Architecture of the Compiler + +This is meant to describe the C++ front-end for gcc in detail. +Questions and comments to mrs@@cygnus.com. + +@menu +* Limitations of g++:: +* Routines:: +* Implementation Specifics:: +* Glossary:: +* Macros:: +* Typical Behavior:: +* Coding Conventions:: +* Templates:: +* Access Control:: +* Error Reporting:: +* Parser:: +* Copying Objects:: +* Exception Handling:: +* Free Store:: +* Concept Index:: +@end menu + +@node Limitations of g++, Routines, Top, Top +@section Limitations of g++ + +@itemize @bullet +@item +Limitations on input source code: 240 nesting levels with the parser +stacksize (YYSTACKSIZE) set to 500 (the default), and requires around +16.4k swap space per nesting level. The parser needs about 2.09 * +number of nesting levels worth of stackspace. + +@cindex pushdecl_class_level +@item +I suspect there are other uses of pushdecl_class_level that do not call +set_identifier_type_value in tandem with the call to +pushdecl_class_level. It would seem to be an omission. + +@cindex access checking +@item +Access checking is unimplemented for nested types. + +@cindex @code{volatile} +@item +@code{volatile} is not implemented in general. + +@cindex pointers to members +@item +Pointers to members are only minimally supported, and there are places +where the grammar doesn't even properly accept them yet. + +@cindex multiple inheritance +@item +@code{this} will be wrong in virtual members functions defined in a +virtual base class, when they are overridden in a derived class, when +called via a non-left most object. + +An example would be: + +@example +extern "C" int printf(const char*, ...); +struct A @{ virtual void f() @{ @} @}; +struct B : virtual A @{ int b; B() : b(0) @{@} void f() @{ b++; @} @}; +struct C : B @{@}; +struct D : B @{@}; +struct E : C, D @{@}; +int main() +@{ + E e; + C& c = e; D& d = e; + c.f(); d.f(); + printf ("C::b = %d, D::b = %d\n", e.C::b, e.D::b); + return 0; +@} +@end example + +This will print out 2, 0, instead of 1,1. + +@end itemize + +@node Routines, Implementation Specifics, Limitations of g++, Top +@section Routines + +This section describes some of the routines used in the C++ front-end. + +@code{build_vtable} and @code{prepare_fresh_vtable} is used only within +the @file{cp-class.c} file, and only in @code{finish_struct} and +@code{modify_vtable_entries}. + +@code{build_vtable}, @code{prepare_fresh_vtable}, and +@code{finish_struct} are the only routines that set @code{DECL_VPARENT}. + +@code{finish_struct} can steal the virtual function table from parents, +this prohibits related_vslot from working. When finish_struct steals, +we know that + +@example +get_binfo (DECL_FIELD_CONTEXT (CLASSTYPE_VFIELD (t)), t, 0) +@end example + +@noindent +will get the related binfo. + +@code{layout_basetypes} does something with the VIRTUALS. + +Supposedly (according to Tiemann) most of the breadth first searching +done, like in @code{get_base_distance} and in @code{get_binfo} was not +because of any design decision. I have since found out the at least one +part of the compiler needs the notion of depth first binfo searching, I +am going to try and convert the whole thing, it should just work. The +term left-most refers to the depth first left-most node. It uses +@code{MAIN_VARIANT == type} as the condition to get left-most, because +the things that have @code{BINFO_OFFSET}s of zero are shared and will +have themselves as their own @code{MAIN_VARIANT}s. The non-shared right +ones, are copies of the left-most one, hence if it is its own +@code{MAIN_VARIENT}, we know it IS a left-most one, if it is not, it is +a non-left-most one. + +@code{get_base_distance}'s path and distance matters in its use in: + +@itemize @bullet +@item +@code{prepare_fresh_vtable} (the code is probably wrong) +@item +@code{init_vfields} Depends upon distance probably in a safe way, +build_offset_ref might use partial paths to do further lookups, +hack_identifier is probably not properly checking access. + +@item +@code{get_first_matching_virtual} probably should check for +@code{get_base_distance} returning -2. + +@item +@code{resolve_offset_ref} should be called in a more deterministic +manner. Right now, it is called in some random contexts, like for +arguments at @code{build_method_call} time, @code{default_conversion} +time, @code{convert_arguments} time, @code{build_unary_op} time, +@code{build_c_cast} time, @code{build_modify_expr} time, +@code{convert_for_assignment} time, and +@code{convert_for_initialization} time. + +But, there are still more contexts it needs to be called in, one was the +ever simple: + +@example +if (obj.*pmi != 7) + @dots{} +@end example + +Seems that the problems were due to the fact that @code{TREE_TYPE} of +the @code{OFFSET_REF} was not a @code{OFFSET_TYPE}, but rather the type +of the referent (like @code{INTEGER_TYPE}). This problem was fixed by +changing @code{default_conversion} to check @code{TREE_CODE (x)}, +instead of only checking @code{TREE_CODE (TREE_TYPE (x))} to see if it +was @code{OFFSET_TYPE}. + +@end itemize + +@node Implementation Specifics, Glossary, Routines, Top +@section Implementation Specifics + +@itemize @bullet +@item Explicit Initialization + +The global list @code{current_member_init_list} contains the list of +mem-initializers specified in a constructor declaration. For example: + +@example +foo::foo() : a(1), b(2) @{@} +@end example + +@noindent +will initialize @samp{a} with 1 and @samp{b} with 2. +@code{expand_member_init} places each initialization (a with 1) on the +global list. Then, when the fndecl is being processed, +@code{emit_base_init} runs down the list, initializing them. It used to +be the case that g++ first ran down @code{current_member_init_list}, +then ran down the list of members initializing the ones that weren't +explicitly initialized. Things were rewritten to perform the +initializations in order of declaration in the class. So, for the above +example, @samp{a} and @samp{b} will be initialized in the order that +they were declared: + +@example +class foo @{ public: int b; int a; foo (); @}; +@end example + +@noindent +Thus, @samp{b} will be initialized with 2 first, then @samp{a} will be +initialized with 1, regardless of how they're listed in the mem-initializer. + +@item Argument Matching + +In early 1993, the argument matching scheme in @sc{gnu} C++ changed +significantly. The original code was completely replaced with a new +method that will, hopefully, be easier to understand and make fixing +specific cases much easier. + +The @samp{-fansi-overloading} option is used to enable the new code; at +some point in the future, it will become the default behavior of the +compiler. + +The file @file{cp-call.c} contains all of the new work, in the functions +@code{rank_for_overload}, @code{compute_harshness}, +@code{compute_conversion_costs}, and @code{ideal_candidate}. + +Instead of using obscure numerical values, the quality of an argument +match is now represented by clear, individual codes. The new data +structure @code{struct harshness} (it used to be an @code{unsigned} +number) contains: + +@enumerate a +@item the @samp{code} field, to signify what was involved in matching two +arguments; +@item the @samp{distance} field, used in situations where inheritance +decides which function should be called (one is ``closer'' than +another); +@item and the @samp{int_penalty} field, used by some codes as a tie-breaker. +@end enumerate + +The @samp{code} field is a number with a given bit set for each type of +code, OR'd together. The new codes are: + +@itemize @bullet +@item @code{EVIL_CODE} +The argument was not a permissible match. + +@item @code{CONST_CODE} +Currently, this is only used by @code{compute_conversion_costs}, to +distinguish when a non-@code{const} member function is called from a +@code{const} member function. + +@item @code{ELLIPSIS_CODE} +A match against an ellipsis @samp{...} is considered worse than all others. + +@item @code{USER_CODE} +Used for a match involving a user-defined conversion. + +@item @code{STD_CODE} +A match involving a standard conversion. + +@item @code{PROMO_CODE} +A match involving an integral promotion. For these, the +@code{int_penalty} field is used to handle the ARM's rule (XXX cite) +that a smaller @code{unsigned} type should promote to a @code{int}, not +to an @code{unsigned int}. + +@item @code{QUAL_CODE} +Used to mark use of qualifiers like @code{const} and @code{volatile}. + +@item @code{TRIVIAL_CODE} +Used for trivial conversions. The @samp{int_penalty} field is used by +@code{convert_harshness} to communicate further penalty information back +to @code{build_overload_call_real} when deciding which function should +be call. +@end itemize + +The functions @code{convert_to_aggr} and @code{build_method_call} use +@code{compute_conversion_costs} to rate each argument's suitability for +a given candidate function (that's how we get the list of candidates for +@code{ideal_candidate}). + +@end itemize + +@node Glossary, Macros, Implementation Specifics, Top +@section Glossary + +@table @r +@item binfo +The main data structure in the compiler used to represent the +inheritance relationships between classes. The data in the binfo can be +accessed by the BINFO_ accessor macros. + +@item vtable +@itemx virtual function table + +The virtual function table holds information used in virtual function +dispatching. In the compiler, they are usually referred to as vtables, +or vtbls. The first index is not used in the normal way, I believe it +is probably used for the virtual destructor. + +@item vfield + +vfields can be thought of as the base information needed to build +vtables. For every vtable that exists for a class, there is a vfield. +See also vtable and virtual function table pointer. When a type is used +as a base class to another type, the virtual function table for the +derived class can be based upon the vtable for the base class, just +extended to include the additional virtual methods declared in the +derived class. The virtual function table from a virtual base class is +never reused in a derived class. @code{is_normal} depends upon this. + +@item virtual function table pointer + +These are @code{FIELD_DECL}s that are pointer types that point to +vtables. See also vtable and vfield. +@end table + +@node Macros, Typical Behavior, Glossary, Top +@section Macros + +This section describes some of the macros used on trees. The list +should be alphabetical. Eventually all macros should be documented +here. There are some postscript drawings that can be used to better +understnad from of the more complex data structures, contact Mike Stump +(@code{mrs@@cygnus.com}) for information about them. + +@table @code +@item BINFO_BASETYPES +A vector of additional binfos for the types inherited by this basetype. +The binfos are fully unshared (except for virtual bases, in which +case the binfo structure is shared). + + If this basetype describes type D as inherited in C, + and if the basetypes of D are E anf F, + then this vector contains binfos for inheritance of E and F by C. + +Has values of: + + TREE_VECs + + +@item BINFO_INHERITANCE_CHAIN +Temporarily used to represent specific inheritances. It usually points +to the binfo associated with the lesser derived type, but it can be +reversed by reverse_path. For example: + +@example + Z ZbY least derived + | + Y YbX + | + X Xb most derived + +TYPE_BINFO (X) == Xb +BINFO_INHERITANCE_CHAIN (Xb) == YbX +BINFO_INHERITANCE_CHAIN (Yb) == ZbY +BINFO_INHERITANCE_CHAIN (Zb) == 0 +@end example + +Not sure is the above is really true, get_base_distance has is point +towards the most derived type, opposite from above. + +Set by build_vbase_path, recursive_bounded_basetype_p, +get_base_distance, lookup_field, lookup_fnfields, and reverse_path. + +What things can this be used on: + + TREE_VECs that are binfos + + +@item BINFO_OFFSET +The offset where this basetype appears in its containing type. +BINFO_OFFSET slot holds the offset (in bytes) from the base of the +complete object to the base of the part of the object that is allocated +on behalf of this `type'. This is always 0 except when there is +multiple inheritance. + +Used on TREE_VEC_ELTs of the binfos BINFO_BASETYPES (...) for example. + + +@item BINFO_VIRTUALS +A unique list of functions for the virtual function table. See also +TYPE_BINFO_VIRTUALS. + +What things can this be used on: + + TREE_VECs that are binfos + + +@item BINFO_VTABLE +Used to find the VAR_DECL that is the virtual function table associated +with this binfo. See also TYPE_BINFO_VTABLE. To get the virtual +function table pointer, see CLASSTYPE_VFIELD. + +What things can this be used on: + + TREE_VECs that are binfos + +Has values of: + + VAR_DECLs that are virtual function tables + + +@item BLOCK_SUPERCONTEXT +In the outermost scope of each function, it points to the FUNCTION_DECL +node. It aids in better DWARF support of inline functions. + + +@item CLASSTYPE_TAGS +CLASSTYPE_TAGS is a linked (via TREE_CHAIN) list of member classes of a +class. TREE_PURPOSE is the name, TREE_VALUE is the type (pushclass scans +these and calls pushtag on them.) + +finish_struct scans these to produce TYPE_DECLs to add to the +TYPE_FIELDS of the type. + +It is expected that name found in the TREE_PURPOSE slot is unique, +resolve_scope_to_name is one such place that depends upon this +uniqueness. + + +@item CLASSTYPE_METHOD_VEC +The following is true after finish_struct has been called (on the +class?) but not before. Before finish_struct is called, things are +different to some extent. Contains a TREE_VEC of methods of the class. +The TREE_VEC_LENGTH is the number of differently named methods plus one +for the 0th entry. The 0th entry is always allocated, and reserved for +ctors and dtors. If there are none, TREE_VEC_ELT(N,0) == NULL_TREE. +Each entry of the TREE_VEC is a FUNCTION_DECL. For each FUNCTION_DECL, +there is a DECL_CHAIN slot. If the FUNCTION_DECL is the last one with a +given name, the DECL_CHAIN slot is NULL_TREE. Otherwise it is the next +method that has the same name (but a different signature). It would +seem that it is not true that because the DECL_CHAIN slot is used in +this way, we cannot call pushdecl to put the method in the global scope +(cause that would overwrite the TREE_CHAIN slot), because they use +different _CHAINs. finish_struct_methods setups up one version of the +TREE_CHAIN slots on the FUNCTION_DECLs. + +friends are kept in TREE_LISTs, so that there's no need to use their +TREE_CHAIN slot for anything. + +Has values of: + + TREE_VECs + + +@item CLASSTYPE_VFIELD +Seems to be in the process of being renamed TYPE_VFIELD. Use on types +to get the main virtual function table pointer. To get the virtual +function table use BINFO_VTABLE (TYPE_BINFO ()). + +Has values of: + + FIELD_DECLs that are virtual function table pointers + +What things can this be used on: + + RECORD_TYPEs + + +@item DECL_CLASS_CONTEXT +Identifies the context that the _DECL was found in. For virtual function +tables, it points to the type associated with the virtual function +table. See also DECL_CONTEXT, DECL_FIELD_CONTEXT and DECL_FCONTEXT. + +The difference between this and DECL_CONTEXT, is that for virtuals +functions like: + +@example +struct A +@{ + virtual int f (); +@}; + +struct B : A +@{ + int f (); +@}; + +DECL_CONTEXT (A::f) == A +DECL_CLASS_CONTEXT (A::f) == A + +DECL_CONTEXT (B::f) == A +DECL_CLASS_CONTEXT (B::f) == B +@end example + +Has values of: + + RECORD_TYPEs, or UNION_TYPEs + +What things can this be used on: + + TYPE_DECLs, _DECLs + + +@item DECL_CONTEXT +Identifies the context that the _DECL was found in. Can be used on +virtual function tables to find the type associated with the virtual +function table, but since they are FIELD_DECLs, DECL_FIELD_CONTEXT is a +better access method. Internally the same as DECL_FIELD_CONTEXT, so +don't us both. See also DECL_FIELD_CONTEXT, DECL_FCONTEXT and +DECL_CLASS_CONTEXT. + +Has values of: + + RECORD_TYPEs + + +What things can this be used on: + +@display +VAR_DECLs that are virtual function tables +_DECLs +@end display + + +@item DECL_FIELD_CONTEXT +Identifies the context that the FIELD_DECL was found in. Internally the +same as DECL_CONTEXT, so don't us both. See also DECL_CONTEXT, +DECL_FCONTEXT and DECL_CLASS_CONTEXT. + +Has values of: + + RECORD_TYPEs + +What things can this be used on: + +@display +FIELD_DECLs that are virtual function pointers +FIELD_DECLs +@end display + + +@item DECL_NESTED_TYPENAME +Holds the fully qualified type name. Example, Base::Derived. + +Has values of: + + IDENTIFIER_NODEs + +What things can this be used on: + + TYPE_DECLs + + +@item DECL_NAME + +Has values of: + +@display +0 for things that don't have names +IDENTIFIER_NODEs for TYPE_DECLs +@end display + +@item DECL_IGNORED_P +A bit that can be set to inform the debug information output routines in +the back-end that a certain _DECL node should be totally ignored. + +Used in cases where it is known that the debugging information will be +output in another file, or where a sub-type is known not to be needed +because the enclosing type is not needed. + +A compiler constructed virtual destructor in derived classes that do not +define an exlicit destructor that was defined exlicit in a base class +has this bit set as well. Also used on __FUNCTION__ and +__PRETTY_FUNCTION__ to mark they are ``compiler generated.'' c-decl and +c-lex.c both want DECL_IGNORED_P set for ``internally generated vars,'' +and ``user-invisible variable.'' + +Functions built by the C++ front-end such as default destructors, +virtual desctructors and default constructors want to be marked that +they are compiler generated, but unsure why. + +Currently, it is used in an absolute way in the C++ front-end, as an +optimization, to tell the debug information output routines to not +generate debugging information that will be output by another separately +compiled file. + + +@item DECL_VIRTUAL_P +A flag used on FIELD_DECLs and VAR_DECLs. (Documentation in tree.h is +wrong.) Used in VAR_DECLs to indicate that the variable is a vtable. +It is also used in FIELD_DECLs for vtable pointers. + +What things can this be used on: + + FIELD_DECLs and VAR_DECLs + + +@item DECL_VPARENT +Used to point to the parent type of the vtable if there is one, else it +is just the type associated with the vtable. Because of the sharing of +virtual function tables that goes on, this slot is not very useful, and +is in fact, not used in the compiler at all. It can be removed. + +What things can this be used on: + + VAR_DECLs that are virtual function tables + +Has values of: + + RECORD_TYPEs maybe UNION_TYPEs + + +@item DECL_FCONTEXT +Used to find the first baseclass in which this FIELD_DECL is defined. +See also DECL_CONTEXT, DECL_FIELD_CONTEXT and DECL_CLASS_CONTEXT. + +How it is used: + + Used when writing out debugging information about vfield and + vbase decls. + +What things can this be used on: + + FIELD_DECLs that are virtual function pointers + FIELD_DECLs + + +@item DECL_REFERENCE_SLOT +Used to hold the initialize for the reference. + +What things can this be used on: + + PARM_DECLs and VAR_DECLs that have a reference type + + +@item DECL_VINDEX +Used for FUNCTION_DECLs in two different ways. Before the structure +containing the FUNCTION_DECL is laid out, DECL_VINDEX may point to a +FUNCTION_DECL in a base class which is the FUNCTION_DECL which this +FUNCTION_DECL will replace as a virtual function. When the class is +laid out, this pointer is changed to an INTEGER_CST node which is +suitable to find an index into the virtual function table. See +get_vtable_entry as to how one can find the right index into the virtual +function table. The first index 0, of a virtual function table it not +used in the normal way, so the first real index is 1. + +DECL_VINDEX may be a TREE_LIST, that would seem to be a list of +overridden FUNCTION_DECLs. add_virtual_function has code to deal with +this when it uses the variable base_fndecl_list, but it would seem that +somehow, it is possible for the TREE_LIST to pursist until method_call, +and it should not. + + +What things can this be used on: + + FUNCTION_DECLs + + +@item DECL_SOURCE_FILE +Identifies what source file a particular declaration was found in. + +Has values of: + + "<built-in>" on TYPE_DECLs to mean the typedef is built in + + +@item DECL_SOURCE_LINE +Identifies what source line number in the source file the declaration +was found at. + +Has values of: + +@display +0 for an undefined label + +0 for TYPE_DECLs that are internally generated + +0 for FUNCTION_DECLs for functions generated by the compiler + (not yet, but should be) + +0 for ``magic'' arguments to functions, that the user has no + control over +@end display + + +@item TREE_USED + +Has values of: + + 0 for unused labels + + +@item TREE_ADDRESSABLE +A flag that is set for any type that has a constructor. + + +@item TREE_COMPLEXITY +They seem a kludge way to track recursion, poping, and pushing. They only +appear in cp-decl.c and cp-decl2.c, so the are a good candidate for +proper fixing, and removal. + + +@item TREE_PRIVATE +Set for FIELD_DECLs by finish_struct. But not uniformly set. + +The following routines do something with PRIVATE access: +build_method_call, alter_access, finish_struct_methods, +finish_struct, convert_to_aggr, CWriteLanguageDecl, CWriteLanguageType, +CWriteUseObject, compute_access, lookup_field, dfs_pushdecl, +GNU_xref_member, dbxout_type_fields, dbxout_type_method_1 + + +@item TREE_PROTECTED +The following routines do something with PROTECTED access: +build_method_call, alter_access, finish_struct, convert_to_aggr, +CWriteLanguageDecl, CWriteLanguageType, CWriteUseObject, +compute_access, lookup_field, GNU_xref_member, dbxout_type_fields, +dbxout_type_method_1 + + +@item TYPE_BINFO +Used to get the binfo for the type. + +Has values of: + + TREE_VECs that are binfos + +What things can this be used on: + + RECORD_TYPEs + + +@item TYPE_BINFO_BASETYPES +See also BINFO_BASETYPES. + +@item TYPE_BINFO_VIRTUALS +A unique list of functions for the virtual function table. See also +BINFO_VIRTUALS. + +What things can this be used on: + + RECORD_TYPEs + + +@item TYPE_BINFO_VTABLE +Points to the virtual function table associated with the given type. +See also BINFO_VTABLE. + +What things can this be used on: + + RECORD_TYPEs + +Has values of: + + VAR_DECLs that are virtual function tables + + +@item TYPE_NAME +Names the type. + +Has values of: + +@display +0 for things that don't have names. +should be IDENTIFIER_NODE for RECORD_TYPEs UNION_TYPEs and + ENUM_TYPEs. +TYPE_DECL for RECORD_TYPEs, UNION_TYPEs and ENUM_TYPEs, but + shouldn't be. +TYPE_DECL for typedefs, unsure why. +@end display + +What things can one use this on: + +@display +TYPE_DECLs +RECORD_TYPEs +UNION_TYPEs +ENUM_TYPEs +@end display + +History: + + It currently points to the TYPE_DECL for RECORD_TYPEs, + UNION_TYPEs and ENUM_TYPEs, but it should be history soon. + + +@item TYPE_METHODS +Synonym for @code{CLASSTYPE_METHOD_VEC}. Chained together with +@code{TREE_CHAIN}. @file{dbxout.c} uses this to get at the methods of a +class. + + +@item TYPE_DECL +Used to represent typedefs, and used to represent bindings layers. + +Components: + + DECL_NAME is the name of the typedef. For example, foo would + be found in the DECL_NAME slot when @code{typedef int foo;} is + seen. + + DECL_SOURCE_LINE identifies what source line number in the + source file the declaration was found at. A value of 0 + indicates that this TYPE_DECL is just an internal binding layer + marker, and does not correspond to a user suppiled typedef. + + DECL_SOURCE_FILE + +@item TYPE_FIELDS +A linked list (via @code{TREE_CHAIN}) of member types of a class. The +list can contain @code{TYPE_DECL}s, but there can also be other things +in the list apparently. See also @code{CLASSTYPE_TAGS}. + + +@item TYPE_VIRTUAL_P +A flag used on a @code{FIELD_DECL} or a @code{VAR_DECL}, indicates it is +a virtual function table or a pointer to one. When used on a +@code{FUNCTION_DECL}, indicates that it is a virtual function. When +used on an @code{IDENTIFIER_NODE}, indicates that a function with this +same name exists and has been declared virtual. + +When used on types, it indicates that the type has virtual functions, or +is derived from one that does. + +Not sure if the above about virtual function tables is still true. See +also info on @code{DECL_VIRTUAL_P}. + +What things can this be used on: + + FIELD_DECLs, VAR_DECLs, FUNCTION_DECLs, IDENTIFIER_NODEs + + +@item VF_BASETYPE_VALUE +Get the associated type from the binfo that caused the given vfield to +exist. This is the least derived class (the most parent class) that +needed a virtual function table. It is probably the case that all uses +of this field are misguided, but they need to be examined on a +case-by-case basis. See history for more information on why the +previous statement was made. + +Set at @code{finish_base_struct} time. + +What things can this be used on: + + TREE_LISTs that are vfields + +History: + + This field was used to determine if a virtual function table's + slot should be filled in with a certain virtual function, by + checking to see if the type returned by VF_BASETYPE_VALUE was a + parent of the context in which the old virtual function existed. + This incorrectly assumes that a given type _could_ not appear as + a parent twice in a given inheritance lattice. For single + inheritance, this would in fact work, because a type could not + possibly appear more than once in an inheritance lattice, but + with multiple inheritance, a type can appear more than once. + + +@item VF_BINFO_VALUE +Identifies the binfo that caused this vfield to exist. If this vfield +is from the first direct base class that has a virtual function table, +then VF_BINFO_VALUE is NULL_TREE, otherwise it will be the binfo of the +direct base where the vfield came from. Can use @code{TREE_VIA_VIRTUAL} +on result to find out if it is a virtual base class. Related to the +binfo found by + +@example +get_binfo (VF_BASETYPE_VALUE (vfield), t, 0) +@end example + +@noindent +where @samp{t} is the type that has the given vfield. + +@example +get_binfo (VF_BASETYPE_VALUE (vfield), t, 0) +@end example + +@noindent +will return the binfo for the the given vfield. + +May or may not be set at @code{modify_vtable_entries} time. Set at +@code{finish_base_struct} time. + +What things can this be used on: + + TREE_LISTs that are vfields + + +@item VF_DERIVED_VALUE +Identifies the type of the most derived class of the vfield, excluding +the the class this vfield is for. + +Set at @code{finish_base_struct} time. + +What things can this be used on: + + TREE_LISTs that are vfields + + +@item VF_NORMAL_VALUE +Identifies the type of the most derived class of the vfield, including +the class this vfield is for. + +Set at @code{finish_base_struct} time. + +What things can this be used on: + + TREE_LISTs that are vfields + + +@item WRITABLE_VTABLES +This is a option that can be defined when building the compiler, that +will cause the compiler to output vtables into the data segment so that +the vtables maybe written. This is undefined by default, because +normally the vtables should be unwritable. People that implement object +I/O facilities may, or people that want to change the dynamic type of +objects may want to have the vtables writable. Another way of achieving +this would be to make a copy of the vtable into writable memory, but the +drawback there is that that method only changes the type for one object. + +@end table + +@node Typical Behavior, Coding Conventions, Macros, Top +@section Typical Behavior + +@cindex parse errors + +Whenever seemingly normal code fails with errors like +@code{syntax error at `\@{'}, it's highly likely that grokdeclarator is +returning a NULL_TREE for whatever reason. + +@node Coding Conventions, Templates, Typical Behavior, Top +@section Coding Conventions + +It should never be that case that trees are modified in-place by the +back-end, @emph{unless} it is guaranteed that the semantics are the same +no matter how shared the tree structure is. @file{fold-const.c} still +has some cases where this is not true, but rms hypothesizes that this +will never be a problem. + +@node Templates, Access Control, Coding Conventions, Top +@section Templates + +g++ uses the simple approach to instantiating templates: it blindly +generates the code for each instantiation as needed. For class +templates, g++ pushes the template parameters into the namespace for the +duration of the instantiation; for function templates, it's a simple +search and replace. + +This approach does not support any of the template definition-time error +checking that is being bandied about by X3J16. It makes no attempt to deal +with name binding in a consistent way. + +Instantiation of a class template is triggered by the use of a template +class anywhere but in a straight declaration like @code{class A<int>}. +This is wrong; in fact, it should not be triggered by typedefs or +declarations of pointers. Now that explicit instantiation is supported, +this misfeature is not necessary. + +Important functions: + +@table @code +@item instantiate_class_template +This function +@end table + +@node Access Control, Error Reporting, Templates, Top +@section Access Control +The function compute_access returns one of three values: + +@table @code +@item access_public +means that the field can be accessed by the current lexical scope. + +@item access_protected +means that the field cannot be accessed by the current lexical scope +because it is protected. + +@item access_private +means that the field cannot be accessed by the current lexical scope +because it is private. +@end table + +DECL_ACCESS is used for access declarations; alter_access creates a list +of types and accesses for a given decl. + +Formerly, DECL_@{PUBLIC,PROTECTED,PRIVATE@} corresponded to the return +codes of compute_access and were used as a cache for compute_access. +Now they are not used at all. + +TREE_PROTECTED and TREE_PRIVATE are used to record the access levels +granted by the containing class. BEWARE: TREE_PUBLIC means something +completely unrelated to access control! + +@node Error Reporting, Parser, Access Control, Top +@section Error Reporting + +The C++ front-end uses a call-back mechanism to allow functions to print +out reasonable strings for types and functions without putting extra +logic in the functions where errors are found. The interface is through +the @code{cp_error} function (or @code{cp_warning}, etc.). The +syntax is exactly like that of @code{error}, except that a few more +conversions are supported: + +@itemize @bullet +@item +%C indicates a value of `enum tree_code'. +@item +%D indicates a *_DECL node. +@item +%E indicates a *_EXPR node. +@item +%L indicates a value of `enum languages'. +@item +%P indicates the name of a parameter (i.e. "this", "1", "2", ...) +@item +%T indicates a *_TYPE node. +@item +%O indicates the name of an operator (MODIFY_EXPR -> "operator ="). + +@end itemize + +There is some overlap between these; for instance, any of the node +options can be used for printing an identifier (though only @code{%D} +tries to decipher function names). + +For a more verbose message (@code{class foo} as opposed to just @code{foo}, +including the return type for functions), use @code{%#c}. +To have the line number on the error message indicate the line of the +DECL, use @code{cp_error_at} and its ilk; to indicate which argument you want, +use @code{%+D}, or it will default to the first. + +@node Parser, Copying Objects, Error Reporting, Top +@section Parser + +Some comments on the parser: + +The @code{after_type_declarator} / @code{notype_declarator} hack is +necessary in order to allow redeclarations of @code{TYPENAME}s, for +instance + +@example +typedef int foo; +class A @{ + char *foo; +@}; +@end example + +In the above, the first @code{foo} is parsed as a @code{notype_declarator}, +and the second as a @code{after_type_declarator}. + +Ambiguities: + +There are currently four reduce/reduce ambiguities in the parser. They are: + +1) Between @code{template_parm} and +@code{named_class_head_sans_basetype}, for the tokens @code{aggr +identifier}. This situation occurs in code looking like + +@example +template <class T> class A @{ @}; +@end example + +It is ambiguous whether @code{class T} should be parsed as the +declaration of a template type parameter named @code{T} or an unnamed +constant parameter of type @code{class T}. Section 14.6, paragraph 3 of +the January '94 working paper states that the first interpretation is +the correct one. This ambiguity results in two reduce/reduce conflicts. + +2) Between @code{primary} and @code{type_id} for code like @samp{int()} +in places where both can be accepted, such as the argument to +@code{sizeof}. Section 8.1 of the pre-San Diego working paper specifies +that these ambiguous constructs will be interpreted as @code{typename}s. +This ambiguity results in six reduce/reduce conflicts between +@samp{absdcl} and @samp{functional_cast}. + +3) Between @code{functional_cast} and +@code{complex_direct_notype_declarator}, for various token strings. +This situation occurs in code looking like + +@example +int (*a); +@end example + +This code is ambiguous; it could be a declaration of the variable +@samp{a} as a pointer to @samp{int}, or it could be a functional cast of +@samp{*a} to @samp{int}. Section 6.8 specifies that the former +interpretation is correct. This ambiguity results in 7 reduce/reduce +conflicts. Another aspect of this ambiguity is code like 'int (x[2]);', +which is resolved at the '[' and accounts for 6 reduce/reduce conflicts +between @samp{direct_notype_declarator} and +@samp{primary}/@samp{overqualified_id}. Finally, there are 4 r/r +conflicts between @samp{expr_or_declarator} and @samp{primary} over code +like 'int (a);', which could probably be resolved but would also +probably be more trouble than it's worth. In all, this situation +accounts for 17 conflicts. Ack! + +The second case above is responsible for the failure to parse 'LinppFile +ppfile (String (argv[1]), &outs, argc, argv);' (from Rogue Wave +Math.h++) as an object declaration, and must be fixed so that it does +not resolve until later. + +4) Indirectly between @code{after_type_declarator} and @code{parm}, for +type names. This occurs in (as one example) code like + +@example +typedef int foo, bar; +class A @{ + foo (bar); +@}; +@end example + +What is @code{bar} inside the class definition? We currently interpret +it as a @code{parm}, as does Cfront, but IBM xlC interprets it as an +@code{after_type_declarator}. I believe that xlC is correct, in light +of 7.1p2, which says "The longest sequence of @i{decl-specifiers} that +could possibly be a type name is taken as the @i{decl-specifier-seq} of +a @i{declaration}." However, it seems clear that this rule must be +violated in the case of constructors. This ambiguity accounts for 8 +conflicts. + +Unlike the others, this ambiguity is not recognized by the Working Paper. + +@node Copying Objects, Exception Handling, Parser, Top +@section Copying Objects + +The generated copy assignment operator in g++ does not currently do the +right thing for multiple inheritance involving virtual bases; it just +calls the copy assignment operators for its direct bases. What it +should probably do is: + +1) Split up the copy assignment operator for all classes that have +vbases into "copy my vbases" and "copy everything else" parts. Or do +the trickiness that the constructors do to ensure that vbases don't get +initialized by intermediate bases. + +2) Wander through the class lattice, find all vbases for which no +intermediate base has a user-defined copy assignment operator, and call +their "copy everything else" routines. If not all of my vbases satisfy +this criterion, warn, because this may be surprising behavior. + +3) Call the "copy everything else" routine for my direct bases. + +If we only have one direct base, we can just foist everything off onto +them. + +This issue is currently under discussion in the core reflector +(2/28/94). + +@node Exception Handling, Free Store, Copying Objects, Top +@section Exception Handling + +Note, exception handling in g++ is still under development. + +This section describes the mapping of C++ exceptions in the C++ +front-end, into the back-end exception handling framework. + +The basic mechanism of exception handling in the back-end is +unwind-protect a la elisp. This is a general, robust, and language +independent representation for exceptions. + +The C++ front-end exceptions are mapping into the unwind-protect +semantics by the C++ front-end. The mapping is describe below. + +Objects with RTTI support should use the RTTI information to do mapping +and checking. Objects without RTTI, like int and const char *, have to +use another means of matching. Currently we use the normal mangling used in +building functions names. Int's are "i", const char * is PCc, etc... + +Unfortunately, the standard allows standard type conversions on throw +parameters so they can match catch handlers. This means we need a +mechanism to handle type conversion at run time, ICK. I read this part +again, and it appears that we only have to be able to do a few of the +conversions at run time, so we should be ok. + +In C++, all cleanups should be protected by exception regions. The +region starts just after the reason why the cleanup is created has +ended. For example, with an automatic variable, that has a constructor, +it would be right after the constructor is run. The region ends just +before the finalization is expanded. Since the backend may expand the +cleanup multiple times along different paths, once for normal end of the +region, once for non-local gotos, once for returns, etc, the backend +must take special care to protect the finalization expansion, if the +expansion is for any other reason than normal region end, and it is +`inline' (it is inside the exception region). The backend can either +choose to move them out of line, or it can created an exception region +over the finalization to protect it, and in the handler associated with +it, it would not run the finalization as it otherwise would have, but +rather just rethrow to the outer handler, careful to skip the normal +handler for the original region. + +In Ada, they will use the more runtime intensive approach of having +fewer regions, but at the cost of additional work at run time, to keep a +list of things that need cleanups. When a variable has finished +construction, they add the cleanup to the list, when the come to the end +of the lifetime of the variable, the run the list down. If the take a +hit before the section finishes normally, they examine the list for +actions to perform. I hope they add this logic into the back-end, as it +would be nice to get that alternative approach in C++. + +On an rs6000, xlC stores exception objects on that stack, under the try +block. When is unwinds down into a handler, the frame pointer is +adjusted back to the normal value for the frame in which the handler +resides, and the stack pointer is left unchanged from the time at which +the object was throwed. This is so that there is always someplace for +the exception object, and nothing can overwrite it, once we start +throwing. The only bad part, is that the stack remains large. + +Flaws in g++'s exception handling. The stack pointer is restored from +stack, we want to match rs6000, and propagate the stack pointer from +time of throw, down, to the catch place. + +Only exact type matching of throw types works (references work also), +catch variables cannot be used. Only works on a Sun sparc running SunOS +4.1.x. Unwinding to outer catch clauses works. All temps and local +variables are cleaned up in all unwinded scopes. Completed parts of +partially constructed objects are not cleaned up. Don't expect +exception handling to work right if you optimize, in fact the compiler +will probably core dump. If two EH regions are the exact same size, the +backend cannot tell which one is first. It punts by picking the last +one, if they tie. This is usually right. We really should stick in a +nop, if they are the same size. + +If we fall off the end of a series of catch blocks, we return to the +flow of control in a normal fasion. But this is wrong, we should +rethrow. + +When we invoke the copy constructor for an exception object because it +is passed by value, and if we take a hit (exception) inside the copy +constructor someplace, where do we go? I have tentatively choosen to +not catch throws by the outer block at the same unwind level, if one +exists, but rather to allow the frame to unwind into the next series of +handlers, if any. If this is the wrong way to do it, we will need to +protect the rest of the handler in some fashion. Maybe just changing +the handler's handler to protect the whole series of handlers is the +right way to go. + +The EH object is copied like it should be, if it is passed by value, +otherwise we get a reference directly to it. + +EH objects make it through unwinding, but are subject to being +overwritten as they are still past the top of stack. Don't throw +automatic objects if this is a problem. + +Exceptions in catch handlers now go to outer block. + +@node Free Store, Concept Index, Exception Handling, Top +@section Free Store + +operator new [] adds a magic cookie to the beginning of arrays for which +the number of elements will be needed by operator delete []. These are +arrays of objects with destructors and arrays of objects that define +operator delete [] with the optional size_t argument. This cookie can +be examined from a program as follows: + +@example +typedef unsigned long size_t; +extern "C" int printf (const char *, ...); + +size_t nelts (void *p) +@{ + struct cookie @{ + size_t nelts __attribute__ ((aligned (sizeof (double)))); + @}; + + cookie *cp = (cookie *)p; + --cp; + + return cp->nelts; +@} + +struct A @{ + ~A() @{ @} +@}; + +main() +@{ + A *ap = new A[3]; + printf ("%ld\n", nelts (ap)); +@} +@end example + +@node Concept Index, , Free Store, Top +@section Concept Index + +@printindex cp + +@bye diff --git a/gnu/usr.bin/cc/doc/install.texi b/gnu/usr.bin/cc/doc/install.texi new file mode 100644 index 0000000..4a4813e --- /dev/null +++ b/gnu/usr.bin/cc/doc/install.texi @@ -0,0 +1,2086 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@c The text of this file appears in the file INSTALL +@c in the GCC distribution, as well as in the GCC manual. + +@ifclear INSTALLONLY +@node Installation +@chapter Installing GNU CC +@end ifclear +@cindex installing GNU CC + +@menu +* Configurations:: Configurations Supported by GNU CC. +* Other Dir:: Compiling in a separate directory (not where the source is). +* Cross-Compiler:: Building and installing a cross-compiler. +* Sun Install:: See below for installation on the Sun. +* VMS Install:: See below for installation on VMS. +* Collect2:: How @code{collect2} works; how it finds @code{ld}. +* Header Dirs:: Understanding the standard header file directories. +@end menu + +Here is the procedure for installing GNU CC on a Unix system. See +@ref{VMS Install}, for VMS systems. In this section we assume you +compile in the same directory that contains the source files; see +@ref{Other Dir}, to find out how to compile in a separate directory on Unix +systems. + +You cannot install GNU C by itself on MSDOS; it will not compile under +any MSDOS compiler except itself. You need to get the complete +compilation package DJGPP, which includes binaries as well as sources, +and includes all the necessary compilation tools and libraries. + +@enumerate +@item +If you have built GNU CC previously in the same directory for a +different target machine, do @samp{make distclean} to delete all files +that might be invalid. One of the files this deletes is +@file{Makefile}; if @samp{make distclean} complains that @file{Makefile} +does not exist, it probably means that the directory is already suitably +clean. + +@item +On a System V release 4 system, make sure @file{/usr/bin} precedes +@file{/usr/ucb} in @code{PATH}. The @code{cc} command in +@file{/usr/ucb} uses libraries which have bugs. + +@item +Specify the host, build and target machine configurations. You do this +by running the file @file{configure}. + +The @dfn{build} machine is the system which you are using, the +@dfn{host} machine is the system where you want to run the resulting +compiler (normally the build machine), and the @dfn{target} machine is +the system for which you want the compiler to generate code. + +If you are building a compiler to produce code for the machine it runs +on (a native compiler), you normally do not need to specify any operands +to @file{configure}; it will try to guess the type of machine you are on +and use that as the build, host and target machines. So you don't need +to specify a configuration when building a native compiler unless +@file{configure} cannot figure out what your configuration is or guesses +wrong. + +In those cases, specify the build machine's @dfn{configuration name} +with the @samp{--build} option; the host and target will default to be +the same as the build machine. (If you are building a cross-compiler, +see @ref{Cross-Compiler}.) + +Here is an example: + +@smallexample +./configure --build=sparc-sun-sunos4.1 +@end smallexample + +A configuration name may be canonical or it may be more or less +abbreviated. + +A canonical configuration name has three parts, separated by dashes. +It looks like this: @samp{@var{cpu}-@var{company}-@var{system}}. +(The three parts may themselves contain dashes; @file{configure} +can figure out which dashes serve which purpose.) For example, +@samp{m68k-sun-sunos4.1} specifies a Sun 3. + +You can also replace parts of the configuration by nicknames or aliases. +For example, @samp{sun3} stands for @samp{m68k-sun}, so +@samp{sun3-sunos4.1} is another way to specify a Sun 3. You can also +use simply @samp{sun3-sunos}, since the version of SunOS is assumed by +default to be version 4. @samp{sun3-bsd} also works, since +@file{configure} knows that the only BSD variant on a Sun 3 is SunOS. + +You can specify a version number after any of the system types, and some +of the CPU types. In most cases, the version is irrelevant, and will be +ignored. So you might as well specify the version if you know it. + +See @ref{Configurations}, for a list of supported configuration names and +notes on many of the configurations. You should check the notes in that +section before proceding any further with the installation of GNU CC. + +There are four additional options you can specify independently to +describe variant hardware and software configurations. These are +@samp{--with-gnu-as}, @samp{--with-gnu-ld}, @samp{--with-stabs} and +@samp{--nfp}. + +@table @samp +@item --with-gnu-as +If you will use GNU CC with the GNU assembler (GAS), you should declare +this by using the @samp{--with-gnu-as} option when you run +@file{configure}. + +Using this option does not install GAS. It only modifies the output of +GNU CC to work with GAS. Building and installing GAS is up to you. + +Conversely, if you @emph{do not} wish to use GAS and do not specify +@samp{--with-gnu-as} when building GNU CC, it is up to you to make sure +that GAS is not installed. GNU CC searches for a program named +@code{as} in various directories; if the program it finds is GAS, then +it runs GAS. If you are not sure where GNU CC finds the assembler it is +using, try specifying @samp{-v} when you run it. + +The systems where it makes a difference whether you use GAS are@* +@samp{hppa1.0-@var{any}-@var{any}}, @samp{hppa1.1-@var{any}-@var{any}}, +@samp{i386-@var{any}-sysv}, @samp{i386-@var{any}-isc},@* +@samp{i860-@var{any}-bsd}, @samp{m68k-bull-sysv}, @samp{m68k-hp-hpux}, +@samp{m68k-sony-bsd},@* +@samp{m68k-altos-sysv}, @samp{m68000-hp-hpux}, @samp{m68000-att-sysv}, +and @samp{mips-@var{any}}). On any other system, @samp{--with-gnu-as} +has no effect. + +On the systems listed above (except for the HP-PA, for ISC on the +386, and for @samp{mips-sgi-irix5.*}), if you use GAS, you should also +use the GNU linker (and specify @samp{--with-gnu-ld}). + +@item --with-gnu-ld +Specify the option @samp{--with-gnu-ld} if you plan to use the GNU +linker with GNU CC. + +This option does not cause the GNU linker to be installed; it just +modifies the behavior of GNU CC to work with the GNU linker. +Specifically, it inhibits the installation of @code{collect2}, a program +which otherwise serves as a front-end for the system's linker on most +configurations. + +@item --with-stabs +On MIPS based systems and on Alphas, you must specify whether you want +GNU CC to create the normal ECOFF debugging format, or to use BSD-style +stabs passed through the ECOFF symbol table. The normal ECOFF debug +format cannot fully handle languages other than C. BSD stabs format can +handle other languages, but it only works with the GNU debugger GDB. + +Normally, GNU CC uses the ECOFF debugging format by default; if you +prefer BSD stabs, specify @samp{--with-stabs} when you configure GNU +CC. + +No matter which default you choose when you configure GNU CC, the user +can use the @samp{-gcoff} and @samp{-gstabs+} options to specify explicitly +the debug format for a particular compilation. + +@samp{--with-stabs} is meaningful on the ISC system on the 386, also, if +@samp{--with-gas} is used. It selects use of stabs debugging +information embedded in COFF output. This kind of debugging information +supports C++ well; ordinary COFF debugging information does not. + +@samp{--with-stabs} is also meaningful on 386 systems running SVR4. It +selects use of stabs debugging information embedded in ELF output. The +C++ compiler currently (2.6.0) does not support the DWARF debugging +information normally used on 386 SVR4 platforms; stabs provide a +workable alternative. This requires gas and gdb, as the normal SVR4 +tools can not generate or interpret stabs. + +@item --nfp +On certain systems, you must specify whether the machine has a floating +point unit. These systems include @samp{m68k-sun-sunos@var{n}} and +@samp{m68k-isi-bsd}. On any other system, @samp{--nfp} currently has no +effect, though perhaps there are other systems where it could usefully +make a difference. +@end table + +The @file{configure} script searches subdirectories of the source +directory for other compilers that are to be integrated into GNU CC. +The GNU compiler for C++, called G++ is in a subdirectory named +@file{cp}. @file{configure} inserts rules into @file{Makefile} to build +all of those compilers. + +Here we spell out what files will be set up by @code{configure}. Normally +you need not be concerned with these files. + +@itemize @bullet +@item +@ifset INTERNALS +A symbolic link named @file{config.h} is made to the top-level config +file for the machine you will run the compiler on (@pxref{Config}). +This file is responsible for defining information about the host +machine. It includes @file{tm.h}. +@end ifset +@ifclear INTERNALS +A symbolic link named @file{config.h} is made to the top-level config +file for the machine you plan to run the compiler on (@pxref{Config,,The +Configuration File, gcc.info, Using and Porting GCC}). This file is +responsible for defining information about the host machine. It +includes @file{tm.h}. +@end ifclear + +The top-level config file is located in the subdirectory @file{config}. +Its name is always @file{xm-@var{something}.h}; usually +@file{xm-@var{machine}.h}, but there are some exceptions. + +If your system does not support symbolic links, you might want to +set up @file{config.h} to contain a @samp{#include} command which +refers to the appropriate file. + +@item +A symbolic link named @file{tconfig.h} is made to the top-level config +file for your target machine. This is used for compiling certain +programs to run on that machine. + +@item +A symbolic link named @file{tm.h} is made to the machine-description +macro file for your target machine. It should be in the subdirectory +@file{config} and its name is often @file{@var{machine}.h}. + +@item +A symbolic link named @file{md} will be made to the machine description +pattern file. It should be in the @file{config} subdirectory and its +name should be @file{@var{machine}.md}; but @var{machine} is often not +the same as the name used in the @file{tm.h} file because the +@file{md} files are more general. + +@item +A symbolic link named @file{aux-output.c} will be made to the output +subroutine file for your machine. It should be in the @file{config} +subdirectory and its name should be @file{@var{machine}.c}. + +@item +The command file @file{configure} also constructs the file +@file{Makefile} by adding some text to the template file +@file{Makefile.in}. The additional text comes from files in the +@file{config} directory, named @file{t-@var{target}} and +@file{x-@var{host}}. If these files do not exist, it means nothing +needs to be added for a given target or host. +@c does the above work now? --mew +@end itemize + +@item +The standard directory for installing GNU CC is @file{/usr/local/lib}. +If you want to install its files somewhere else, specify +@samp{--prefix=@var{dir}} when you run @file{configure}. Here @var{dir} +is a directory name to use instead of @file{/usr/local} for all purposes +with one exception: the directory @file{/usr/local/include} is searched +for header files no matter where you install the compiler. To override +this name, use the @code{--local-prefix} option below. + +@item +Specify @samp{--local-prefix=@var{dir}} if you want the compiler to +search directory @file{@var{dir}/include} for locally installed header +files @emph{instead} of @file{/usr/local/include}. + +You should specify @samp{--local-prefix} @strong{only} if your site has +a different convention (not @file{/usr/local}) for where to put +site-specific files. + +@strong{Do not} specify @file{/usr} as the @samp{--local-prefix}! The +directory you use for @samp{--local-prefix} @strong{must not} contain +any of the system's standard header files. If it did contain them, +certain programs would be miscompiled (including GNU Emacs, on certain +targets), because this would override and nullify the header file +corrections made by the @code{fixincludes} script. + +@cindex Bison parser generator +@cindex parser generator, Bison +@item +Make sure the Bison parser generator is installed. (This is +unnecessary if the Bison output files @file{c-parse.c} and +@file{cexp.c} are more recent than @file{c-parse.y} and @file{cexp.y} +and you do not plan to change the @samp{.y} files.) + +Bison versions older than Sept 8, 1988 will produce incorrect output +for @file{c-parse.c}. + +@item +If you have chosen a configuration for GNU CC which requires other GNU +tools (such as GAS or the GNU linker) instead of the standard system +tools, install the required tools in the build directory under the names +@file{as}, @file{ld} or whatever is appropriate. This will enable the +compiler to find the proper tools for compilation of the program +@file{enquire}. + +Alternatively, you can do subsequent compilation using a value of the +@code{PATH} environment variable such that the necessary GNU tools come +before the standard system tools. + +@item +Build the compiler. Just type @samp{make LANGUAGES=c} in the compiler +directory. + +@samp{LANGUAGES=c} specifies that only the C compiler should be +compiled. The makefile normally builds compilers for all the supported +languages; currently, C, C++ and Objective C. However, C is the only +language that is sure to work when you build with other non-GNU C +compilers. In addition, building anything but C at this stage is a +waste of time. + +In general, you can specify the languages to build by typing the +argument @samp{LANGUAGES="@var{list}"}, where @var{list} is one or more +words from the list @samp{c}, @samp{c++}, and @samp{objective-c}. If +you have any additional GNU compilers as subdirectories of the GNU CC +source directory, you may also specify their names in this list. + +Ignore any warnings you may see about ``statement not reached'' in +@file{insn-emit.c}; they are normal. Also, warnings about ``unknown +escape sequence'' are normal in @file{genopinit.c} and perhaps some +other files. Likewise, you should ignore warnings about ``constant is +so large that it is unsigned'' in @file{insn-emit.c} and +@file{insn-recog.c}. Any other compilation errors may represent bugs in +the port to your machine or operating system, and +@ifclear INSTALLONLY +should be investigated and reported (@pxref{Bugs}). +@end ifclear +@ifset INSTALLONLY +should be investigated and reported. +@end ifset + +Some commercial compilers fail to compile GNU CC because they have bugs +or limitations. For example, the Microsoft compiler is said to run out +of macro space. Some Ultrix compilers run out of expression space; then +you need to break up the statement where the problem happens. + +@item +If you are building a cross-compiler, stop here. @xref{Cross-Compiler}. + +@cindex stage1 +@item +Move the first-stage object files and executables into a subdirectory +with this command: + +@smallexample +make stage1 +@end smallexample + +The files are moved into a subdirectory named @file{stage1}. +Once installation is complete, you may wish to delete these files +with @code{rm -r stage1}. + +@item +If you have chosen a configuration for GNU CC which requires other GNU +tools (such as GAS or the GNU linker) instead of the standard system +tools, install the required tools in the @file{stage1} subdirectory +under the names @file{as}, @file{ld} or whatever is appropriate. This +will enable the stage 1 compiler to find the proper tools in the +following stage. + +Alternatively, you can do subsequent compilation using a value of the +@code{PATH} environment variable such that the necessary GNU tools come +before the standard system tools. + +@item +Recompile the compiler with itself, with this command: + +@smallexample +make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O" +@end smallexample + +This is called making the stage 2 compiler. + +The command shown above builds compilers for all the supported +languages. If you don't want them all, you can specify the languages to +build by typing the argument @samp{LANGUAGES="@var{list}"}. @var{list} +should contain one or more words from the list @samp{c}, @samp{c++}, +@samp{objective-c}, and @samp{proto}. Separate the words with spaces. +@samp{proto} stands for the programs @code{protoize} and +@code{unprotoize}; they are not a separate language, but you use +@code{LANGUAGES} to enable or disable their installation. + +If you are going to build the stage 3 compiler, then you might want to +build only the C language in stage 2. + +Once you have built the stage 2 compiler, if you are short of disk +space, you can delete the subdirectory @file{stage1}. + +On a 68000 or 68020 system lacking floating point hardware, +unless you have selected a @file{tm.h} file that expects by default +that there is no such hardware, do this instead: + +@smallexample +make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O -msoft-float" +@end smallexample + +@item +If you wish to test the compiler by compiling it with itself one more +time, install any other necessary GNU tools (such as GAS or the GNU +linker) in the @file{stage2} subdirectory as you did in the +@file{stage1} subdirectory, then do this: + +@smallexample +make stage2 +make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" +@end smallexample + +@noindent +This is called making the stage 3 compiler. Aside from the @samp{-B} +option, the compiler options should be the same as when you made the +stage 2 compiler. But the @code{LANGUAGES} option need not be the +same. The command shown above builds compilers for all the supported +languages; if you don't want them all, you can specify the languages to +build by typing the argument @samp{LANGUAGES="@var{list}"}, as described +above. + +If you do not have to install any additional GNU tools, you may use the +command + +@smallexample +make bootstrap LANGUAGES=@var{language-list} BOOT_CFLAGS=@var{option-list} +@end smallexample + +@noindent +instead of making @file{stage1}, @file{stage2}, and performing +the two compiler builds. + +@item +Then compare the latest object files with the stage 2 object +files---they ought to be identical, aside from time stamps (if any). + +On some systems, meaningful comparison of object files is impossible; +they always appear ``different.'' This is currently true on Solaris and +probably on all systems that use ELF object file format. On some +versions of Irix on SGI machines and OSF/1 on Alpha systems, you will +not be able to compare the files without specifying @file{-save-temps}; +see the description of individual systems above to see if you get +comparison failures. You may have similar problems on other systems. + +Use this command to compare the files: + +@smallexample +make compare +@end smallexample + +This will mention any object files that differ between stage 2 and stage +3. Any difference, no matter how innocuous, indicates that the stage 2 +compiler has compiled GNU CC incorrectly, and is therefore a potentially +@ifclear INSTALLONLY +serious bug which you should investigate and report (@pxref{Bugs}). +@end ifclear +@ifset INSTALLONLY +serious bug which you should investigate and report. +@end ifset + +If your system does not put time stamps in the object files, then this +is a faster way to compare them (using the Bourne shell): + +@smallexample +for file in *.o; do +cmp $file stage2/$file +done +@end smallexample + +If you have built the compiler with the @samp{-mno-mips-tfile} option on +MIPS machines, you will not be able to compare the files. + +@item +Build the Objective C library (if you have built the Objective C +compiler). Here is the command to do this: + +@smallexample +make objc-runtime CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" +@end smallexample + +@item +Install the compiler driver, the compiler's passes and run-time support +with @samp{make install}. Use the same value for @code{CC}, +@code{CFLAGS} and @code{LANGUAGES} that you used when compiling the +files that are being installed. One reason this is necessary is that +some versions of Make have bugs and recompile files gratuitously when +you do this step. If you use the same variable values, those files will +be recompiled properly. + +For example, if you have built the stage 2 compiler, you can use the +following command: + +@smallexample +make install CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" LANGUAGES="@var{list}" +@end smallexample + +@noindent +This copies the files @file{cc1}, @file{cpp} and @file{libgcc.a} to +files @file{cc1}, @file{cpp} and @file{libgcc.a} in the directory +@file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}, which is where +the compiler driver program looks for them. Here @var{target} is the +target machine type specified when you ran @file{configure}, and +@var{version} is the version number of GNU CC. This naming scheme +permits various versions and/or cross-compilers to coexist. + +This also copies the driver program @file{xgcc} into +@file{/usr/local/bin/gcc}, so that it appears in typical execution +search paths. + +On some systems, this command causes recompilation of some files. This +is usually due to bugs in @code{make}. You should either ignore this +problem, or use GNU Make. + +@cindex @code{alloca} and SunOs +@strong{Warning: there is a bug in @code{alloca} in the Sun library. To +avoid this bug, be sure to install the executables of GNU CC that were +compiled by GNU CC. (That is, the executables from stage 2 or 3, not +stage 1.) They use @code{alloca} as a built-in function and never the +one in the library.} + +(It is usually better to install GNU CC executables from stage 2 or 3, +since they usually run faster than the ones compiled with some other +compiler.) + +@item +Install the Objective C library (if you are installing the Objective C +compiler). Here is the command to do this: + +@smallexample +make install-libobjc CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" +@end smallexample + +@item +If you're going to use C++, it's likely that you need to also install +the libg++ distribution. It should be available from the same +place where you got the GNU C distribution. Just as GNU C does not +distribute a C runtime library, it also does not include a C++ run-time +library. All I/O functionality, special class libraries, etc., are +available in the libg++ distribution. +@end enumerate + +@node Configurations +@section Configurations Supported by GNU CC +@cindex configurations supported by GNU CC + +Here are the possible CPU types: + +@quotation +@c gmicro, alliant, spur and tahoe omitted since they don't work. +1750a, a29k, alpha, arm, c@var{n}, clipper, dsp16xx, elxsi, h8300, +hppa1.0, hppa1.1, i370, i386, i486, i860, i960, m68000, m68k, m88k, +mips, ns32k, pyramid, romp, rs6000, sh, sparc, sparclite, sparc64, vax, +we32k. +@end quotation + +Here are the recognized company names. As you can see, customary +abbreviations are used rather than the longer official names. + +@c What should be done about merlin, tek*, dolphin? +@quotation +acorn, alliant, altos, apollo, att, bull, +cbm, convergent, convex, crds, dec, dg, dolphin, +elxsi, encore, harris, hitachi, hp, ibm, intergraph, isi, +mips, motorola, ncr, next, ns, omron, plexus, +sequent, sgi, sony, sun, tti, unicom. +@end quotation + +The company name is meaningful only to disambiguate when the rest of +the information supplied is insufficient. You can omit it, writing +just @samp{@var{cpu}-@var{system}}, if it is not needed. For example, +@samp{vax-ultrix4.2} is equivalent to @samp{vax-dec-ultrix4.2}. + +Here is a list of system types: + +@quotation +386bsd, aix, acis, amigados, aos, aout, bosx, bsd, clix, ctix, cxux, +dgux, dynix, ebmon, elf, esix, freebsd, hms, genix, gnu, gnu/linux, +hiux, hpux, iris, irix, isc, luna, lynxos, mach, minix, msdos, mvs, +netbsd, newsos, nindy, ns, osf, osfrose, ptx, riscix, riscos, rtu, sco, +solaris, sunos, sym, sysv, ultrix, unicos, uniplus, unos, vms, vxworks, +xenix. +@end quotation + +@noindent +You can omit the system type; then @file{configure} guesses the +operating system from the CPU and company. + +You can add a version number to the system type; this may or may not +make a difference. For example, you can write @samp{bsd4.3} or +@samp{bsd4.4} to distinguish versions of BSD. In practice, the version +number is most needed for @samp{sysv3} and @samp{sysv4}, which are often +treated differently. + +If you specify an impossible combination such as @samp{i860-dg-vms}, +then you may get an error message from @file{configure}, or it may +ignore part of the information and do the best it can with the rest. +@file{configure} always prints the canonical name for the alternative +that it used. GNU CC does not support all possible alternatives. + +Often a particular model of machine has a name. Many machine names are +recognized as aliases for CPU/company combinations. Thus, the machine +name @samp{sun3}, mentioned above, is an alias for @samp{m68k-sun}. +Sometimes we accept a company name as a machine name, when the name is +popularly used for a particular machine. Here is a table of the known +machine names: + +@quotation +3300, 3b1, 3b@var{n}, 7300, altos3068, altos, +apollo68, att-7300, balance, +convex-c@var{n}, crds, decstation-3100, +decstation, delta, encore, +fx2800, gmicro, hp7@var{nn}, hp8@var{nn}, +hp9k2@var{nn}, hp9k3@var{nn}, hp9k7@var{nn}, +hp9k8@var{nn}, iris4d, iris, isi68, +m3230, magnum, merlin, miniframe, +mmax, news-3600, news800, news, next, +pbd, pc532, pmax, powerpc, ps2, risc-news, +rtpc, sun2, sun386i, sun386, sun3, +sun4, symmetry, tower-32, tower. +@end quotation + +@noindent +Remember that a machine name specifies both the cpu type and the company +name. +If you want to install your own homemade configuration files, you can +use @samp{local} as the company name to access them. If you use +configuration @samp{@var{cpu}-local}, the configuration name +without the cpu prefix +is used to form the configuration file names. + +Thus, if you specify @samp{m68k-local}, configuration uses +files @file{m68k.md}, @file{local.h}, @file{m68k.c}, +@file{xm-local.h}, @file{t-local}, and @file{x-local}, all in the +directory @file{config/m68k}. + +Here is a list of configurations that have special treatment or special +things you must know: + +@table @samp +@item 1750a-*-* +MIL-STD-1750A processors. + +Starting with GCC 2.6.1, the MIL-STD-1750A cross configuration no longer +supports the Tektronix Assembler, but instead produces output for +@code{as1750}, an assembler/linker available under the GNU Public +License for the 1750A. Contact @emph{okellogg@@salyko.cube.net} for more +details on obtaining @samp{as1750}. A similarly licensed simulator for +the 1750A is available from same address. + +You should ignore a fatal error during the building of libgcc (libgcc is +not yet implemented for the 1750A.) + +The @code{as1750} assembler requires the file @file{ms1750.inc}, which is +found in the directory @file{config/1750a}. + +GNU CC produced the same sections as the Fairchild F9450 C Compiler, +namely: + +@table @code +@item NREL +The program code section. + +@item SREL +The read/write (RAM) data section. + +@item KREL +The read-only (ROM) constants section. + +@item IREL +Initialization section (code to copy KREL to SREL). +@end table + +The smallest addressable unit is 16 bits (BITS_PER_UNIT is 16). This +means that type `char' is represented with a 16-bit word per character. +The 1750A's "Load/Store Upper/Lower Byte" instructions are not used by +GNU CC. + +There is a problem with long argument lists to functions. The compiler +aborts if the sum of space needed by all arguments exceeds 14 words. +This is because the arguments are passed in registers (R0..R13) not on +the stack, and there is a problem with passing further arguments (i.e. +beyond those in R0..R13) via the stack. + +If efficiency is less important than using long argument lists, you +can change the definition of the @code{FUNCTION_ARG} macro in +@file{config/1750/1750a.h} to always return zero. If you do that, +GNU CC will pass all parameters on the stack. + +@item alpha-*-osf1 +Systems using processors that implement the DEC Alpha architecture and +are running the OSF/1 operating system, for example the DEC Alpha AXP +systems. (VMS on the Alpha is not currently supported by GNU CC.) + +GNU CC writes a @samp{.verstamp} directive to the assembler output file +unless it is built as a cross-compiler. It gets the version to use from +the system header file @file{/usr/include/stamp.h}. If you install a +new version of OSF/1, you should rebuild GCC to pick up the new version +stamp. + +Note that since the Alpha is a 64-bit architecture, cross-compilers from +32-bit machines will not generate code as efficient as that generated +when the compiler is running on a 64-bit machine because many +optimizations that depend on being able to represent a word on the +target in an integral value on the host cannot be performed. Building +cross-compilers on the Alpha for 32-bit machines has only been tested in +a few cases and may not work properly. + +@code{make compare} may fail on old versions of OSF/1 unless you add +@samp{-save-temps} to @code{CFLAGS}. On these systems, the name of the +assembler input file is stored in the object file, and that makes +comparison fail if it differs between the @code{stage1} and +@code{stage2} compilations. The option @samp{-save-temps} forces a +fixed name to be used for the assembler input file, instead of a +randomly chosen name in @file{/tmp}. Do not add @samp{-save-temps} +unless the comparisons fail without that option. If you add +@samp{-save-temps}, you will have to manually delete the @samp{.i} and +@samp{.s} files after each series of compilations. + +GNU CC now supports both the native (ECOFF) debugging format used by DBX +and GDB and an encapsulated STABS format for use only with GDB. See the +discussion of the @samp{--with-stabs} option of @file{configure} above +for more information on these formats and how to select them. + +There is a bug in DEC's assembler that produces incorrect line numbers +for ECOFF format when the @samp{.align} directive is used. To work +around this problem, GNU CC will not emit such alignment directives +while writing ECOFF format debugging information even if optimization is +being performed. Unfortunately, this has the very undesirable +side-effect that code addresses when @samp{-O} is specified are +different depending on whether or not @samp{-g} is also specified. + +To avoid this behavior, specify @samp{-gstabs+} and use GDB instead of +DBX. DEC is now aware of this problem with the assembler and hopes to +provide a fix shortly. + +@item arm +Advanced RISC Machines ARM-family processors. These are often used in +embedded applications. There are no standard Unix configurations. +This configuration corresponds to the basic instruction sequences and will +produce a.out format object modules. + +You may need to make a variant of the file @file{arm.h} for your particular +configuration. + +@item arm-*-riscix +The ARM2 or ARM3 processor running RISC iX, Acorn's port of BSD Unix. If +you are running a version of RISC iX prior to 1.2 then you must specify +the version number during configuration. Note that the assembler +shipped with RISC iX does not support stabs debugging information; a +new version of the assembler, with stabs support included, is now +available from Acorn. + +@item a29k +AMD Am29k-family processors. These are normally used in embedded +applications. There are no standard Unix configurations. +This configuration +corresponds to AMD's standard calling sequence and binary interface +and is compatible with other 29k tools. + +You may need to make a variant of the file @file{a29k.h} for your +particular configuration. + +@item a29k-*-bsd +AMD Am29050 used in a system running a variant of BSD Unix. + +@item decstation-* +DECstations can support three different personalities: Ultrix, +DEC OSF/1, and OSF/rose. To configure GCC for these platforms +use the following configurations: + +@table @samp +@item decstation-ultrix +Ultrix configuration. + +@item decstation-osf1 +Dec's version of OSF/1. + +@item decstation-osfrose +Open Software Foundation reference port of OSF/1 which uses the +OSF/rose object file format instead of ECOFF. Normally, you +would not select this configuration. +@end table + +The MIPS C compiler needs to be told to increase its table size +for switch statements with the @samp{-Wf,-XNg1500} option in +order to compile @file{cp/parse.c}. If you use the @samp{-O2} +optimization option, you also need to use @samp{-Olimit 3000}. +Both of these options are automatically generated in the +@file{Makefile} that the shell script @file{configure} builds. +If you override the @code{CC} make variable and use the MIPS +compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}. + +@item elxsi-elxsi-bsd +The Elxsi's C compiler has known limitations that prevent it from +compiling GNU C. Please contact @code{mrs@@cygnus.com} for more details. + +@item dsp16xx +A port to the AT&T DSP1610 family of processors. + +@ignore +@item fx80 +Alliant FX/8 computer. Note that the standard installed C compiler in +Concentrix 5.0 has a bug which prevent it from compiling GNU CC +correctly. You can patch the compiler bug as follows: + +@smallexample +cp /bin/pcc ./pcc +adb -w ./pcc - << EOF +15f6?w 6610 +EOF +@end smallexample + +Then you must use the @samp{-ip12} option when compiling GNU CC +with the patched compiler, as shown here: + +@smallexample +make CC="./pcc -ip12" CFLAGS=-w +@end smallexample + +Note also that Alliant's version of DBX does not manage to work with the +output from GNU CC. +@end ignore + +@item h8300-*-* +The calling convention and structure layout has changed in release 2.6. +All code must be recompiled. The calling convention now passes the +first three arguments in function calls in registers. Structures are no +longer a multiple of 2 bytes. + +@item hppa*-*-* +There are two variants of this CPU, called 1.0 and 1.1, which have +different machine descriptions. You must use the right one for your +machine. All 7@var{nn} machines and 8@var{n}7 machines use 1.1, while +all other 8@var{nn} machines use 1.0. + +The easiest way to handle this problem is to use @samp{configure +hp@var{nnn}} or @samp{configure hp@var{nnn}-hpux}, where @var{nnn} is +the model number of the machine. Then @file{configure} will figure out +if the machine is a 1.0 or 1.1. Use @samp{uname -a} to find out the +model number of your machine. + +@samp{-g} does not work on HP-UX, since that system uses a peculiar +debugging format which GNU CC does not know about. However, @samp{-g} +will work if you also use GAS and GDB in conjunction with GCC. We +highly recommend using GAS for all HP-PA configurations. + +You should be using GAS-2.3 (or later) along with GDB-4.12 (or later). These +can be retrieved from all the traditional GNU ftp archive sites. + +Build GAS and install the resulting binary as: + +@example +/usr/local/lib/gcc-lib/@var{configuration}/@var{gccversion}/as +@end example + +@noindent +where @var{configuration} is the configuration name (perhaps +@samp{hp@var{nnn}-hpux}) and @var{gccversion} is the GNU CC version +number. Do this @emph{before} starting the build process, otherwise you will +get errors from the HPUX assembler while building @file{libgcc2.a}. The +command + +@example +make install-dir +@end example + +@noindent +will create the necessary directory hierarchy so you can install GAS before +building GCC. + +To enable debugging, configure GNU CC with the @samp{--with-gnu-as} option +before building. + +It has been reported that GNU CC produces invalid assembly code for +1.1 machines running HP-UX 8.02 when using the HP assembler. Typically +the errors look like this: +@example +as: bug.s @@line#15 [err#1060] + Argument 0 or 2 in FARG upper + - lookahead = ARGW1=FR,RTNVAL=GR +as: foo.s @@line#28 [err#1060] + Argument 0 or 2 in FARG upper + - lookahead = ARGW1=FR +@end example + +You can check the version of HP-UX you are running by executing the command +@samp{uname -r}. If you are indeed running HP-UX 8.02 on a PA and +using the HP assembler then configure GCC with "hp@var{nnn}-hpux8.02". + +@item i370-*-* +This port is very preliminary and has many known bugs. We hope to +have a higher-quality port for this machine soon. + +@item i386-*-gnu/linux +Bash-1.12 has a bug that causes configure to fail. The symptom is that +the c++ subdirectory, @file{cp}, is not configured. Bash-1.14 and later +work fine. + +@item i386-*-sco +Compilation with RCC is recommended. Also, it may be a good idea to +link with GNU malloc instead of the malloc that comes with the system. + +@item i386-*-sco3.2.4 +Use this configuration for SCO release 3.2 version 4. + +@item i386-*-isc +It may be a good idea to link with GNU malloc instead of the malloc that +comes with the system. + +In ISC version 4.1, @file{sed} core dumps when building +@file{deduced.h}. Use the version of @file{sed} from version 4.0. + +@item i386-*-esix +It may be good idea to link with GNU malloc instead of the malloc that +comes with the system. + +@item i386-ibm-aix +You need to use GAS version 2.1 or later, and and LD from +GNU binutils version 2.2 or later. + +@item i386-sequent-bsd +Go to the Berkeley universe before compiling. In addition, you probably +need to create a file named @file{string.h} containing just one line: +@samp{#include <strings.h>}. + +@item i386-sequent-ptx1* +Sequent DYNIX/ptx 1.x. + +@item i386-sequent-ptx2* +Sequent DYNIX/ptx 2.x. + +@item i386-sun-sunos4 +You may find that you need another version of GNU CC to begin +bootstrapping with, since the current version when built with the +system's own compiler seems to get an infinite loop compiling part of +@file{libgcc2.c}. GNU CC version 2 compiled with GNU CC (any version) +seems not to have this problem. + +See @ref{Sun Install}, for information on installing GNU CC on Sun +systems. + +@item i860-intel-osf1 +This is the Paragon. +@ifset INSTALLONLY +If you have version 1.0 of the operating system, you need to take +special steps to build GNU CC due to peculiarities of the system. Newer +system versions have no problem. See the section `Installation Problems' +in the GNU CC Manual. +@end ifset +@ifclear INSTALLONLY +If you have version 1.0 of the operating system, +see @ref{Installation Problems}, for special things you need to do to +compensate for peculiarities in the system. +@end ifclear + +@item m68000-hp-bsd +HP 9000 series 200 running BSD. Note that the C compiler that comes +with this system cannot compile GNU CC; contact @code{law@@cs.utah.edu} +to get binaries of GNU CC for bootstrapping. + +@item m68k-altos +Altos 3068. You must use the GNU assembler, linker and debugger. +Also, you must fix a kernel bug. Details in the file @file{README.ALTOS}. + +@item m68k-att-sysv +AT&T 3b1, a.k.a. 7300 PC. Special procedures are needed to compile GNU +CC with this machine's standard C compiler, due to bugs in that +compiler. You can bootstrap it more easily with +previous versions of GNU CC if you have them. + +Installing GNU CC on the 3b1 is difficult if you do not already have +GNU CC running, due to bugs in the installed C compiler. However, +the following procedure might work. We are unable to test it. + +@enumerate +@item +Comment out the @samp{#include "config.h"} line on line 37 of +@file{cccp.c} and do @samp{make cpp}. This makes a preliminary version +of GNU cpp. + +@item +Save the old @file{/lib/cpp} and copy the preliminary GNU cpp to that +file name. + +@item +Undo your change in @file{cccp.c}, or reinstall the original version, +and do @samp{make cpp} again. + +@item +Copy this final version of GNU cpp into @file{/lib/cpp}. + +@findex obstack_free +@item +Replace every occurrence of @code{obstack_free} in the file +@file{tree.c} with @code{_obstack_free}. + +@item +Run @code{make} to get the first-stage GNU CC. + +@item +Reinstall the original version of @file{/lib/cpp}. + +@item +Now you can compile GNU CC with itself and install it in the normal +fashion. +@end enumerate + +@item m68k-bull-sysv +Bull DPX/2 series 200 and 300 with BOS-2.00.45 up to BOS-2.01. GNU CC works +either with native assembler or GNU assembler. You can use +GNU assembler with native coff generation by providing @samp{--with-gnu-as} to +the configure script or use GNU assembler with dbx-in-coff encapsulation +by providing @samp{--with-gnu-as --stabs}. For any problem with native +assembler or for availability of the DPX/2 port of GAS, contact +@code{F.Pierresteguy@@frcl.bull.fr}. + +@item m68k-crds-unox +Use @samp{configure unos} for building on Unos. + +The Unos assembler is named @code{casm} instead of @code{as}. For some +strange reason linking @file{/bin/as} to @file{/bin/casm} changes the +behavior, and does not work. So, when installing GNU CC, you should +install the following script as @file{as} in the subdirectory where +the passes of GCC are installed: + +@example +#!/bin/sh +casm $* +@end example + +The default Unos library is named @file{libunos.a} instead of +@file{libc.a}. To allow GNU CC to function, either change all +references to @samp{-lc} in @file{gcc.c} to @samp{-lunos} or link +@file{/lib/libc.a} to @file{/lib/libunos.a}. + +@cindex @code{alloca}, for Unos +When compiling GNU CC with the standard compiler, to overcome bugs in +the support of @code{alloca}, do not use @samp{-O} when making stage 2. +Then use the stage 2 compiler with @samp{-O} to make the stage 3 +compiler. This compiler will have the same characteristics as the usual +stage 2 compiler on other systems. Use it to make a stage 4 compiler +and compare that with stage 3 to verify proper compilation. + +(Perhaps simply defining @code{ALLOCA} in @file{x-crds} as described in +the comments there will make the above paragraph superfluous. Please +inform us of whether this works.) + +Unos uses memory segmentation instead of demand paging, so you will need +a lot of memory. 5 Mb is barely enough if no other tasks are running. +If linking @file{cc1} fails, try putting the object files into a library +and linking from that library. + +@item m68k-hp-hpux +HP 9000 series 300 or 400 running HP-UX. HP-UX version 8.0 has a bug in +the assembler that prevents compilation of GNU CC. To fix it, get patch +PHCO_4484 from HP. + +In addition, if you wish to use gas @samp{--with-gnu-as} you must use +gas version 2.1 or later, and you must use the GNU linker version 2.1 or +later. Earlier versions of gas relied upon a program which converted the +gas output into the native HP/UX format, but that program has not been +kept up to date. gdb does not understand that native HP/UX format, so +you must use gas if you wish to use gdb. + +@item m68k-sun +Sun 3. We do not provide a configuration file to use the Sun FPA by +default, because programs that establish signal handlers for floating +point traps inherently cannot work with the FPA. + +See @ref{Sun Install}, for information on installing GNU CC on Sun +systems. + +@item m88k-*-svr3 +Motorola m88k running the AT&T/Unisoft/Motorola V.3 reference port. +These systems tend to use the Green Hills C, revision 1.8.5, as the +standard C compiler. There are apparently bugs in this compiler that +result in object files differences between stage 2 and stage 3. If this +happens, make the stage 4 compiler and compare it to the stage 3 +compiler. If the stage 3 and stage 4 object files are identical, this +suggests you encountered a problem with the standard C compiler; the +stage 3 and 4 compilers may be usable. + +It is best, however, to use an older version of GNU CC for bootstrapping +if you have one. + +@item m88k-*-dgux +Motorola m88k running DG/UX. To build 88open BCS native or cross +compilers on DG/UX, specify the configuration name as +@samp{m88k-*-dguxbcs} and build in the 88open BCS software development +environment. To build ELF native or cross compilers on DG/UX, specify +@samp{m88k-*-dgux} and build in the DG/UX ELF development environment. +You set the software development environment by issuing +@samp{sde-target} command and specifying either @samp{m88kbcs} or +@samp{m88kdguxelf} as the operand. + +If you do not specify a configuration name, @file{configure} guesses the +configuration based on the current software development environment. + +@item m88k-tektronix-sysv3 +Tektronix XD88 running UTekV 3.2e. Do not turn on +optimization while building stage1 if you bootstrap with +the buggy Green Hills compiler. Also, The bundled LAI +System V NFS is buggy so if you build in an NFS mounted +directory, start from a fresh reboot, or avoid NFS all together. +Otherwise you may have trouble getting clean comparisons +between stages. + +@item mips-mips-bsd +MIPS machines running the MIPS operating system in BSD mode. It's +possible that some old versions of the system lack the functions +@code{memcpy}, @code{memcmp}, and @code{memset}. If your system lacks +these, you must remove or undo the definition of +@code{TARGET_MEM_FUNCTIONS} in @file{mips-bsd.h}. + +The MIPS C compiler needs to be told to increase its table size +for switch statements with the @samp{-Wf,-XNg1500} option in +order to compile @file{cp/parse.c}. If you use the @samp{-O2} +optimization option, you also need to use @samp{-Olimit 3000}. +Both of these options are automatically generated in the +@file{Makefile} that the shell script @file{configure} builds. +If you override the @code{CC} make variable and use the MIPS +compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}. + +@item mips-mips-riscos* +The MIPS C compiler needs to be told to increase its table size +for switch statements with the @samp{-Wf,-XNg1500} option in +order to compile @file{cp/parse.c}. If you use the @samp{-O2} +optimization option, you also need to use @samp{-Olimit 3000}. +Both of these options are automatically generated in the +@file{Makefile} that the shell script @file{configure} builds. +If you override the @code{CC} make variable and use the MIPS +compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}. + +MIPS computers running RISC-OS can support four different +personalities: default, BSD 4.3, System V.3, and System V.4 +(older versions of RISC-OS don't support V.4). To configure GCC +for these platforms use the following configurations: + +@table @samp +@item mips-mips-riscos@code{rev} +Default configuration for RISC-OS, revision @code{rev}. + +@item mips-mips-riscos@code{rev}bsd +BSD 4.3 configuration for RISC-OS, revision @code{rev}. + +@item mips-mips-riscos@code{rev}sysv4 +System V.4 configuration for RISC-OS, revision @code{rev}. + +@item mips-mips-riscos@code{rev}sysv +System V.3 configuration for RISC-OS, revision @code{rev}. +@end table + +The revision @code{rev} mentioned above is the revision of +RISC-OS to use. You must reconfigure GCC when going from a +RISC-OS revision 4 to RISC-OS revision 5. This has the effect of +avoiding a linker +@ifclear INSTALLONLY +bug (see @ref{Installation Problems}, for more details). +@end ifclear +@ifset INSTALLONLY +bug. +@end ifset + +@item mips-sgi-* +In order to compile GCC on an SGI running IRIX 4, the "c.hdr.lib" +option must be installed from the CD-ROM supplied from Silicon Graphics. +This is found on the 2nd CD in release 4.0.1. + +@code{make compare} may fail on version 5 of IRIX unless you add +@samp{-save-temps} to @code{CFLAGS}. On these systems, the name of the +assembler input file is stored in the object file, and that makes +comparison fail if it differs between the @code{stage1} and +@code{stage2} compilations. The option @samp{-save-temps} forces a +fixed name to be used for the assembler input file, instead of a +randomly chosen name in @file{/tmp}. Do not add @samp{-save-temps} +unless the comparisons fail without that option. If you do you +@samp{-save-temps}, you will have to manually delete the @samp{.i} and +@samp{.s} files after each series of compilations. + +The MIPS C compiler needs to be told to increase its table size +for switch statements with the @samp{-Wf,-XNg1500} option in +order to compile @file{cp/parse.c}. If you use the @samp{-O2} +optimization option, you also need to use @samp{-Olimit 3000}. +Both of these options are automatically generated in the +@file{Makefile} that the shell script @file{configure} builds. +If you override the @code{CC} make variable and use the MIPS +compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}. + +On Irix version 4.0.5F, and perhaps on some other versions as well, +there is an assembler bug that reorders instructions incorrectly. To +work around it, specify the target configuration +@samp{mips-sgi-irix4loser}. This configuration inhibits assembler +optimization. + +In a compiler configured with target @samp{mips-sgi-irix4}, you can turn +off assembler optimization by using the @samp{-noasmopt} option. This +compiler option passes the option @samp{-O0} to the assembler, to +inhibit reordering. + +The @samp{-noasmopt} option can be useful for testing whether a problem +is due to erroneous assembler reordering. Even if a problem does not go +away with @samp{-noasmopt}, it may still be due to assembler +reordering---perhaps GNU CC itself was miscompiled as a result. + +To enable debugging under Irix 5, you must use GNU as 2.5 or later, +and use the --with-gnu-as configure option when configuring gcc. +GNU as is distributed as part of the binutils package. + +@item mips-sony-sysv +Sony MIPS NEWS. This works in NEWSOS 5.0.1, but not in 5.0.2 (which +uses ELF instead of COFF). Support for 5.0.2 will probably be provided +soon by volunteers. In particular, the linker does not like the +code generated by GCC when shared libraries are linked in. + +@item ns32k-encore +Encore ns32000 system. Encore systems are supported only under BSD. + +@item ns32k-*-genix +National Semiconductor ns32000 system. Genix has bugs in @code{alloca} +and @code{malloc}; you must get the compiled versions of these from GNU +Emacs. + +@item ns32k-sequent +Go to the Berkeley universe before compiling. In addition, you probably +need to create a file named @file{string.h} containing just one line: +@samp{#include <strings.h>}. + +@item ns32k-utek +UTEK ns32000 system (``merlin''). The C compiler that comes with this +system cannot compile GNU CC; contact @samp{tektronix!reed!mason} to get +binaries of GNU CC for bootstrapping. + +@item romp-*-aos +@itemx romp-*-mach +The only operating systems supported for the IBM RT PC are AOS and +MACH. GNU CC does not support AIX running on the RT. We recommend you +compile GNU CC with an earlier version of itself; if you compile GNU CC +with @code{hc}, the Metaware compiler, it will work, but you will get +mismatches between the stage 2 and stage 3 compilers in various files. +These errors are minor differences in some floating-point constants and +can be safely ignored; the stage 3 compiler is correct. + +@item rs6000-*-aix +If you are running AIX version 3.2.5 and have XLC version 1.3.0.0, you +must obtain XLC 1.3.0.1 by requesting PTF 421749 from IBM. Likewise, +XLC-1.3.0.19 cannot correctly compile GNU CC; you must obtain +XLC-1.3.0.24 by requesting PTF 432238 from IBM. If you are using an +older version of AIX you may have an old version of the IBM assembler, +which cannot correctly handle debugging directives. See the file +@file{README.RS6000} for more details on both of these problems. + +The PowerPC and POWER2 architectures are now supported, but have not +been very extensively tested due to lack of appropriate systems. Only +AIX is supported on the PowerPC. GNU CC does not yet support the 64-bit +PowerPC instructions. + +Objective C does not work on this architecture. + +AIX on the RS/6000 provides support (NLS) for environments outside of +the United States. Compilers and assemblers use NLS to support +locale-specific representations of various objects including +floating-point numbers ("." vs "," for separating decimal fractions). +There have been problems reported where the library linked with GNU CC +does not produce the same floating-point formats that the assembler +accepts. If you have this problem, set the LANG environment variable to +"C" or "En_US". + +@item vax-dec-ultrix +Don't try compiling with Vax C (@code{vcc}). It produces incorrect code +in some cases (for example, when @code{alloca} is used). + +Meanwhile, compiling @file{cp/parse.c} with pcc does not work because of +an internal table size limitation in that compiler. To avoid this +problem, compile just the GNU C compiler first, and use it to recompile +building all the languages that you want to run. + +@item sparc-sun-* +See @ref{Sun Install}, for information on installing GNU CC on Sun +systems. + +@item vax-dec-vms +See @ref{VMS Install}, for details on how to install GNU CC on VMS. + +@item we32k-*-* +These computers are also known as the 3b2, 3b5, 3b20 and other similar +names. (However, the 3b1 is actually a 68000; see +@ref{Configurations}.) + +Don't use @samp{-g} when compiling with the system's compiler. The +system's linker seems to be unable to handle such a large program with +debugging information. + +The system's compiler runs out of capacity when compiling @file{stmt.c} +in GNU CC. You can work around this by building @file{cpp} in GNU CC +first, then use that instead of the system's preprocessor with the +system's C compiler to compile @file{stmt.c}. Here is how: + +@example +mv /lib/cpp /lib/cpp.att +cp cpp /lib/cpp.gnu +echo '/lib/cpp.gnu -traditional $@{1+"$@@"@}' > /lib/cpp +chmod +x /lib/cpp +@end example + +The system's compiler produces bad code for some of the GNU CC +optimization files. So you must build the stage 2 compiler without +optimization. Then build a stage 3 compiler with optimization. +That executable should work. Here are the necessary commands: + +@example +make LANGUAGES=c CC=stage1/xgcc CFLAGS="-Bstage1/ -g" +make stage2 +make CC=stage2/xgcc CFLAGS="-Bstage2/ -g -O" +@end example + +You may need to raise the ULIMIT setting to build a C++ compiler, +as the file @file{cc1plus} is larger than one megabyte. +@end table + +@node Other Dir +@section Compilation in a Separate Directory +@cindex other directory, compilation in +@cindex compilation in a separate directory +@cindex separate directory, compilation in + +If you wish to build the object files and executables in a directory +other than the one containing the source files, here is what you must +do differently: + +@enumerate +@item +Make sure you have a version of Make that supports the @code{VPATH} +feature. (GNU Make supports it, as do Make versions on most BSD +systems.) + +@item +If you have ever run @file{configure} in the source directory, you must undo +the configuration. Do this by running: + +@example +make distclean +@end example + +@item +Go to the directory in which you want to build the compiler before +running @file{configure}: + +@example +mkdir gcc-sun3 +cd gcc-sun3 +@end example + +On systems that do not support symbolic links, this directory must be +on the same file system as the source code directory. + +@item +Specify where to find @file{configure} when you run it: + +@example +../gcc/configure @dots{} +@end example + +This also tells @code{configure} where to find the compiler sources; +@code{configure} takes the directory from the file name that was used to +invoke it. But if you want to be sure, you can specify the source +directory with the @samp{--srcdir} option, like this: + +@example +../gcc/configure --srcdir=../gcc @var{other options} +@end example + +The directory you specify with @samp{--srcdir} need not be the same +as the one that @code{configure} is found in. +@end enumerate + +Now, you can run @code{make} in that directory. You need not repeat the +configuration steps shown above, when ordinary source files change. You +must, however, run @code{configure} again when the configuration files +change, if your system does not support symbolic links. + +@node Cross-Compiler +@section Building and Installing a Cross-Compiler +@cindex cross-compiler, installation + +GNU CC can function as a cross-compiler for many machines, but not all. + +@itemize @bullet +@item +Cross-compilers for the Mips as target using the Mips assembler +currently do not work, because the auxiliary programs +@file{mips-tdump.c} and @file{mips-tfile.c} can't be compiled on +anything but a Mips. It does work to cross compile for a Mips +if you use the GNU assembler and linker. + +@item +Cross-compilers between machines with different floating point formats +have not all been made to work. GNU CC now has a floating point +emulator with which these can work, but each target machine description +needs to be updated to take advantage of it. + +@item +Cross-compilation between machines of different word sizes is +somewhat problematic and sometimes does not work. +@end itemize + +Since GNU CC generates assembler code, you probably need a +cross-assembler that GNU CC can run, in order to produce object files. +If you want to link on other than the target machine, you need a +cross-linker as well. You also need header files and libraries suitable +for the target machine that you can install on the host machine. + +@menu +* Steps of Cross:: Using a cross-compiler involves several steps + that may be carried out on different machines. +* Configure Cross:: Configuring a cross-compiler. +* Tools and Libraries:: Where to put the linker and assembler, and the C library. +* Cross Headers:: Finding and installing header files + for a cross-compiler. +* Cross Runtime:: Supplying arithmetic runtime routines (@file{libgcc1.a}). +* Build Cross:: Actually compiling the cross-compiler. +@end menu + +@node Steps of Cross +@subsection Steps of Cross-Compilation + +To compile and run a program using a cross-compiler involves several +steps: + +@itemize @bullet +@item +Run the cross-compiler on the host machine to produce assembler files +for the target machine. This requires header files for the target +machine. + +@item +Assemble the files produced by the cross-compiler. You can do this +either with an assembler on the target machine, or with a +cross-assembler on the host machine. + +@item +Link those files to make an executable. You can do this either with a +linker on the target machine, or with a cross-linker on the host +machine. Whichever machine you use, you need libraries and certain +startup files (typically @file{crt@dots{}.o}) for the target machine. +@end itemize + +It is most convenient to do all of these steps on the same host machine, +since then you can do it all with a single invocation of GNU CC. This +requires a suitable cross-assembler and cross-linker. For some targets, +the GNU assembler and linker are available. + +@node Configure Cross +@subsection Configuring a Cross-Compiler + +To build GNU CC as a cross-compiler, you start out by running +@file{configure}. Use the @samp{--target=@var{target}} to specify the +target type. If @file{configure} was unable to correctly identify the +system you are running on, also specify the @samp{--build=@var{build}} +option. For example, here is how to configure for a cross-compiler that +produces code for an HP 68030 system running BSD on a system that +@file{configure} can correctly identify: + +@smallexample +./configure --target=m68k-hp-bsd4.3 +@end smallexample + +@node Tools and Libraries +@subsection Tools and Libraries for a Cross-Compiler + +If you have a cross-assembler and cross-linker available, you should +install them now. Put them in the directory +@file{/usr/local/@var{target}/bin}. Here is a table of the tools +you should put in this directory: + +@table @file +@item as +This should be the cross-assembler. + +@item ld +This should be the cross-linker. + +@item ar +This should be the cross-archiver: a program which can manipulate +archive files (linker libraries) in the target machine's format. + +@item ranlib +This should be a program to construct a symbol table in an archive file. +@end table + +The installation of GNU CC will find these programs in that directory, +and copy or link them to the proper place to for the cross-compiler to +find them when run later. + +The easiest way to provide these files is to build the Binutils package +and GAS. Configure them with the same @samp{--host} and @samp{--target} +options that you use for configuring GNU CC, then build and install +them. They install their executables automatically into the proper +directory. Alas, they do not support all the targets that GNU CC +supports. + +If you want to install libraries to use with the cross-compiler, such as +a standard C library, put them in the directory +@file{/usr/local/@var{target}/lib}; installation of GNU CC copies all +all the files in that subdirectory into the proper place for GNU CC to +find them and link with them. Here's an example of copying some +libraries from a target machine: + +@example +ftp @var{target-machine} +lcd /usr/local/@var{target}/lib +cd /lib +get libc.a +cd /usr/lib +get libg.a +get libm.a +quit +@end example + +@noindent +The precise set of libraries you'll need, and their locations on +the target machine, vary depending on its operating system. + +@cindex start files +Many targets require ``start files'' such as @file{crt0.o} and +@file{crtn.o} which are linked into each executable; these too should be +placed in @file{/usr/local/@var{target}/lib}. There may be several +alternatives for @file{crt0.o}, for use with profiling or other +compilation options. Check your target's definition of +@code{STARTFILE_SPEC} to find out what start files it uses. +Here's an example of copying these files from a target machine: + +@example +ftp @var{target-machine} +lcd /usr/local/@var{target}/lib +prompt +cd /lib +mget *crt*.o +cd /usr/lib +mget *crt*.o +quit +@end example + +@node Cross Runtime +@subsection @file{libgcc.a} and Cross-Compilers + +Code compiled by GNU CC uses certain runtime support functions +implicitly. Some of these functions can be compiled successfully with +GNU CC itself, but a few cannot be. These problem functions are in the +source file @file{libgcc1.c}; the library made from them is called +@file{libgcc1.a}. + +When you build a native compiler, these functions are compiled with some +other compiler--the one that you use for bootstrapping GNU CC. +Presumably it knows how to open code these operations, or else knows how +to call the run-time emulation facilities that the machine comes with. +But this approach doesn't work for building a cross-compiler. The +compiler that you use for building knows about the host system, not the +target system. + +So, when you build a cross-compiler you have to supply a suitable +library @file{libgcc1.a} that does the job it is expected to do. + +To compile @file{libgcc1.c} with the cross-compiler itself does not +work. The functions in this file are supposed to implement arithmetic +operations that GNU CC does not know how to open code, for your target +machine. If these functions are compiled with GNU CC itself, they +will compile into infinite recursion. + +On any given target, most of these functions are not needed. If GNU CC +can open code an arithmetic operation, it will not call these functions +to perform the operation. It is possible that on your target machine, +none of these functions is needed. If so, you can supply an empty +library as @file{libgcc1.a}. + +Many targets need library support only for multiplication and division. +If you are linking with a library that contains functions for +multiplication and division, you can tell GNU CC to call them directly +by defining the macros @code{MULSI3_LIBCALL}, and the like. These +macros need to be defined in the target description macro file. For +some targets, they are defined already. This may be sufficient to +avoid the need for libgcc1.a; if so, you can supply an empty library. + +Some targets do not have floating point instructions; they need other +functions in @file{libgcc1.a}, which do floating arithmetic. +Recent versions of GNU CC have a file which emulates floating point. +With a certain amount of work, you should be able to construct a +floating point emulator that can be used as @file{libgcc1.a}. Perhaps +future versions will contain code to do this automatically and +conveniently. That depends on whether someone wants to implement it. + +If your target system has another C compiler, you can configure GNU CC +as a native compiler on that machine, build just @file{libgcc1.a} with +@samp{make libgcc1.a} on that machine, and use the resulting file with +the cross-compiler. To do this, execute the following on the target +machine: + +@example +cd @var{target-build-dir} +./configure --host=sparc --target=sun3 +make libgcc1.a +@end example + +@noindent +And then this on the host machine: + +@example +ftp @var{target-machine} +binary +cd @var{target-build-dir} +get libgcc1.a +quit +@end example + +Another way to provide the functions you need in @file{libgcc1.a} is to +define the appropriate @code{perform_@dots{}} macros for those +functions. If these definitions do not use the C arithmetic operators +that they are meant to implement, you should be able to compile them +with the cross-compiler you are building. (If these definitions already +exist for your target file, then you are all set.) + +To build @file{libgcc1.a} using the perform macros, use +@samp{LIBGCC1=libgcc1.a OLDCC=./xgcc} when building the compiler. +Otherwise, you should place your replacement library under the name +@file{libgcc1.a} in the directory in which you will build the +cross-compiler, before you run @code{make}. + +@node Cross Headers +@subsection Cross-Compilers and Header Files + +If you are cross-compiling a standalone program or a program for an +embedded system, then you may not need any header files except the few +that are part of GNU CC (and those of your program). However, if you +intend to link your program with a standard C library such as +@file{libc.a}, then you probably need to compile with the header files +that go with the library you use. + +The GNU C compiler does not come with these files, because (1) they are +system-specific, and (2) they belong in a C library, not in a compiler. + +If the GNU C library supports your target machine, then you can get the +header files from there (assuming you actually use the GNU library when +you link your program). + +If your target machine comes with a C compiler, it probably comes with +suitable header files also. If you make these files accessible from the host +machine, the cross-compiler can use them also. + +Otherwise, you're on your own in finding header files to use when +cross-compiling. + +When you have found suitable header files, put them in +@file{/usr/local/@var{target}/include}, before building the cross +compiler. Then installation will run fixincludes properly and install +the corrected versions of the header files where the compiler will use +them. + +Provide the header files before you build the cross-compiler, because +the build stage actually runs the cross-compiler to produce parts of +@file{libgcc.a}. (These are the parts that @emph{can} be compiled with +GNU CC.) Some of them need suitable header files. + +Here's an example showing how to copy the header files from a target +machine. On the target machine, do this: + +@example +(cd /usr/include; tar cf - .) > tarfile +@end example + +Then, on the host machine, do this: + +@example +ftp @var{target-machine} +lcd /usr/local/@var{target}/include +get tarfile +quit +tar xf tarfile +@end example + +@node Build Cross +@subsection Actually Building the Cross-Compiler + +Now you can proceed just as for compiling a single-machine compiler +through the step of building stage 1. If you have not provided some +sort of @file{libgcc1.a}, then compilation will give up at the point +where it needs that file, printing a suitable error message. If you +do provide @file{libgcc1.a}, then building the compiler will automatically +compile and link a test program called @file{cross-test}; if you get +errors in the linking, it means that not all of the necessary routines +in @file{libgcc1.a} are available. + +If you are making a cross-compiler for an embedded system, and there is +no @file{stdio.h} header for it, then the compilation of @file{enquire} +will probably fail. The job of @file{enquire} is to run on the target +machine and figure out by experiment the nature of its floating point +representation. @file{enquire} records its findings in the header file +@file{float.h}. If you can't produce this file by running +@file{enquire} on the target machine, then you will need to come up with +a suitable @file{float.h} in some other way (or else, avoid using it in +your programs). + +Do not try to build stage 2 for a cross-compiler. It doesn't work to +rebuild GNU CC as a cross-compiler using the cross-compiler, because +that would produce a program that runs on the target machine, not on the +host. For example, if you compile a 386-to-68030 cross-compiler with +itself, the result will not be right either for the 386 (because it was +compiled into 68030 code) or for the 68030 (because it was configured +for a 386 as the host). If you want to compile GNU CC into 68030 code, +whether you compile it on a 68030 or with a cross-compiler on a 386, you +must specify a 68030 as the host when you configure it. + +To install the cross-compiler, use @samp{make install}, as usual. + +@node Sun Install +@section Installing GNU CC on the Sun +@cindex Sun installation +@cindex installing GNU CC on the Sun + +On Solaris (version 2.1), do not use the linker or other tools in +@file{/usr/ucb} to build GNU CC. Use @code{/usr/ccs/bin}. + +Make sure the environment variable @code{FLOAT_OPTION} is not set when +you compile @file{libgcc.a}. If this option were set to @code{f68881} +when @file{libgcc.a} is compiled, the resulting code would demand to be +linked with a special startup file and would not link properly without +special pains. + +@cindex @code{alloca}, for SunOs +There is a bug in @code{alloca} in certain versions of the Sun library. +To avoid this bug, install the binaries of GNU CC that were compiled by +GNU CC. They use @code{alloca} as a built-in function and never the one +in the library. + +Some versions of the Sun compiler crash when compiling GNU CC. The +problem is a segmentation fault in cpp. This problem seems to be due to +the bulk of data in the environment variables. You may be able to avoid +it by using the following command to compile GNU CC with Sun CC: + +@example +make CC="TERMCAP=x OBJS=x LIBFUNCS=x STAGESTUFF=x cc" +@end example + +@node VMS Install +@section Installing GNU CC on VMS +@cindex VMS installation +@cindex installing GNU CC on VMS + +The VMS version of GNU CC is distributed in a backup saveset containing +both source code and precompiled binaries. + +To install the @file{gcc} command so you can use the compiler easily, in +the same manner as you use the VMS C compiler, you must install the VMS CLD +file for GNU CC as follows: + +@enumerate +@item +Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE} +to point to the directories where the GNU CC executables +(@file{gcc-cpp.exe}, @file{gcc-cc1.exe}, etc.) and the C include files are +kept respectively. This should be done with the commands:@refill + +@smallexample +$ assign /system /translation=concealed - + disk:[gcc.] gnu_cc +$ assign /system /translation=concealed - + disk:[gcc.include.] gnu_cc_include +@end smallexample + +@noindent +with the appropriate disk and directory names. These commands can be +placed in your system startup file so they will be executed whenever +the machine is rebooted. You may, if you choose, do this via the +@file{GCC_INSTALL.COM} script in the @file{[GCC]} directory. + +@item +Install the @file{GCC} command with the command line: + +@smallexample +$ set command /table=sys$common:[syslib]dcltables - + /output=sys$common:[syslib]dcltables gnu_cc:[000000]gcc +$ install replace sys$common:[syslib]dcltables +@end smallexample + +@item +To install the help file, do the following: + +@smallexample +$ library/help sys$library:helplib.hlb gcc.hlp +@end smallexample + +@noindent +Now you can invoke the compiler with a command like @samp{gcc /verbose +file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in +Unix. +@end enumerate + +If you wish to use GNU C++ you must first install GNU CC, and then +perform the following steps: + +@enumerate +@item +Define the VMS logical name @samp{GNU_GXX_INCLUDE} to point to the +directory where the preprocessor will search for the C++ header files. +This can be done with the command:@refill + +@smallexample +$ assign /system /translation=concealed - + disk:[gcc.gxx_include.] gnu_gxx_include +@end smallexample + +@noindent +with the appropriate disk and directory name. If you are going to be +using libg++, this is where the libg++ install procedure will install +the libg++ header files. + +@item +Obtain the file @file{gcc-cc1plus.exe}, and place this in the same +directory that @file{gcc-cc1.exe} is kept. + +The GNU C++ compiler can be invoked with a command like @samp{gcc /plus +/verbose file.cc}, which is equivalent to the command @samp{g++ -v -c +file.cc} in Unix. +@end enumerate + +We try to put corresponding binaries and sources on the VMS distribution +tape. But sometimes the binaries will be from an older version than the +sources, because we don't always have time to update them. (Use the +@samp{/version} option to determine the version number of the binaries and +compare it with the source file @file{version.c} to tell whether this is +so.) In this case, you should use the binaries you get to recompile the +sources. If you must recompile, here is how: + +@enumerate +@item +Execute the command procedure @file{vmsconfig.com} to set up the files +@file{tm.h}, @file{config.h}, @file{aux-output.c}, and @file{md.}, and +to create files @file{tconfig.h} and @file{hconfig.h}. This procedure +also creates several linker option files used by @file{make-cc1.com} and +a data file used by @file{make-l2.com}.@refill + +@smallexample +$ @@vmsconfig.com +@end smallexample + +@item +Setup the logical names and command tables as defined above. In +addition, define the VMS logical name @samp{GNU_BISON} to point at the +to the directories where the Bison executable is kept. This should be +done with the command:@refill + +@smallexample +$ assign /system /translation=concealed - + disk:[bison.] gnu_bison +@end smallexample + +You may, if you choose, use the @file{INSTALL_BISON.COM} script in the +@file{[BISON]} directory. + +@item +Install the @samp{BISON} command with the command line:@refill + +@smallexample +$ set command /table=sys$common:[syslib]dcltables - + /output=sys$common:[syslib]dcltables - + gnu_bison:[000000]bison +$ install replace sys$common:[syslib]dcltables +@end smallexample + +@item +Type @samp{@@make-gcc} to recompile everything (alternatively, submit +the file @file{make-gcc.com} to a batch queue). If you wish to build +the GNU C++ compiler as well as the GNU CC compiler, you must first edit +@file{make-gcc.com} and follow the instructions that appear in the +comments.@refill + +@item +In order to use GCC, you need a library of functions which GCC compiled code +will call to perform certain tasks, and these functions are defined in the +file @file{libgcc2.c}. To compile this you should use the command procedure +@file{make-l2.com}, which will generate the library @file{libgcc2.olb}. +@file{libgcc2.olb} should be built using the compiler built from +the same distribution that @file{libgcc2.c} came from, and +@file{make-gcc.com} will automatically do all of this for you. + +To install the library, use the following commands:@refill + +@smallexample +$ library gnu_cc:[000000]gcclib/delete=(new,eprintf) +$ library gnu_cc:[000000]gcclib/delete=L_* +$ library libgcc2/extract=*/output=libgcc2.obj +$ library gnu_cc:[000000]gcclib libgcc2.obj +@end smallexample + +The first command simply removes old modules that will be replaced with +modules from @file{libgcc2} under different module names. The modules +@code{new} and @code{eprintf} may not actually be present in your +@file{gcclib.olb}---if the VMS librarian complains about those modules +not being present, simply ignore the message and continue on with the +next command. The second command removes the modules that came from the +previous version of the library @file{libgcc2.c}. + +Whenever you update the compiler on your system, you should also update the +library with the above procedure. + +@item +You may wish to build GCC in such a way that no files are written to the +directory where the source files reside. An example would be the when +the source files are on a read-only disk. In these cases, execute the +following DCL commands (substituting your actual path names): + +@smallexample +$ assign dua0:[gcc.build_dir.]/translation=concealed, - + dua1:[gcc.source_dir.]/translation=concealed gcc_build +$ set default gcc_build:[000000] +@end smallexample + +@noindent +where the directory @file{dua1:[gcc.source_dir]} contains the source +code, and the directory @file{dua0:[gcc.build_dir]} is meant to contain +all of the generated object files and executables. Once you have done +this, you can proceed building GCC as described above. (Keep in mind +that @file{gcc_build} is a rooted logical name, and thus the device +names in each element of the search list must be an actual physical +device name rather than another rooted logical name). + +@item +@strong{If you are building GNU CC with a previous version of GNU CC, +you also should check to see that you have the newest version of the +assembler}. In particular, GNU CC version 2 treats global constant +variables slightly differently from GNU CC version 1, and GAS version +1.38.1 does not have the patches required to work with GCC version 2. +If you use GAS 1.38.1, then @code{extern const} variables will not have +the read-only bit set, and the linker will generate warning messages +about mismatched psect attributes for these variables. These warning +messages are merely a nuisance, and can safely be ignored. + +If you are compiling with a version of GNU CC older than 1.33, specify +@samp{/DEFINE=("inline=")} as an option in all the compilations. This +requires editing all the @code{gcc} commands in @file{make-cc1.com}. +(The older versions had problems supporting @code{inline}.) Once you +have a working 1.33 or newer GNU CC, you can change this file back. + +@item +If you want to build GNU CC with the VAX C compiler, you will need to +make minor changes in @file{make-cccp.com} and @file{make-cc1.com} +to choose alternate definitions of @code{CC}, @code{CFLAGS}, and +@code{LIBS}. See comments in those files. However, you must +also have a working version of the GNU assembler (GNU as, aka GAS) as +it is used as the back-end for GNU CC to produce binary object modules +and is not included in the GNU CC sources. GAS is also needed to +compile @file{libgcc2} in order to build @file{gcclib} (see above); +@file{make-l2.com} expects to be able to find it operational in +@file{gnu_cc:[000000]gnu-as.exe}. + +To use GNU CC on VMS, you need the VMS driver programs +@file{gcc.exe}, @file{gcc.com}, and @file{gcc.cld}. They are +distributed with the VMS binaries (@file{gcc-vms}) rather than the +GNU CC sources. GAS is also included in @file{gcc-vms}, as is Bison. + +Once you have successfully built GNU CC with VAX C, you should use the +resulting compiler to rebuild itself. Before doing this, be sure to +restore the @code{CC}, @code{CFLAGS}, and @code{LIBS} definitions in +@file{make-cccp.com} and @file{make-cc1.com}. The second generation +compiler will be able to take advantage of many optimizations that must +be suppressed when building with other compilers. +@end enumerate + +Under previous versions of GNU CC, the generated code would occasionally +give strange results when linked with the sharable @file{VAXCRTL} library. +Now this should work. + +Even with this version, however, GNU CC itself should not be linked with +the sharable @file{VAXCRTL}. The version of @code{qsort} in +@file{VAXCRTL} has a bug (known to be present in VMS versions V4.6 +through V5.5) which causes the compiler to fail. + +The executables are generated by @file{make-cc1.com} and +@file{make-cccp.com} use the object library version of @file{VAXCRTL} in +order to make use of the @code{qsort} routine in @file{gcclib.olb}. If +you wish to link the compiler executables with the shareable image +version of @file{VAXCRTL}, you should edit the file @file{tm.h} (created +by @file{vmsconfig.com}) to define the macro @code{QSORT_WORKAROUND}. + +@code{QSORT_WORKAROUND} is always defined when GNU CC is compiled with +VAX C, to avoid a problem in case @file{gcclib.olb} is not yet +available. + +@node Collect2 +@section @code{collect2} + +Many target systems do not have support in the assembler and linker for +``constructors''---initialization functions to be called before the +official ``start'' of @code{main}. On such systems, GNU CC uses a +utility called @code{collect2} to arrange to call these functions at +start time. + +The program @code{collect2} works by linking the program once and +looking through the linker output file for symbols with particular names +indicating they are constructor functions. If it finds any, it +creates a new temporary @samp{.c} file containing a table of them, +compiles it, and links the program a second time including that file. + +@findex __main +@cindex constructors, automatic calls +The actual calls to the constructors are carried out by a subroutine +called @code{__main}, which is called (automatically) at the beginning +of the body of @code{main} (provided @code{main} was compiled with GNU +CC). Calling @code{__main} is necessary, even when compiling C code, to +allow linking C and C++ object code together. (If you use +@samp{-nostdlib}, you get an unresolved reference to @code{__main}, +since it's defined in the standard GCC library. Include @samp{-lgcc} at +the end of your compiler command line to resolve this reference.) + +The program @code{collect2} is installed as @code{ld} in the directory +where the passes of the compiler are installed. When @code{collect2} +needs to find the @emph{real} @code{ld}, it tries the following file +names: + +@itemize @bullet +@item +@file{real-ld} in the directories listed in the compiler's search +directories. + +@item +@file{real-ld} in the directories listed in the environment variable +@code{PATH}. + +@item +The file specified in the @code{REAL_LD_FILE_NAME} configuration macro, +if specified. + +@item +@file{ld} in the compiler's search directories, except that +@code{collect2} will not execute itself recursively. + +@item +@file{ld} in @code{PATH}. +@end itemize + +``The compiler's search directories'' means all the directories where +@code{gcc} searches for passes of the compiler. This includes +directories that you specify with @samp{-B}. + +Cross-compilers search a little differently: + +@itemize @bullet +@item +@file{real-ld} in the compiler's search directories. + +@item +@file{@var{target}-real-ld} in @code{PATH}. + +@item +The file specified in the @code{REAL_LD_FILE_NAME} configuration macro, +if specified. + +@item +@file{ld} in the compiler's search directories. + +@item +@file{@var{target}-ld} in @code{PATH}. +@end itemize + +@code{collect2} explicitly avoids running @code{ld} using the file name +under which @code{collect2} itself was invoked. In fact, it remembers +up a list of such names---in case one copy of @code{collect2} finds +another copy (or version) of @code{collect2} installed as @code{ld} in a +second place in the search path. + +@code{collect2} searches for the utilities @code{nm} and @code{strip} +using the same algorithm as above for @code{ld}. + +@node Header Dirs +@section Standard Header File Directories + +@code{GCC_INCLUDE_DIR} means the same thing for native and cross. It is +where GNU CC stores its private include files, and also where GNU CC +stores the fixed include files. A cross compiled GNU CC runs +@code{fixincludes} on the header files in @file{$(tooldir)/include}. +(If the cross compilation header files need to be fixed, they must be +installed before GNU CC is built. If the cross compilation header files +are already suitable for ANSI C and GNU CC, nothing special need be +done). + +@code{GPLUS_INCLUDE_DIR} means the same thing for native and cross. It +is where @code{g++} looks first for header files. @code{libg++} +installs only target independent header files in that directory. + +@code{LOCAL_INCLUDE_DIR} is used only for a native compiler. It is +normally @file{/usr/local/include}. GNU CC searches this directory so +that users can install header files in @file{/usr/local/include}. + +@code{CROSS_INCLUDE_DIR} is used only for a cross compiler. GNU CC +doesn't install anything there. + +@code{TOOL_INCLUDE_DIR} is used for both native and cross compilers. It +is the place for other packages to install header files that GNU CC will +use. For a cross-compiler, this is the equivalent of +@file{/usr/include}. When you build a cross-compiler, +@code{fixincludes} processes any header files in this directory. diff --git a/gnu/usr.bin/cc/doc/invoke.texi b/gnu/usr.bin/cc/doc/invoke.texi new file mode 100644 index 0000000..d3fc4f3 --- /dev/null +++ b/gnu/usr.bin/cc/doc/invoke.texi @@ -0,0 +1,4207 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Invoking GCC +@chapter GNU CC Command Options +@cindex GNU CC command options +@cindex command options +@cindex options, GNU CC command + +When you invoke GNU CC, it normally does preprocessing, compilation, +assembly and linking. The ``overall options'' allow you to stop this +process at an intermediate stage. For example, the @samp{-c} option +says not to run the linker. Then the output consists of object files +output by the assembler. + +Other options are passed on to one stage of processing. Some options +control the preprocessor and others the compiler itself. Yet other +options control the assembler and linker; most of these are not +documented here, since you rarely need to use any of them. + +@cindex C compilation options +Most of the command line options that you can use with GNU CC are useful +for C programs; when an option is only useful with another language +(usually C++), the explanation says so explicitly. If the description +for a particular option does not mention a source language, you can use +that option with all supported languages. + +@cindex C++ compilation options +@xref{Invoking G++,,Compiling C++ Programs}, for a summary of special +options for compiling C++ programs. + +@cindex grouping options +@cindex options, grouping +The @code{gcc} program accepts options and file names as operands. Many +options have multiletter names; therefore multiple single-letter options +may @emph{not} be grouped: @samp{-dr} is very different from @w{@samp{-d +-r}}. + +@cindex order of options +@cindex options, order +You can mix options and other arguments. For the most part, the order +you use doesn't matter. Order does matter when you use several options +of the same kind; for example, if you specify @samp{-L} more than once, +the directories are searched in the order specified. + +Many options have long names starting with @samp{-f} or with +@samp{-W}---for example, @samp{-fforce-mem}, +@samp{-fstrength-reduce}, @samp{-Wformat} and so on. Most of +these have both positive and negative forms; the negative form of +@samp{-ffoo} would be @samp{-fno-foo}. This manual documents +only one of these two forms, whichever one is not the default. + +@menu +* Option Summary:: Brief list of all options, without explanations. +* Overall Options:: Controlling the kind of output: + an executable, object files, assembler files, + or preprocessed source. +* Invoking G++:: Compiling C++ programs. +* C Dialect Options:: Controlling the variant of C language compiled. +* C++ Dialect Options:: Variations on C++. +* Warning Options:: How picky should the compiler be? +* Debugging Options:: Symbol tables, measurements, and debugging dumps. +* Optimize Options:: How much optimization? +* Preprocessor Options:: Controlling header files and macro definitions. + Also, getting dependency information for Make. +* Assembler Options:: Passing options to the assembler. +* Link Options:: Specifying libraries and so on. +* Directory Options:: Where to find header files and libraries. + Where to find the compiler executable files. +* Target Options:: Running a cross-compiler, or an old version of GNU CC. +* Submodel Options:: Specifying minor hardware or convention variations, + such as 68010 vs 68020. +* Code Gen Options:: Specifying conventions for function calls, data layout + and register usage. +* Environment Variables:: Env vars that affect GNU CC. +* Running Protoize:: Automatically adding or removing function prototypes. +@end menu + +@node Option Summary +@section Option Summary + +Here is a summary of all the options, grouped by type. Explanations are +in the following sections. + +@table @emph +@item Overall Options +@xref{Overall Options,,Options Controlling the Kind of Output}. +@smallexample +-c -S -E -o @var{file} -pipe -v -x @var{language} +@end smallexample + +@item C Language Options +@xref{C Dialect Options,,Options Controlling C Dialect}. +@smallexample +-ansi -fallow-single-precision -fcond-mismatch -fno-asm +-fno-builtin -fsigned-bitfields -fsigned-char +-funsigned-bitfields -funsigned-char -fwritable-strings +-traditional -traditional-cpp -trigraphs +@end smallexample + +@item C++ Language Options +@xref{C++ Dialect Options,,Options Controlling C++ Dialect}. +@smallexample +-fall-virtual -fdollars-in-identifiers -felide-constructors +-fenum-int-equiv -fexternal-templates -fhandle-signatures +-fmemoize-lookups -fno-default-inline -fno-strict-prototype +-fnonnull-objects -fthis-is-variable -nostdinc++ +-traditional +e@var{n} +@end smallexample + +@item Warning Options +@xref{Warning Options,,Options to Request or Suppress Warnings}. +@smallexample +-fsyntax-only -pedantic -pedantic-errors +-w -W -Wall -Waggregate-return -Wbad-function-cast +-Wcast-align -Wcast-qual -Wchar-subscript -Wcomment +-Wconversion -Wenum-clash -Werror -Wformat +-Wid-clash-@var{len} -Wimplicit -Wimport -Winline +-Wlarger-than-@var{len} -Wmissing-declarations +-Wmissing-prototypes -Wnested-externs +-Wno-import -Woverloaded-virtual -Wparentheses +-Wpointer-arith -Wredundant-decls -Wreorder -Wreturn-type -Wshadow +-Wstrict-prototypes -Wswitch -Wsynth -Wtemplate-debugging +-Wtraditional -Wtrigraphs -Wuninitialized -Wunused +-Wwrite-strings +@end smallexample + +@item Debugging Options +@xref{Debugging Options,,Options for Debugging Your Program or GCC}. +@smallexample +-a -d@var{letters} -fpretend-float +-g -g@var{level} -gcoff -gdwarf -gdwarf+ +-ggdb -gstabs -gstabs+ -gxcoff -gxcoff+ +-p -pg -print-file-name=@var{library} -print-libgcc-file-name +-print-prog-name=@var{program} -save-temps +@end smallexample + +@item Optimization Options +@xref{Optimize Options,,Options that Control Optimization}. +@smallexample +-fcaller-saves -fcse-follow-jumps -fcse-skip-blocks +-fdelayed-branch -fexpensive-optimizations +-ffast-math -ffloat-store -fforce-addr -fforce-mem +-finline-functions -fkeep-inline-functions +-fno-default-inline -fno-defer-pop -fno-function-cse +-fno-inline -fno-peephole -fomit-frame-pointer +-frerun-cse-after-loop -fschedule-insns +-fschedule-insns2 -fstrength-reduce -fthread-jumps +-funroll-all-loops -funroll-loops +-O -O0 -O1 -O2 -O3 +@end smallexample + +@item Preprocessor Options +@xref{Preprocessor Options,,Options Controlling the Preprocessor}. +@smallexample +-A@var{question}(@var{answer}) -C -dD -dM -dN +-D@var{macro}@r{[}=@var{defn}@r{]} -E -H +-idirafter @var{dir} +-include @var{file} -imacros @var{file} +-iprefix @var{file} -iwithprefix @var{dir} +-iwithprefixbefore @var{dir} -isystem @var{dir} +-M -MD -MM -MMD -MG -nostdinc -P -trigraphs +-undef -U@var{macro} -Wp,@var{option} +@end smallexample + +@item Assembler Option +@xref{Assembler Options,,Passing Options to the Assembler}. +@smallexample +-Wa,@var{option} +@end smallexample + +@item Linker Options +@xref{Link Options,,Options for Linking}. +@smallexample +@var{object-file-name} +-l@var{library} -nostartfiles -nostdlib +-s -static -shared -symbolic +-Wl,@var{option} -Xlinker @var{option} +-u @var{symbol} +@end smallexample + +@item Directory Options +@xref{Directory Options,,Options for Directory Search}. +@smallexample +-B@var{prefix} -I@var{dir} -I- -L@var{dir} +@end smallexample + +@item Target Options +@c I wrote this xref this way to avoid overfull hbox. -- rms +@xref{Target Options}. +@smallexample +-b @var{machine} -V @var{version} +@end smallexample + +@item Machine Dependent Options +@xref{Submodel Options,,Hardware Models and Configurations}. +@smallexample +@emph{M680x0 Options} +-m68000 -m68020 -m68020-40 -m68030 -m68040 -m68881 +-mbitfield -mc68000 -mc68020 -mfpa -mnobitfield +-mrtd -mshort -msoft-float + +@emph{VAX Options} +-mg -mgnu -munix + +@emph{SPARC Options} +-mapp-regs -mcypress -mepilogue -mflat -mfpu -mhard-float +-mhard-quad-float -mno-app-regs -mno-flat -mno-fpu +-mno-epilogue -mno-unaligned-doubles +-msoft-float -msoft-quad-float +-msparclite -msupersparc -munaligned-doubles -mv8 + +SPARC V9 compilers support the following options +in addition to the above: + +-mmedlow -mmedany +-mint32 -mint64 -mlong32 -mlong64 +-mno-stack-bias -mstack-bias + +@emph{Convex Options} +-mc1 -mc2 -mc32 -mc34 -mc38 +-margcount -mnoargcount +-mlong32 -mlong64 +-mvolatile-cache -mvolatile-nocache + +@emph{AMD29K Options} +-m29000 -m29050 -mbw -mnbw -mdw -mndw +-mlarge -mnormal -msmall +-mkernel-registers -mno-reuse-arg-regs +-mno-stack-check -mno-storem-bug +-mreuse-arg-regs -msoft-float -mstack-check +-mstorem-bug -muser-registers + +@emph{ARM Options} +-mapcs -m2 -m3 -m6 -mbsd -mxopen -mno-symrename + +@emph{M88K Options} +-m88000 -m88100 -m88110 -mbig-pic +-mcheck-zero-division -mhandle-large-shift +-midentify-revision -mno-check-zero-division +-mno-ocs-debug-info -mno-ocs-frame-position +-mno-optimize-arg-area -mno-serialize-volatile +-mno-underscores -mocs-debug-info +-mocs-frame-position -moptimize-arg-area +-mserialize-volatile -mshort-data-@var{num} -msvr3 +-msvr4 -mtrap-large-shift -muse-div-instruction +-mversion-03.00 -mwarn-passed-structs + +@emph{RS/6000 Options and PowerPC} +-mcpu=@var{cpu type} +-mpower -mno-power -mpower2 -pno-power2 +-mpowerpc -mno-powerpc +-mpowerpc-gpopt -mno-powerpc-gpopt +-mpowerpc-gfxopt -mno-powerpc-gfxopt +-mnew-mnemonics -mno-new-mnemonics +-mfull-toc -mminimal-toc -mno-fop-in-toc -mno-sum-in-toc + +@emph{RT Options} +-mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs +-mfull-fp-blocks -mhc-struct-return -min-line-mul +-mminimum-fp-blocks -mnohc-struct-return + +@emph{MIPS Options} +-mabicalls -mcpu=@var{cpu type} -membedded-data +-membedded-pic -mfp32 -mfp64 -mgas -mgp32 -mgp64 +-mgpopt -mhalf-pic -mhard-float -mint64 -mips1 +-mips2 -mips3 -mlong64 -mlong-calls -mmemcpy +-mmips-as -mmips-tfile -mno-abicalls +-mno-embedded-data -mno-embedded-pic +-mno-gpopt -mno-long-calls +-mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats +-mrnames -msoft-float +-mstats -G @var{num} -nocpp + +@emph{i386 Options} +-m486 -mieee-fp -mno-486 -mno-fancy-math-387 +-mno-fp-ret-in-387 -msoft-float -msvr3-shlib +-mno-wide-multiply -mreg-alloc=@var{list} + +@emph{HPPA Options} +-mdisable-fpregs -mdisable-indexing -mjump-in-delay +-mgas -mlong-calls -mno-disable-fpregs -mno-disable-indexing +-mno-gas -mno-jump-in-delay +-mno-long-calls -mno-portable-runtime +-mpa-risc-1-0 -mpa-risc-1-1 -mportable-runtime + +@emph{Intel 960 Options} +-m@var{cpu type} -masm-compat -mclean-linkage +-mcode-align -mcomplex-addr -mleaf-procedures +-mic-compat -mic2.0-compat -mic3.0-compat +-mintel-asm -mno-clean-linkage -mno-code-align +-mno-complex-addr -mno-leaf-procedures +-mno-old-align -mno-strict-align -mno-tail-call +-mnumerics -mold-align -msoft-float -mstrict-align +-mtail-call + +@emph{DEC Alpha Options} +-mfp-regs -mno-fp-regs -mno-soft-float +-msoft-float + +@emph{Clipper Options} +-mc300 -mc400 + +@emph{H8/300 Options} +-mrelax -mh + +@emph{System V Options} +-Qy -Qn -YP,@var{paths} -Ym,@var{dir} +@end smallexample + +@item Code Generation Options +@xref{Code Gen Options,,Options for Code Generation Conventions}. +@smallexample +-fcall-saved-@var{reg} -fcall-used-@var{reg} +-ffixed-@var{reg} -finhibit-size-directive +-fno-common -fno-ident -fno-gnu-linker +-fpcc-struct-return -fpic -fPIC +-freg-struct-return -fshared-data -fshort-enums +-fshort-double -fvolatile -fvolatile-global +-fverbose-asm +e0 +e1 +@end smallexample +@end table + +@menu +* Overall Options:: Controlling the kind of output: + an executable, object files, assembler files, + or preprocessed source. +* C Dialect Options:: Controlling the variant of C language compiled. +* C++ Dialect Options:: Variations on C++. +* Warning Options:: How picky should the compiler be? +* Debugging Options:: Symbol tables, measurements, and debugging dumps. +* Optimize Options:: How much optimization? +* Preprocessor Options:: Controlling header files and macro definitions. + Also, getting dependency information for Make. +* Assembler Options:: Passing options to the assembler. +* Link Options:: Specifying libraries and so on. +* Directory Options:: Where to find header files and libraries. + Where to find the compiler executable files. +* Target Options:: Running a cross-compiler, or an old version of GNU CC. +@end menu + +@node Overall Options +@section Options Controlling the Kind of Output + +Compilation can involve up to four stages: preprocessing, compilation +proper, assembly and linking, always in that order. The first three +stages apply to an individual source file, and end by producing an +object file; linking combines all the object files (those newly +compiled, and those specified as input) into an executable file. + +@cindex file name suffix +For any given input file, the file name suffix determines what kind of +compilation is done: + +@table @code +@item @var{file}.c +C source code which must be preprocessed. + +@item @var{file}.i +C source code which should not be preprocessed. + +@item @var{file}.ii +C++ source code which should not be preprocessed. + +@item @var{file}.m +Objective-C source code. Note that you must link with the library +@file{libobjc.a} to make an Objective-C program work. + +@item @var{file}.h +C header file (not to be compiled or linked). + +@item @var{file}.cc +@itemx @var{file}.cxx +@itemx @var{file}.cpp +@itemx @var{file}.C +C++ source code which must be preprocessed. Note that in @samp{.cxx}, +the last two letters must both be literally @samp{x}. Likewise, +@samp{.C} refers to a literal capital C. + +@item @var{file}.s +Assembler code. + +@item @var{file}.S +Assembler code which must be preprocessed. + +@item @var{other} +An object file to be fed straight into linking. +Any file name with no recognized suffix is treated this way. +@end table + +You can specify the input language explicitly with the @samp{-x} option: + +@table @code +@item -x @var{language} +Specify explicitly the @var{language} for the following input files +(rather than letting the compiler choose a default based on the file +name suffix). This option applies to all following input files until +the next @samp{-x} option. Possible values for @var{language} are: +@example +c objective-c c++ +c-header cpp-output c++-cpp-output +assembler assembler-with-cpp +@end example + +@item -x none +Turn off any specification of a language, so that subsequent files are +handled according to their file name suffixes (as they are if @samp{-x} +has not been used at all). +@end table + +If you only want some of the stages of compilation, you can use +@samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and +one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where +@code{gcc} is to stop. Note that some combinations (for example, +@samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all. + +@table @code +@item -c +Compile or assemble the source files, but do not link. The linking +stage simply is not done. The ultimate output is in the form of an +object file for each source file. + +By default, the object file name for a source file is made by replacing +the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}. + +Unrecognized input files, not requiring compilation or assembly, are +ignored. + +@item -S +Stop after the stage of compilation proper; do not assemble. The output +is in the form of an assembler code file for each non-assembler input +file specified. + +By default, the assembler file name for a source file is made by +replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}. + +Input files that don't require compilation are ignored. + +@item -E +Stop after the preprocessing stage; do not run the compiler proper. The +output is in the form of preprocessed source code, which is sent to the +standard output. + +Input files which don't require preprocessing are ignored. + +@cindex output file option +@item -o @var{file} +Place output in file @var{file}. This applies regardless to whatever +sort of output is being produced, whether it be an executable file, +an object file, an assembler file or preprocessed C code. + +Since only one output file can be specified, it does not make sense to +use @samp{-o} when compiling more than one input file, unless you are +producing an executable file as output. + +If @samp{-o} is not specified, the default is to put an executable file +in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in +@file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and +all preprocessed C source on standard output.@refill + +@item -v +Print (on standard error output) the commands executed to run the stages +of compilation. Also print the version number of the compiler driver +program and of the preprocessor and the compiler proper. + +@item -pipe +Use pipes rather than temporary files for communication between the +various stages of compilation. This fails to work on some systems where +the assembler is unable to read from a pipe; but the GNU assembler has +no trouble. +@end table + +@node Invoking G++ +@section Compiling C++ Programs + +@cindex suffixes for C++ source +@cindex C++ source file suffixes +C++ source files conventionally use one of the suffixes @samp{.C}, +@samp{.cc}, @samp{cpp}, or @samp{.cxx}; preprocessed C++ files use the +suffix @samp{.ii}. GNU CC recognizes files with these names and +compiles them as C++ programs even if you call the compiler the same way +as for compiling C programs (usually with the name @code{gcc}). + +@findex g++ +@findex c++ +However, C++ programs often require class libraries as well as a +compiler that understands the C++ language---and under some +circumstances, you might want to compile programs from standard input, +or otherwise without a suffix that flags them as C++ programs. +@code{g++} is a program that calls GNU CC with the default language +set to C++, and automatically specifies linking against the GNU class +library libg++. +@cindex @code{g++ 1.@var{xx}} +@cindex @code{g++}, separate compiler +@cindex @code{g++} older version +@footnote{Prior to release 2 of the compiler, +there was a separate @code{g++} compiler. That version was based on GNU +CC, but not integrated with it. Versions of @code{g++} with a +@samp{1.@var{xx}} version number---for example, @code{g++} version 1.37 +or 1.42---are much less reliable than the versions integrated with GCC +2. Moreover, combining G++ @samp{1.@var{xx}} with a version 2 GCC will +simply not work.} On many systems, the script @code{g++} is also +installed with the name @code{c++}. + +@cindex invoking @code{g++} +When you compile C++ programs, you may specify many of the same +command-line options that you use for compiling programs in any +language; or command-line options meaningful for C and related +languages; or options that are meaningful only for C++ programs. +@xref{C Dialect Options,,Options Controlling C Dialect}, for +explanations of options for languages related to C. +@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for +explanations of options that are meaningful only for C++ programs. + +@node C Dialect Options +@section Options Controlling C Dialect +@cindex dialect options +@cindex language dialect options +@cindex options, dialect + +The following options control the dialect of C (or languages derived +from C, such as C++ and Objective C) that the compiler accepts: + +@table @code +@cindex ANSI support +@item -ansi +Support all ANSI standard C programs. + +This turns off certain features of GNU C that are incompatible with ANSI +C, such as the @code{asm}, @code{inline} and @code{typeof} keywords, and +predefined macros such as @code{unix} and @code{vax} that identify the +type of system you are using. It also enables the undesirable and +rarely used ANSI trigraph feature, and disallows @samp{$} as part of +identifiers. + +The alternate keywords @code{__asm__}, @code{__extension__}, +@code{__inline__} and @code{__typeof__} continue to work despite +@samp{-ansi}. You would not want to use them in an ANSI C program, of +course, but it is useful to put them in header files that might be included +in compilations done with @samp{-ansi}. Alternate predefined macros +such as @code{__unix__} and @code{__vax__} are also available, with or +without @samp{-ansi}. + +The @samp{-ansi} option does not cause non-ANSI programs to be +rejected gratuitously. For that, @samp{-pedantic} is required in +addition to @samp{-ansi}. @xref{Warning Options}. + +The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi} +option is used. Some header files may notice this macro and refrain +from declaring certain functions or defining certain macros that the +ANSI standard doesn't call for; this is to avoid interfering with any +programs that might use these names for other things. + +The functions @code{alloca}, @code{abort}, @code{exit}, and +@code{_exit} are not builtin functions when @samp{-ansi} is used. + +@item -fno-asm +Do not recognize @code{asm}, @code{inline} or @code{typeof} as a +keyword. These words may then be used as identifiers. You can use the +keywords @code{__asm__}, @code{__inline__} and @code{__typeof__} +instead. @samp{-ansi} implies @samp{-fno-asm}. + +@item -fno-builtin +@cindex builtin functions +@findex abort +@findex abs +@findex alloca +@findex cos +@findex exit +@findex fabs +@findex ffs +@findex labs +@findex memcmp +@findex memcpy +@findex sin +@findex sqrt +@findex strcmp +@findex strcpy +@findex strlen +Don't recognize builtin functions that do not begin with two leading +underscores. Currently, the functions affected include @code{abort}, +@code{abs}, @code{alloca}, @code{cos}, @code{exit}, @code{fabs}, +@code{ffs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{sin}, +@code{sqrt}, @code{strcmp}, @code{strcpy}, and @code{strlen}. + +GCC normally generates special code to handle certain builtin functions +more efficiently; for instance, calls to @code{alloca} may become single +instructions that adjust the stack directly, and calls to @code{memcpy} +may become inline copy loops. The resulting code is often both smaller +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. + +The @samp{-ansi} option prevents @code{alloca} and @code{ffs} from being +builtin functions, since these functions do not have an ANSI standard +meaning. + +@item -trigraphs +Support ANSI C trigraphs. You don't want to know about this +brain-damage. The @samp{-ansi} option implies @samp{-trigraphs}. + +@cindex traditional C language +@cindex C language, traditional +@item -traditional +Attempt to support some aspects of traditional C compilers. +Specifically: + +@itemize @bullet +@item +All @code{extern} declarations take effect globally even if they +are written inside of a function definition. This includes implicit +declarations of functions. + +@item +The 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 ANSI 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 +@samp{-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 ANSI C: automatic variables +not declared @code{volatile} may be clobbered. + +@item +@kindex \x +@kindex \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{@samp{-traditional}}, @samp{\x} is a prefix for the hexadecimal +representation of a character, and @samp{\a} produces a bell. + +@item +In C++ programs, assignment to @code{this} is permitted with +@samp{-traditional}. (The option @samp{-fthis-is-variable} also has +this effect.) +@end itemize + +You may wish to use @samp{-fno-builtin} as well as @samp{-traditional} +if your program uses names that are normally GNU C builtin functions for +other purposes of its own. + +You cannot use @samp{-traditional} if you include any header files that +rely on ANSI C features. Some vendors are starting to ship systems with +ANSI C header files and you cannot use @samp{-traditional} on such +systems to compile files that include any system headers. + +@item +In the preprocessor, comments convert to nothing at all, rather than +to a space. This allows traditional token concatenation. + +@item +In preprocessor directive, the @samp{#} symbol must appear as the first +character of a line. + +@item +In the preprocessor, macro arguments are recognized within string +constants in a macro definition (and their values are stringified, +though without additional quote marks, when they appear in such a +context). The preprocessor always considers a string constant to end +at a newline. + +@item +@cindex detecting @w{@samp{-traditional}} +The predefined macro @code{__STDC__} is not defined when you use +@samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions +which @code{__GNUC__} indicates are not affected by +@samp{-traditional}). If you need to write header files that work +differently depending on whether @samp{-traditional} is in use, by +testing both of these predefined macros you can distinguish four +situations: GNU C, traditional GNU C, other ANSI C compilers, and other +old C compilers. @xref{Standard Predefined,,Standard Predefined +Macros,cpp.info,The C Preprocessor}, for more discussion of these and other +predefined macros. + +@item +@cindex string constants vs newline +@cindex newline vs string constants +The preprocessor considers a string constant to end at a newline (unless +the newline is escaped with @samp{\}). (Without @w{@samp{-traditional}}, +string constants can contain the newline character as typed.) + +@item -traditional-cpp +Attempt to support some aspects of traditional C preprocessors. +This includes the last five items in the table immediately above, +but none of the other effects of @samp{-traditional}. + +@item -fcond-mismatch +Allow conditional expressions with mismatched types in the second and +third arguments. The value of such an expression is void. + +@item -funsigned-char +Let the type @code{char} be unsigned, like @code{unsigned char}. + +Each kind of machine has a default for what @code{char} should +be. It is either like @code{unsigned char} by default or like +@code{signed char} by default. + +Ideally, a portable program should always use @code{signed char} or +@code{unsigned char} when it depends on the signedness of an object. +But many programs have been written to use plain @code{char} and +expect it to be signed, or expect it to be unsigned, depending on the +machines they were written for. This option, and its inverse, let you +make such a program work with the opposite default. + +The type @code{char} is always a distinct type from each of +@code{signed char} or @code{unsigned char}, even though its behavior +is always just like one of those two. + +@item -fsigned-char +Let the type @code{char} be signed, like @code{signed char}. + +Note that this is equivalent to @samp{-fno-unsigned-char}, which is +the negative form of @samp{-funsigned-char}. Likewise, the option +@samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}. + +@item -fsigned-bitfields +@itemx -funsigned-bitfields +@itemx -fno-signed-bitfields +@itemx -fno-unsigned-bitfields +These options control whether a bitfield is signed or unsigned, when the +declaration does not use either @code{signed} or @code{unsigned}. By +default, such a bitfield is signed, because this is consistent: the +basic integer types such as @code{int} are signed types. + +However, when @samp{-traditional} is used, bitfields are all unsigned +no matter what. + +@item -fwritable-strings +Store string constants in the writable data segment and don't uniquize +them. This is for compatibility with old programs which assume they can +write into string constants. The option @samp{-traditional} also has +this effect. + +Writing into string constants is a very bad idea; ``constants'' should +be constant. + +@item -fallow-single-precision +Do not promote single precision math operations to double precision, +even when compiling with @samp{-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 @samp{-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 ANSI or GNU C conventions (the default). + +@end table + +@node C++ Dialect Options +@section Options Controlling C++ Dialect + +@cindex compiler options, C++ +@cindex C++ options, command line +@cindex options, C++ +This section describes the command-line options that are only meaningful +for C++ programs; but you can also use most of the GNU compiler options +regardless of what language your program is in. For example, you +might compile a file @code{firstClass.C} like this: + +@example +g++ -g -felide-constructors -O -c firstClass.C +@end example + +@noindent +In this example, only @samp{-felide-constructors} is an option meant +only for C++ programs; you can use the other options with any +language supported by GNU CC. + +Here is a list of options that are @emph{only} for compiling C++ programs: + +@table @code +@item -fno-access-control +Turn off all access checking. This switch is mainly useful for working +around bugs in the access control code. + +@item -fall-virtual +Treat all possible member functions as virtual, implicitly. +All member functions (except for constructor functions and @code{new} or +@code{delete} member operators) are treated as virtual functions of the +class where they appear. + +This does not mean that all calls to these member functions will be made +through the internal table of virtual functions. Under some +circumstances, the compiler can determine that a call to a given virtual +function can be made directly; in these cases the calls are direct in +any case. + +@item -fconserve-space +Put uninitialized or runtime-initialized global variables into the +common segment, as C does. This saves space in the executable at the +cost of not diagnosing duplicate definitions. If your program +mysteriously crashes after @code{main()} has completed, you may have an +object that is being destroyed twice because two definitions were merged. + +@item -fdollars-in-identifiers +Accept @samp{$} in identifiers. You can also explicitly prohibit use of +@samp{$} with the option @samp{-fno-dollars-in-identifiers}. (GNU C++ +allows @samp{$} by default on some target systems but not others.) +Traditional C allowed the character @samp{$} to form part of +identifiers. However, ANSI C and C++ forbid @samp{$} in identifiers. + +@item -fenum-int-equiv +Permit implicit conversion of @code{int} to enumeration types. Normally +GNU C++ allows conversion of @code{enum} to @code{int}, but not the +other way around. + +@item -fexternal-templates +Cause template instantiations to obey @samp{#pragma interface} and +@samp{implementation}; template instances are emitted or not according +to the location of the template definition. @xref{Template +Instantiation}, for more information. + +@item -falt-external-templates +Similar to -fexternal-templates, but template instances are emitted or +not according to the place where they are first instantiated. +@xref{Template Instantiation}, for more information. + +@item -fno-implicit-templates +Never emit code for templates which are instantiated implicitly (i.e. by +use); only emit code for explicit instantiations. @xref{Template +Instantiation}, for more information. + +@item -fhandle-signatures +Recognize the @code{signature} and @code{sigof} keywords for specifying +abstract types. The default (@samp{-fno-handle-signatures}) is not to +recognize them. @xref{C++ Signatures, Type Abstraction using +Signatures}. + +@item -fhuge-objects +Support virtual function calls for objects that exceed the size +representable by a @samp{short int}. Users should not use this flag by +default; if you need to use it, the compiler will tell you so. If you +compile any of your code with this flag, you must compile @emph{all} of +your code with this flag (including libg++, if you use it). + +This flag is not useful when compiling with -fvtable-thunks. + +@item -fno-implement-inlines +To save space, do not emit out-of-line copies of inline functions +controlled by @samp{#pragma implementation}. This will cause linker +errors if these functions are not inlined everywhere they are called. + +@item -fmemoize-lookups +@itemx -fsave-memoized +Use heuristics to compile faster. These heuristics are not enabled by +default, since they are only effective for certain input files. Other +input files compile more slowly. + +The first time the compiler must build a call to a member function (or +reference to a data member), it must (1) determine whether the class +implements member functions of that name; (2) resolve which member +function to call (which involves figuring out what sorts of type +conversions need to be made); and (3) check the visibility of the member +function to the caller. All of this adds up to slower compilation. +Normally, the second time a call is made to that member function (or +reference to that data member), it must go through the same lengthy +process again. This means that code like this: + +@smallexample +cout << "This " << p << " has " << n << " legs.\n"; +@end smallexample + +@noindent +makes six passes through all three steps. By using a software cache, a +``hit'' significantly reduces this cost. Unfortunately, using the cache +introduces another layer of mechanisms which must be implemented, and so +incurs its own overhead. @samp{-fmemoize-lookups} enables the software +cache. + +Because access privileges (visibility) to members and member functions +may differ from one function context to the next, G++ may need to flush +the cache. With the @samp{-fmemoize-lookups} flag, the cache is flushed +after every function that is compiled. The @samp{-fsave-memoized} flag +enables the same software cache, but when the compiler determines that +the context of the last function compiled would yield the same access +privileges of the next function to compile, it preserves the cache. +This is most helpful when defining many member functions for the same +class: with the exception of member functions which are friends of other +classes, each member function has exactly the same access privileges as +every other, and the cache need not be flushed. + +@item -fno-strict-prototype +Treat a function declaration with no arguments, such as @samp{int foo +();}, as C would treat it---as saying nothing about the number of +arguments or their types. Normally, such a declaration in C++ means +that the function @code{foo} takes no arguments. + +This option does not work with operator overloading, which places +constraints on the parameter types. + +@item -fnonnull-objects +Assume that objects reached through references are not null. + +Normally, GNU C++ makes conservative assumptions about objects reached +through references. For example, the compiler must check that @code{a} +is not null in code like the following: + +@example +obj &a = g (); +a.f (2); +@end example + +Checking that references of this sort have non-null values requires +extra code, however, and it is unnecessary for many programs. You can +use @w{@samp{-fnonnull-objects}} to omit the checks for null, if your +program doesn't require checking. + +This checking is currently only done for conversions to virtual base classes. + +@item -fthis-is-variable +Permit assignment to @code{this}. The incorporation of user-defined +free store management into C++ has made assignment to @samp{this} an +anachronism. Therefore, by default it is invalid to assign to +@code{this} within a class member function; that is, GNU C++ treats +@samp{this} in a member function of class @code{X} as a non-lvalue of +type @samp{X *}. However, for backwards compatibility, you can make it +valid with @samp{-fthis-is-variable}. + +@item -fvtable-thunks +Use @samp{thunks} to implement the virtual function dispatch table +(@samp{vtable}). The traditional (cfront-style) approach to +implementing vtables was to store a pointer to the function and two +offsets for adjusting the @samp{this} pointer at the call site. Newer +implementations store a single pointer to a @samp{thunk} function which +does any necessary adjustment and then calls the target function. + +This option also enables a heuristic for controlling emission of +vtables; if a class has any non-inline virtual functions, the vtable +will be emitted in the translation unit containing the first one of +those. + +@item -nostdinc++ +Do not search for header files in the standard directories specific to +C++, but do still search the other standard directories. (This option +is used when building libg++.) + +@item -traditional +For C++ programs (in addition to the effects that apply to both C and +C++), this has the same effect as @samp{-fthis-is-variable}. +@xref{C Dialect Options,, Options Controlling C Dialect}. +@end table + +In addition, these optimization, warning, and code generation options +have meanings only for C++ programs: + +@table @code +@item -fno-default-inline +Do not assume @samp{inline} for functions defined inside a class scope. +@xref{Optimize Options,,Options That Control Optimization}. + +@item -Wenum-clash +@itemx -Woverloaded-virtual +@itemx -Wtemplate-debugging +Warnings that apply only to C++ programs. @xref{Warning +Options,,Options to Request or Suppress Warnings}. + +@item +e@var{n} +Control how virtual function definitions are used, in a fashion +compatible with @code{cfront} 1.x. @xref{Code Gen Options,,Options for +Code Generation Conventions}. +@end table + +@node Warning Options +@section Options to Request or Suppress Warnings +@cindex options to control warnings +@cindex warning messages +@cindex messages, warning +@cindex suppressing warnings + +Warnings are diagnostic messages that report constructions which +are not inherently erroneous but which are risky or suggest there +may have been an error. + +You can request many specific warnings with options beginning @samp{-W}, +for example @samp{-Wimplicit} to request warnings on implicit +declarations. Each of these specific warning options also has a +negative form beginning @samp{-Wno-} to turn off warnings; +for example, @samp{-Wno-implicit}. This manual lists only one of the +two forms, whichever is not the default. + +These options control the amount and kinds of warnings produced by GNU +CC: + +@table @code +@cindex syntax checking +@item -fsyntax-only +Check the code for syntax errors, but don't do anything beyond that. + +@item -w +Inhibit all warning messages. + +@item -Wno-import +Inhibit warning messages about the use of @samp{#import}. + +@item -pedantic +Issue all the warnings demanded by strict ANSI standard C; reject +all programs that use forbidden extensions. + +Valid ANSI standard C programs should compile properly with or without +this option (though a rare few will require @samp{-ansi}). However, +without this option, certain GNU extensions and traditional C features +are supported as well. With this option, they are rejected. + +@samp{-pedantic} does not cause warning messages for use of the +alternate keywords whose names begin and end with @samp{__}. Pedantic +warnings are also disabled in the expression that follows +@code{__extension__}. However, only system header files should use +these escape routes; application programs should avoid them. +@xref{Alternate Keywords}. + +This option is not intended to be @i{useful}; it exists only to satisfy +pedants who would otherwise claim that GNU CC fails to support the ANSI +standard. + +Some users try to use @samp{-pedantic} to check programs for strict ANSI +C conformance. They soon find that it does not do quite what they want: +it finds some non-ANSI practices, but not all---only those for which +ANSI C @emph{requires} a diagnostic. + +A feature to report any failure to conform to ANSI C might be useful in +some instances, but would require considerable additional work and would +be quite different from @samp{-pedantic}. We recommend, rather, that +users take advantage of the extensions of GNU C and disregard the +limitations of other compilers. Aside from certain supercomputers and +obsolete small machines, there is less and less reason ever to use any +other C compiler other than for bootstrapping GNU CC. + +@item -pedantic-errors +Like @samp{-pedantic}, except that errors are produced rather than +warnings. + +@item -W +Print extra warning messages for these events: + +@itemize @bullet +@cindex @code{longjmp} warnings +@item +A nonvolatile automatic variable might be changed by a call to +@code{longjmp}. These warnings as well are possible only in +optimizing compilation. + +The compiler sees only the calls to @code{setjmp}. It cannot know +where @code{longjmp} will be called; in fact, a signal handler could +call it at any point in the code. As a result, you may get a warning +even when there is in fact no problem because @code{longjmp} cannot +in fact be called at the place which would cause a problem. + +@item +A function can return either with or without a value. (Falling +off the end of the function body is considered returning without +a value.) For example, this function would evoke such a +warning: + +@smallexample +@group +foo (a) +@{ + if (a > 0) + return a; +@} +@end group +@end smallexample + +@item +An expression-statement contains no side effects. + +@item +An unsigned value is compared against zero with @samp{<} or @samp{<=}. + +@item +A comparison like @samp{x<=y<=z} appears; this is equivalent to +@samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from +that of ordinary mathematical notation. + +@item +Storage-class specifiers like @code{static} are not the first things in +a declaration. According to the C Standard, this usage is obsolescent. + +@item +An aggregate has a partly bracketed initializer. +For example, the following code would evoke such a warning, +because braces are missing around the initializer for @code{x.h}: + +@smallexample +struct s @{ int f, g; @}; +struct t @{ struct s h; int i; @}; +struct t x = @{ 1, 2, 3 @}; +@end smallexample +@end itemize + +@item -Wimplicit +Warn whenever a function or parameter is implicitly declared. + +@item -Wreturn-type +Warn whenever a function is defined with a return-type that defaults +to @code{int}. Also warn about any @code{return} statement with no +return-value in a function whose return-type is not @code{void}. + +@item -Wunused +Warn whenever a variable is unused aside from its declaration, +whenever a function is declared static but never defined, whenever a +label is declared but not used, and whenever a statement computes a +result that is explicitly not used. + +To suppress this warning for a local variable or expression, simply cast +it to void. This will also work for file-scope variables, but if you +want to mark them used at the point of definition, you can use this +macro: + +@smallexample +#define USE(var) \ + static void *const use_##var = (&use_##var, &var, 0) + +USE (string); +@end smallexample + +@item -Wswitch +Warn whenever a @code{switch} statement has an index of enumeral type +and lacks a @code{case} for one or more of the named codes of that +enumeration. (The presence of a @code{default} label prevents this +warning.) @code{case} labels outside the enumeration range also +provoke warnings when this option is used. + +@item -Wcomment +Warn whenever a comment-start sequence @samp{/*} appears in a comment. + +@item -Wtrigraphs +Warn if any trigraphs are encountered (assuming they are enabled). + +@item -Wformat +Check calls to @code{printf} and @code{scanf}, etc., to make sure that +the arguments supplied have types appropriate to the format string +specified. + +@item -Wchar-subscripts +Warn if an array subscript has type @code{char}. This is a common cause +of error, as programmers often forget that this type is signed on some +machines. + +@item -Wuninitialized +An automatic variable is used without first being initialized. + +These warnings are possible only in optimizing compilation, +because they require data flow information that is computed only +when optimizing. If you don't specify @samp{-O}, you simply won't +get these warnings. + +These warnings occur only for variables that are candidates for +register allocation. Therefore, they do not occur for a variable that +is declared @code{volatile}, or whose address is taken, or whose size +is other than 1, 2, 4 or 8 bytes. Also, they do not occur for +structures, unions or arrays, even when they are in registers. + +Note that there may be no warning about a variable that is used only +to compute a value that itself is never used, because such +computations may be deleted by data flow analysis before the warnings +are printed. + +These warnings are made optional because GNU CC is not smart +enough to see all the reasons why the code might be correct +despite appearing to have an error. Here is one example of how +this can happen: + +@smallexample +@{ + int x; + switch (y) + @{ + case 1: x = 1; + break; + case 2: x = 4; + break; + case 3: x = 5; + @} + foo (x); +@} +@end smallexample + +@noindent +If the value of @code{y} is always 1, 2 or 3, then @code{x} is +always initialized, but GNU CC doesn't know this. Here is +another common case: + +@smallexample +@{ + int save_y; + if (change_y) save_y = y, y = new_y; + @dots{} + if (change_y) y = save_y; +@} +@end smallexample + +@noindent +This has no bug because @code{save_y} is used only if it is set. + +Some spurious warnings can be avoided if you declare all the functions +you use that never return as @code{noreturn}. @xref{Function +Attributes}. + +@item -Wparentheses +Warn if parentheses are omitted in certain contexts, such +as when there is an assignment in a context where a truth value +is expected, or when operators are nested whose precedence people +often get confused about. + +@item -Wenum-clash +@cindex enumeration clash warnings +@cindex warning for enumeration conversions +Warn about conversion between different enumeration types. +(C++ only). + +@item -Wtemplate-debugging +@cindex template debugging +When using templates in a C++ program, warn if debugging is not yet +fully available (C++ only). + +@item -Wreorder (C++ only) +@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: + +@smallexample +struct A @{ + int i; + int j; + A(): j (0), i (1) @{ @} +@}; +@end smallexample + +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. + +@item -Wall +All of the above @samp{-W} options combined. These are all the +options which pertain to usage that we recommend avoiding and that we +believe is easy to avoid, even in conjunction with macros. +@end table + +The remaining @samp{-W@dots{}} options are not implied by @samp{-Wall} +because they warn about constructions that we consider reasonable to +use, on occasion, in clean programs. + +@table @code +@item -Wtraditional +Warn about certain constructs that behave differently in traditional and +ANSI C. + +@itemize @bullet +@item +Macro arguments occurring within string constants in the macro body. +These would substitute the argument in traditional C, but are part of +the constant in ANSI C. + +@item +A function declared external in one block and then used after the end of +the block. + +@item +A @code{switch} statement has an operand of type @code{long}. +@end itemize + +@item -Wshadow +Warn whenever a local variable shadows another local variable. + +@item -Wid-clash-@var{len} +Warn whenever two distinct identifiers match in the first @var{len} +characters. This may help you prepare a program that will compile +with certain obsolete, brain-damaged compilers. + +@item -Wlarger-than-@var{len} +Warn whenever an object of larger than @var{len} bytes is defined. + +@item -Wpointer-arith +Warn about anything that depends on the ``size of'' a function type or +of @code{void}. GNU C assigns these types a size of 1, for +convenience in calculations with @code{void *} pointers and pointers +to functions. + +@item -Wbad-function-cast +Warn whenever a function call is cast to a non-matching type. +For example, warn if @code{int malloc()} is cast to @code{anything *}. + +@item -Wcast-qual +Warn whenever a pointer is cast so as to remove a type qualifier from +the target type. For example, warn if a @code{const char *} is cast +to an ordinary @code{char *}. + +@item -Wcast-align +Warn whenever a pointer is cast such that the required alignment of the +target is increased. For example, warn if a @code{char *} is cast to +an @code{int *} on machines where integers can only be accessed at +two- or four-byte boundaries. + +@item -Wwrite-strings +Give string constants the type @code{const char[@var{length}]} so that +copying the address of one into a non-@code{const} @code{char *} +pointer will get a warning. These warnings will help you find at +compile time code that can try to write into a string constant, but +only if you have been very careful about using @code{const} in +declarations and prototypes. Otherwise, it will just be a nuisance; +this is why we did not make @samp{-Wall} request these warnings. + +@item -Wconversion +Warn if a prototype causes a type conversion that is different from what +would happen to the same argument in the absence of a prototype. This +includes conversions of fixed point to floating and vice versa, and +conversions changing the width or signedness of a fixed point argument +except when the same as the default promotion. + +Also, warn if a negative integer constant expression is implicitly +converted to an unsigned type. For example, warn about the assignment +@code{x = -1} if @code{x} is unsigned. But do not warn about explicit +casts like @code{(unsigned) -1}. + +@item -Waggregate-return +Warn if any functions that return structures or unions are defined or +called. (In languages where you can return an array, this also elicits +a warning.) + +@item -Wstrict-prototypes +Warn if a function is declared or defined without specifying the +argument types. (An old-style function definition is permitted without +a warning if preceded by a declaration which specifies the argument +types.) + +@item -Wmissing-prototypes +Warn if a global function is defined without a previous prototype +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 +Warn if a global function is defined without a previous declaration. +Do so even if the definition itself provides a prototype. +Use this option to detect global functions that are not declared in +header files. + +@item -Wredundant-decls +Warn if anything is declared more than once in the same scope, even in +cases where multiple declaration is valid and changes nothing. + +@item -Wnested-externs +Warn if an @code{extern} declaration is encountered within an function. + +@item -Winline +Warn if a function can not be inlined, and either it was declared as inline, +or else the @samp{-finline-functions} option was given. + +@item -Woverloaded-virtual +@cindex overloaded virtual fn, warning +@cindex warning for overloaded virtual fn +Warn when a derived class function declaration may be an error in +defining a virtual function (C++ only). In a derived class, the +definitions of virtual functions must match the type signature of a +virtual function declared in the base class. With this option, the +compiler warns when you define a function with the same name as a +virtual function, but with a type signature that does not match any +declarations from the base class. + +@item -Wsynth (C++ only) +@cindex warning for synthesized methods +@cindex synthesized methods, warning +Warn when g++'s synthesis behavior does not match that of cfront. For +instance: + +@smallexample +struct A @{ + operator int (); + A& operator = (int); +@}; + +main () +@{ + A a,b; + a = b; +@} +@end smallexample + +In this example, g++ will synthesize a default @samp{A& operator = +(const A&);}, while cfront will use the user-defined @samp{operator =}. + +@item -Werror +Make all warnings into errors. +@end table + +@node Debugging Options +@section Options for Debugging Your Program or GNU CC +@cindex options, debugging +@cindex debugging information options + +GNU CC has various special options that are used for debugging +either your program or GCC: + +@table @code +@item -g +Produce debugging information in the operating system's native format +(stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging +information. + +On most systems that use stabs format, @samp{-g} enables use of extra +debugging information that only GDB can use; this extra information +makes debugging work better in GDB but will probably make other debuggers +crash or +refuse to read the program. If you want to control for certain whether +to generate the extra information, use @samp{-gstabs+}, @samp{-gstabs}, +@samp{-gxcoff+}, @samp{-gxcoff}, @samp{-gdwarf+}, or @samp{-gdwarf} +(see below). + +Unlike most other C compilers, GNU CC allows you to use @samp{-g} with +@samp{-O}. The shortcuts taken by optimized code may occasionally +produce surprising results: some variables you declared may not exist +at all; flow of control may briefly move where you did not expect it; +some statements may not be executed because they compute constant +results or their values were already at hand; some statements may +execute in different places because they were moved out of loops. + +Nevertheless it proves possible to debug optimized output. This makes +it reasonable to use the optimizer for programs that might have bugs. + +The following options are useful when GNU CC is generated with the +capability for more than one debugging format. + +@item -ggdb +Produce debugging information in the native format (if that is supported), +including GDB extensions if at all possible. + +@item -gstabs +Produce debugging information in stabs format (if that is supported), +without GDB extensions. This is the format used by DBX on most BSD +systems. On MIPS, Alpha and System V Release 4 systems this option +produces stabs debugging output which is not understood by DBX or SDB. +On System V Release 4 systems this option requires the GNU assembler. + +@item -gstabs+ +Produce debugging information in stabs format (if that is 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. + +@item -gcoff +Produce debugging information in COFF format (if that is supported). +This is the format used by SDB on most System V systems prior to +System V Release 4. + +@item -gxcoff +Produce debugging information in XCOFF format (if that is supported). +This is the format used by the DBX debugger on IBM RS/6000 systems. + +@item -gxcoff+ +Produce debugging information in XCOFF format (if that is 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. + +@item -gdwarf +Produce debugging information in DWARF format (if that is supported). +This is the format used by SDB on most System V Release 4 systems. + +@item -gdwarf+ +Produce debugging information in DWARF format (if that is 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. + +@item -g@var{level} +@itemx -ggdb@var{level} +@itemx -gstabs@var{level} +@itemx -gcoff@var{level} +@itemx -gxcoff@var{level} +@itemx -gdwarf@var{level} +Request debugging information and also use @var{level} to specify how +much information. The default level is 2. + +Level 1 produces minimal information, enough for making backtraces in +parts of the program that you don't plan to debug. This includes +descriptions of functions and external variables, but no information +about local variables and no line numbers. + +Level 3 includes extra information, such as all the macro definitions +present in the program. Some debuggers support macro expansion when +you use @samp{-g3}. + +@cindex @code{prof} +@item -p +Generate extra code to write profile information suitable for the +analysis program @code{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} +@item -pg +Generate extra code to write profile information suitable for the +analysis program @code{gprof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. + +@cindex @code{tcov} +@item -a +Generate extra code to write profile information for basic blocks, which will +record the number of times each basic block is executed, the basic block start +address, and the function name containing the basic block. If @samp{-g} is +used, the line number and filename of the start of the basic block will also be +recorded. If not overridden by the machine description, the default action is +to append to the text file @file{bb.out}. + +This data could be analyzed by a program like @code{tcov}. Note, +however, that the format of the data is not what @code{tcov} expects. +Eventually GNU @code{gprof} should be extended to process this data. + +@item -d@var{letters} +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 word to the source file +name (e.g. @file{foo.c.rtl} or @file{foo.c.jump}). Here are the +possible letters for use in @var{letters}, and their meanings: + +@table @samp +@item M +Dump all macro definitions, at the end of preprocessing, and write no +output. +@item N +Dump all macro names, at the end of preprocessing. +@item D +Dump all macro definitions, at the end of preprocessing, in addition to +normal output. +@item y +Dump debugging information during parsing, to standard error. +@item r +Dump after RTL generation, to @file{@var{file}.rtl}. +@item x +Just generate RTL for a function instead of compiling it. Usually used +with @samp{r}. +@item j +Dump after first jump optimization, to @file{@var{file}.jump}. +@item s +Dump after CSE (including the jump optimization that sometimes +follows CSE), to @file{@var{file}.cse}. +@item L +Dump after loop optimization, to @file{@var{file}.loop}. +@item t +Dump after the second CSE pass (including the jump optimization that +sometimes follows CSE), to @file{@var{file}.cse2}. +@item f +Dump after flow analysis, to @file{@var{file}.flow}. +@item c +Dump after instruction combination, to the file +@file{@var{file}.combine}. +@item S +Dump after the first instruction scheduling pass, to +@file{@var{file}.sched}. +@item l +Dump after local register allocation, to +@file{@var{file}.lreg}. +@item g +Dump after global register allocation, to +@file{@var{file}.greg}. +@item R +Dump after the second instruction scheduling pass, to +@file{@var{file}.sched2}. +@item J +Dump after last jump optimization, to @file{@var{file}.jump2}. +@item d +Dump after delayed branch scheduling, to @file{@var{file}.dbr}. +@item k +Dump after conversion from registers to stack, to @file{@var{file}.stack}. +@item a +Produce all the dumps listed above. +@item m +Print statistics on memory usage, at the end of the run, to +standard error. +@item p +Annotate the assembler output with a comment indicating which +pattern and alternative was used. +@end table + +@item -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 GNU CC would make when running on +the target machine. + +@item -save-temps +Store the usual ``temporary'' intermediate files permanently; place them +in the current directory and name them based on the source file. Thus, +compiling @file{foo.c} with @samp{-c -save-temps} would produce files +@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. + +@item -print-file-name=@var{library} +Print the full absolute name of the library file @var{library} that +would be used when linking---and don't do anything else. With this +option, GNU CC does not compile or link anything; it just prints the +file name. + +@item -print-prog-name=@var{program} +Like @samp{-print-file-name}, but searches for a program such as @samp{cpp}. + +@item -print-libgcc-file-name +Same as @samp{-print-file-name=libgcc.a}. + +This is useful when you use @samp{-nostdlib} but you do want to link +with @file{libgcc.a}. You can do + +@example +gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name` +@end example +@end table + +@node Optimize Options +@section Options That Control Optimization +@cindex optimize options +@cindex options, optimization + +These options control various sorts of optimizations: + +@table @code +@item -O +@itemx -O1 +Optimize. Optimizing compilation takes somewhat more time, and a lot +more memory for a large function. + +Without @samp{-O}, the compiler's goal is to reduce the cost of +compilation and to make debugging produce the expected results. +Statements are independent: if you stop the program with a breakpoint +between statements, you can then assign a new value to any variable or +change the program counter to any other statement in the function and +get exactly the results you would expect from the source code. + +Without @samp{-O}, the compiler only allocates variables declared +@code{register} in registers. The resulting compiled code is a little +worse than produced by PCC without @samp{-O}. + +With @samp{-O}, the compiler tries to reduce code size and execution +time. + +When you specify @samp{-O}, the compiler turns on @samp{-fthread-jumps} +and @samp{-fdefer-pop} on all machines. The compiler turns on +@samp{-fdelayed-branch} on machines that have delay slots, and +@samp{-fomit-frame-pointer} on machines that can support debugging even +without a frame pointer. On some machines the compiler also turns +on other flags.@refill + +@item -O2 +Optimize even more. GNU CC performs nearly all supported optimizations +that do not involve a space-speed tradeoff. The compiler does not +perform loop unrolling or function inlining when you specify @samp{-O2}. +As compared to @samp{-O}, this option increases both compilation time +and the performance of the generated code. + +@samp{-O2} turns on all optional optimizations except for loop unrolling +and function inlining. It also turns on frame pointer elimination on +machines where doing so does not interfer with debugging. + +@item -O3 +Optimize yet more. @samp{-O3} turns on all optimizations specified by +@samp{-O2} and also turns on the @samp{inline-functions} option. + +@item -O0 +Do not optimize. + +If you use multiple @samp{-O} options, with or without level numbers, +the last such option is the one that is effective. +@end table + +Options of the form @samp{-f@var{flag}} specify machine-independent +flags. Most flags have both positive and negative forms; the negative +form of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, +only one of the forms is listed---the one which is not the default. +You can figure out the other form by either removing @samp{no-} or +adding it. + +@table @code +@item -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. + +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. For most programs, +the excess precision does only good, but a few programs rely on the +precise definition of IEEE floating point. Use @samp{-ffloat-store} for +such programs. + +@item -fno-default-inline +Do not make member functions inline by default merely because they are +defined inside the class scope (C++ only). Otherwise, when you specify +@w{@samp{-O}}, member functions defined inside class scope are compiled +inline by default; i.e., you don't need to add @samp{inline} in front of +the member function name. + +@item -fno-defer-pop +Always pop the arguments to each function call as soon as that function +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. + +@item -fforce-mem +Force memory operands to be copied into registers before doing +arithmetic on them. This may produce better code by making all +memory references potential common subexpressions. When they are +not common subexpressions, instruction combination should +eliminate the separate register-load. I am interested in hearing +about the difference this makes. + +@item -fforce-addr +Force memory address constants to be copied into registers before +doing arithmetic on them. This may produce better code just as +@samp{-fforce-mem} may. I am interested in hearing about the +difference this makes. + +@item -fomit-frame-pointer +Don't keep the frame pointer in a register for functions that +don't need one. This avoids the instructions to save, set up and +restore frame pointers; it also makes an extra register available +in many functions. @strong{It also makes debugging impossible on +some machines.} + +@ifset INTERNALS +On some machines, such as the Vax, this flag has no effect, because +the standard calling sequence automatically handles the frame pointer +and nothing is saved by pretending it doesn't exist. The +machine-description macro @code{FRAME_POINTER_REQUIRED} controls +whether a target machine supports this flag. @xref{Registers}.@refill +@end ifset +@ifclear INTERNALS +On some machines, such as the Vax, this flag has no effect, because +the standard calling sequence automatically handles the frame pointer +and nothing is saved by pretending it doesn't exist. The +machine-description macro @code{FRAME_POINTER_REQUIRED} controls +whether a target machine supports this flag. @xref{Registers,,Register +Usage, gcc.info, Using and Porting GCC}.@refill +@end ifclear + +@item -fno-inline +Don't pay attention to the @code{inline} keyword. Normally this option +is used to keep the compiler from expanding any functions inline. +Note that if you are not optimizing, no functions can be expanded inline. + +@item -finline-functions +Integrate all simple functions into their callers. The compiler +heuristically decides which functions are simple enough to be worth +integrating in this way. + +If all calls to a given function are integrated, and the function is +declared @code{static}, then the function is normally not output as +assembler code in its own right. + +@item -fkeep-inline-functions +Even if all calls to a given function are integrated, and the function +is declared @code{static}, nevertheless output a separate run-time +callable version of the function. + +@item -fno-function-cse +Do not put function addresses in registers; make each instruction that +calls a constant function contain the function's address explicitly. + +This option results in less efficient code, but some strange hacks +that alter the assembler output may be confused by the optimizations +performed when this option is not used. + +@item -ffast-math +This option allows GCC to violate some ANSI or IEEE rules and/or +specifications in the interest of optimizing code for speed. For +example, it allows the compiler to assume arguments to the @code{sqrt} +function are non-negative numbers and that no floating-point values +are NaNs. + +This option should never be turned on by any @samp{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ANSI rules/specifications for +math functions. +@end table + +@c following causes underfulls.. they don't look great, but we deal. +@c --mew 26jan93 +The following options control specific optimizations. The @samp{-O2} +option turns on all of these optimizations except @samp{-funroll-loops} +and @samp{-funroll-all-loops}. On most machines, the @samp{-O} option +turns on the @samp{-fthread-jumps} and @samp{-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. + +@table @code +@item -fstrength-reduce +Perform the optimizations of loop strength reduction and +elimination of iteration variables. + +@item -fthread-jumps +Perform optimizations where we check to see if a jump branches to a +location where another comparison subsumed by the first is found. If +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. + +@item -fcse-follow-jumps +In common subexpression elimination, scan through jump instructions +when the target of the jump is not reached by any other path. For +example, when CSE encounters an @code{if} statement with an +@code{else} clause, CSE will follow the jump when the condition +tested is false. + +@item -fcse-skip-blocks +This is similar to @samp{-fcse-follow-jumps}, but causes CSE to +follow jumps which conditionally skip over blocks. When CSE +encounters a simple @code{if} statement with no else clause, +@samp{-fcse-skip-blocks} causes CSE to follow the jump around the +body of the @code{if}. + +@item -frerun-cse-after-loop +Re-run common subexpression elimination after loop optimizations has been +performed. + +@item -fexpensive-optimizations +Perform a number of minor optimizations that are relatively expensive. + +@item -fdelayed-branch +If supported for the target machine, attempt to reorder instructions +to exploit instruction slots available after delayed branch +instructions. + +@item -fschedule-insns +If supported for the target machine, attempt to reorder instructions to +eliminate execution stalls due to required data being unavailable. This +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. + +@item -fschedule-insns2 +Similar to @samp{-fschedule-insns}, but requests an additional pass of +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. + +@item -fcaller-saves +Enable values to be allocated in registers that will be clobbered by +function calls, by emitting extra instructions to save and restore the +registers around such calls. Such allocation is done only when it +seems to result in better code than would otherwise be produced. + +This option is enabled by default on certain machines, usually those +which have no call-preserved registers to use instead. + +@item -funroll-loops +Perform the optimization of loop unrolling. This is only done for loops +whose number of iterations can be determined at compile time or run time. +@samp{-funroll-loop} implies both @samp{-fstrength-reduce} and +@samp{-frerun-cse-after-loop}. + +@item -funroll-all-loops +Perform the optimization of loop unrolling. This is done for all loops +and usually makes programs run more slowly. @samp{-funroll-all-loops} +implies @samp{-fstrength-reduce} as well as @samp{-frerun-cse-after-loop}. + +@item -fno-peephole +Disable any machine-specific peephole optimizations. +@end table + +@node Preprocessor Options +@section Options Controlling the Preprocessor +@cindex preprocessor options +@cindex options, preprocessor + +These options control the C preprocessor, which is run on each C source +file before actual compilation. + +If you use the @samp{-E} option, nothing is done except preprocessing. +Some of these options make sense only together with @samp{-E} because +they cause the preprocessor output to be unsuitable for actual +compilation. + +@table @code +@item -include @var{file} +Process @var{file} as input before processing the regular input file. +In effect, the contents of @var{file} are compiled first. Any @samp{-D} +and @samp{-U} options on the command line are always processed before +@samp{-include @var{file}}, regardless of the order in which they are +written. All the @samp{-include} and @samp{-imacros} options are +processed in the order in which they are written. + +@item -imacros @var{file} +Process @var{file} as input, discarding the resulting output, before +processing the regular input file. Because the output generated from +@var{file} is discarded, the only effect of @samp{-imacros @var{file}} +is to make the macros defined in @var{file} available for use in the +main input. + +Any @samp{-D} and @samp{-U} options on the command line are always +processed before @samp{-imacros @var{file}}, regardless of the order in +which they are written. All the @samp{-include} and @samp{-imacros} +options are processed in the order in which they are written. + +@item -idirafter @var{dir} +@cindex second include path +Add the directory @var{dir} to the second include path. The directories +on the second include path are searched when a header file is not found +in any of the directories in the main include path (the one that +@samp{-I} adds to). + +@item -iprefix @var{prefix} +Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix} +options. + +@item -iwithprefix @var{dir} +Add a directory to the second include path. The directory's name is +made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was +specified previously with @samp{-iprefix}. If you have not specified a +prefix yet, the directory containing the installed passes of the +compiler is used as the default. + +@item -iwithprefixbefore @var{dir} +Add a directory to the main include path. The directory's name is made +by concatenating @var{prefix} and @var{dir}, as in the case of +@samp{-iwithprefix}. + +@item -isystem @var{dir} +Add a directory to the beginning of the second include path, marking it +as a system directory, so that it gets the same special treatment as +is applied to the standard system directories. + +@item -nostdinc +Do not search the standard system directories for header files. Only +the directories you have specified with @samp{-I} options (and the +current directory, if appropriate) are searched. @xref{Directory +Options}, for information on @samp{-I}. + +By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file +search path to only those directories you specify explicitly. + +@item -undef +Do not predefine any nonstandard macros. (Including architecture flags). + +@item -E +Run only the C preprocessor. Preprocess all the C source files +specified and output the results to standard output or to the +specified output file. + +@item -C +Tell the preprocessor not to discard comments. Used with the +@samp{-E} option. + +@item -P +Tell the preprocessor not to generate @samp{#line} commands. +Used with the @samp{-E} option. + +@cindex make +@cindex dependencies, make +@item -M +Tell the preprocessor to output a rule suitable for @code{make} +describing the dependencies of each object file. For each source file, +the preprocessor outputs one @code{make}-rule whose target is the object +file name for that source file and whose dependencies are all the +@code{#include} header files it uses. This rule may be a single line or +may be continued with @samp{\}-newline if it is long. The list of rules +is printed on standard output instead of the preprocessed C program. + +@samp{-M} implies @samp{-E}. + +Another way to specify output of a @code{make} rule is by setting +the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment +Variables}). + +@item -MM +Like @samp{-M} but the output mentions only the user header files +included with @samp{#include "@var{file}"}. System header files +included with @samp{#include <@var{file}>} are omitted. + +@item -MD +Like @samp{-M} but the dependency information is written to a file made by +replacing ".c" with ".d" at the end of the input file names. +This is in addition to compiling the file as specified---@samp{-MD} does +not inhibit ordinary compilation the way @samp{-M} does. + +In Mach, you can use the utility @code{md} to merge multiple dependency +files into a single dependency file suitable for using with the @samp{make} +command. + +@item -MMD +Like @samp{-MD} except mention only user header files, not system +header files. + +@item -MG +Treat missing header files as generated files and assume they live in the +same directory as the source file. If you specify @samp{-MG}, you +must also specify either @samp{-M} or @samp{-MM}. @samp{-MG} is not +supported with @samp{-MD} or @samp{-MMD}. + +@item -H +Print the name of each header file used, in addition to other normal +activities. + +@item -A@var{question}(@var{answer}) +Assert the answer @var{answer} for @var{question}, in case it is tested +with a preprocessor conditional such as @samp{#if +#@var{question}(@var{answer})}. @samp{-A-} disables the standard +assertions that normally describe the target machine. + +@item -D@var{macro} +Define macro @var{macro} with the string @samp{1} as its definition. + +@item -D@var{macro}=@var{defn} +Define macro @var{macro} as @var{defn}. All instances of @samp{-D} on +the command line are processed before any @samp{-U} options. + +@item -U@var{macro} +Undefine macro @var{macro}. @samp{-U} options are evaluated after all +@samp{-D} options, but before any @samp{-include} and @samp{-imacros} +options. + +@item -dM +Tell the preprocessor to output only a list of the macro definitions +that are in effect at the end of preprocessing. Used with the @samp{-E} +option. + +@item -dD +Tell the preprocessing to pass all macro definitions into the output, in +their proper sequence in the rest of the output. + +@item -dN +Like @samp{-dD} except that the macro arguments and contents are omitted. +Only @samp{#define @var{name}} is included in the output. + +@item -trigraphs +Support ANSI C trigraphs. The @samp{-ansi} option also has this effect. + +@item -Wp,@var{option} +Pass @var{option} as an option to the preprocessor. If @var{option} +contains commas, it is split into multiple options at the commas. +@end table + +@node Assembler Options +@section Passing Options to the Assembler + +@c prevent bad page break with this line +You can pass options to the assembler. + +@table @code +@item -Wa,@var{option} +Pass @var{option} as an option to the assembler. If @var{option} +contains commas, it is split into multiple options at the commas. +@end table + +@node Link Options +@section Options for Linking +@cindex link options +@cindex options, linking + +These options come into play when the compiler links object files into +an executable output file. They are meaningless if the compiler is +not doing a link step. + +@table @code +@cindex file names +@item @var{object-file-name} +A file name that does not end in a special recognized suffix is +considered to name an object file or library. (Object files are +distinguished from libraries by the linker according to the file +contents.) If linking is done, these object files are used as input +to the linker. + +@item -c +@itemx -S +@itemx -E +If any of these options is used, then the linker is not run, and +object file names should not be used as arguments. @xref{Overall +Options}. + +@cindex Libraries +@item -l@var{library} +Search the library named @var{library} when linking. + +It makes a difference where in the command you write this option; the +linker searches processes libraries and object files in the order they +are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z} +after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers +to functions in @samp{z}, those functions may not be loaded. + +The linker searches a standard list of directories for the library, +which is actually a file named @file{lib@var{library}.a}. The linker +then uses this file as if it had been specified precisely by name. + +The directories searched include several standard system directories +plus any that you specify with @samp{-L}. + +Normally the files found this way are library files---archive files +whose members are object files. The linker handles an archive file by +scanning through it for members which define symbols that have so far +been referenced but not defined. But if the file that is found is an +ordinary object file, it is linked in the usual fashion. The only +difference between using an @samp{-l} option and specifying a file name +is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a} +and searches several directories. + +@item -lobjc +You need this special case of the @samp{-l} option in order to +link an Objective C program. + +@item -nostartfiles +Do not use the standard system startup files when linking. +The standard libraries are used normally. + +@item -nostdlib +Do not use the standard system libraries and startup files when linking. +Only the files you specify will be passed to the linker. + +@cindex @code{-lgcc}, use with @code{-nostdlib} +@cindex @code{-nostdlib} and unresolved references +@cindex unresolved references and @code{-nostdlib} +One of the standard libraries bypassed by @samp{-nostdlib} is +@file{libgcc.a}, a library of internal subroutines that GNU CC uses to +overcome shortcomings of particular machines, or special needs for some +languages. +@ifset INTERNALS +(@xref{Interface,,Interfacing to GNU CC Output}, for more discussion of +@file{libgcc.a}.) +@end ifset +@ifclear INTERNALS +(@xref{Interface,,Interfacing to GNU CC Output,gcc.info,Porting GNU CC}, +for more discussion of @file{libgcc.a}.) +@end ifclear +In most cases, you need @file{libgcc.a} even when you want to avoid +other standard libraries. In other words, when you specify +@samp{-nostdlib} you should usually specify @samp{-lgcc} as well. This +ensures that you have no unresolved references to internal GNU CC +library subroutines. (For example, @samp{__main}, used to ensure C++ +constructors will be called; @pxref{Collect2,,@code{collect2}}.) + +@item -s +Remove all symbol table and relocation information from the executable. + +@item -static +On systems that support dynamic linking, this prevents linking with the shared +libraries. On other systems, this +option has no effect. + +@item -shared +Produce a shared object which can then be linked with other objects to +form an executable. Only a few systems support this option. + +@item -symbolic +Bind references to global symbols when building a shared object. Warn +about any unresolved references (unless overridden by the link editor +option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support +this option. + +@item -Xlinker @var{option} +Pass @var{option} as an option to the linker. You can use this to +supply system-specific linker options which GNU CC does not know how to +recognize. + +If you want to pass an option that takes an argument, you must use +@samp{-Xlinker} twice, once for the option and once for the argument. +For example, to pass @samp{-assert definitions}, you must write +@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write +@samp{-Xlinker "-assert definitions"}, because this passes the entire +string as a single argument, which is not what the linker expects. + +@item -Wl,@var{option} +Pass @var{option} as an option to the linker. If @var{option} contains +commas, it is split into multiple options at the commas. + +@item -u @var{symbol} +Pretend the symbol @var{symbol} is undefined, to force linking of +library modules to define it. You can use @samp{-u} multiple times with +different symbols to force loading of additional library modules. +@end table + +@node Directory Options +@section Options for Directory Search +@cindex directory options +@cindex options, directory search +@cindex search path + +These options specify directories to search for header files, for +libraries and for parts of the compiler: + +@table @code +@item -I@var{dir} +Append directory @var{dir} to the list of directories searched for +include files. + +@item -I- +Any directories you specify with @samp{-I} options before the @samp{-I-} +option are searched only for the case of @samp{#include "@var{file}"}; +they are not searched for @samp{#include <@var{file}>}. + +If additional directories are specified with @samp{-I} options after +the @samp{-I-}, these directories are searched for all @samp{#include} +directives. (Ordinarily @emph{all} @samp{-I} directories are used +this way.) + +In addition, the @samp{-I-} option inhibits the use of the current +directory (where the current input file came from) as the first search +directory for @samp{#include "@var{file}"}. There is no way to +override this effect of @samp{-I-}. With @samp{-I.} you can specify +searching the directory which was current when the compiler was +invoked. That is not exactly the same as what the preprocessor does +by default, but it is often satisfactory. + +@samp{-I-} does not inhibit the use of the standard system directories +for header files. Thus, @samp{-I-} and @samp{-nostdinc} are +independent. + +@item -L@var{dir} +Add directory @var{dir} to the list of directories to be searched +for @samp{-l}. + +@item -B@var{prefix} +This option specifies where to find the executables, libraries, +include files, and data files of the compiler itself. + +The compiler driver program runs one or more of the subprograms +@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries +@var{prefix} as a prefix for each program it tries to run, both with and +without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}). + +For each subprogram to be run, the compiler driver first tries the +@samp{-B} prefix, if any. If that name is not found, or if @samp{-B} +was not specified, the driver tries two standard prefixes, which are +@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of +those results in a file name that is found, the unmodified program +name is searched for using the directories specified in your +@samp{PATH} environment variable. + +@samp{-B} prefixes that effectively specify directory names also apply +to libraries in the linker, because the compiler translates these +options into @samp{-L} options for the linker. They also apply to +includes files in the preprocessor, because the compiler translates these +options into @samp{-isystem} options for the preprocessor. In this case, +the compiler appends @samp{include} to the prefix. + +The run-time support file @file{libgcc.a} can also be searched for using +the @samp{-B} prefix, if needed. If it is not found there, the two +standard prefixes above are tried, and that is all. The file is left +out of the link if it is not found by those means. + +Another way to specify a prefix much like the @samp{-B} prefix is to use +the environment variable @code{GCC_EXEC_PREFIX}. @xref{Environment +Variables}. +@end table + +@node Target Options +@section Specifying Target Machine and Compiler Version +@cindex target options +@cindex cross compiling +@cindex specifying machine version +@cindex specifying compiler version and target machine +@cindex compiler version, specifying +@cindex target machine, specifying + +By default, GNU CC 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 GNU CC, for different target machines, can be +installed side by side. Then you specify which one to use with the +@samp{-b} option. + +In addition, older and newer versions of GNU CC can be installed side +by side. One of them (probably the newest) will be the default, but +you may sometimes wish to use another. + +@table @code +@item -b @var{machine} +The argument @var{machine} specifies the target machine for compilation. +This is useful when you have installed GNU CC as a cross-compiler. + +The value to use for @var{machine} is the same as was specified as the +machine type when configuring GNU CC as a cross-compiler. For +example, if a cross-compiler was configured with @samp{configure +i386v}, meaning to compile for an 80386 running System V, then you +would specify @samp{-b i386v} to run that cross compiler. + +When you do not specify @samp{-b}, it normally means to compile for +the same type of machine that you are using. + +@item -V @var{version} +The argument @var{version} specifies which version of GNU CC to run. +This is useful when multiple versions are installed. For example, +@var{version} might be @samp{2.0}, meaning to run GNU CC version 2.0. + +The default version, when you do not specify @samp{-V}, is controlled +by the way GNU CC is installed. Normally, it will be a version that +is recommended for general use. +@end table + +The @samp{-b} and @samp{-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 GNU CC, for a given target machine, is +normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill + +Thus, sites can customize the effect of @samp{-b} or @samp{-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 @samp{-b +80386} becomes an alias for @samp{-b i386v}. + +In one respect, the @samp{-b} or @samp{-V} do not completely change +to a different compiler: the top-level driver program @code{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 and version. + +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 compiler version. + +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 @code{ogcc} +and that for version 2.1 is installed as @code{gcc}, then the command +@code{gcc} will use version 2.1 by default, while @code{ogcc} will use +2.0 by default. However, you can choose either version with either +command with the @samp{-V} option. + +@node Submodel Options +@section Hardware Models and Configurations +@cindex submodel options +@cindex specifying hardware config +@cindex hardware models and configurations, specifying +@cindex machine dependent options + +Earlier we discussed the standard option @samp{-b} which chooses among +different installed compilers for completely different target +machines, such as Vax vs. 68000 vs. 80386. + +In addition, each of these target machine types can have its own +special options, starting with @samp{-m}, to choose among various +hardware models or configurations---for example, 68010 vs 68020, +floating coprocessor or none. A single installed version of the +compiler can compile for any model or configuration, according to the +options specified. + +Some configurations of the compiler also support additional special +options, usually for compatibility with other compilers on the same +platform. + +@ifset INTERNALS +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. +@end ifset + +@menu +* M680x0 Options:: +* VAX Options:: +* SPARC Options:: +* Convex Options:: +* AMD29K Options:: +* ARM Options:: +* M88K Options:: +* RS/6000 and PowerPC Options:: +* RT Options:: +* MIPS Options:: +* i386 Options:: +* HPPA Options:: +* Intel 960 Options:: +* DEC Alpha Options:: +* Clipper Options:: +* H8/300 Options:: +* System V Options:: +@end menu + +@node M680x0 Options +@subsection M680x0 Options +@cindex M680x0 options + +These are the @samp{-m} options defined for the 68000 series. The default +values for these options depends on which style of 68000 was selected when +the compiler was configured; the defaults for the most common choices are +given below. + +@table @code +@item -m68000 +@itemx -mc68000 +Generate output for a 68000. This is the default +when the compiler is configured for 68000-based systems. + +@item -m68020 +@itemx -mc68020 +Generate output for a 68020. This is the default +when the compiler is configured for 68020-based systems. + +@item -m68881 +Generate output containing 68881 instructions for floating point. +This is the default for most 68020 systems unless @samp{-nfp} was +specified when the compiler was configured. + +@item -m68030 +Generate output for a 68030. This is the default when the compiler is +configured for 68030-based systems. + +@item -m68040 +Generate output for a 68040. This is the default when the compiler is +configured for 68040-based systems. + +This option inhibits the use of 68881/68882 instructions that have to be +emulated by software on the 68040. If your 68040 does not have code to +emulate those instructions, use @samp{-m68040}. + +@item -m68020-40 +Generate output for a 68040, without using any of the new instructions. +This results in code which can run relatively efficiently on either a +68020/68881 or a 68030 or a 68040. The generated code does use the +68881 instructions that are emulated on the 68040. + +@item -mfpa +Generate output containing Sun FPA instructions for floating point. + +@item -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not part of GNU CC. +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 -mshort +Consider type @code{int} to be 16 bits wide, like @code{short int}. + +@item -mnobitfield +Do not use the bit-field instructions. The @samp{-m68000} option +implies @w{@samp{-mnobitfield}}. + +@item -mbitfield +Do use the bit-field instructions. The @samp{-m68020} option implies +@samp{-mbitfield}. This is the default if you use a configuration +designed for a 68020. + +@item -mrtd +Use a different function-calling convention, in which functions +that take a fixed number of arguments return with the @code{rtd} +instruction, which pops their arguments while returning. This +saves one instruction in the caller since there is no need to pop +the arguments there. + +This calling convention is incompatible with the one normally +used on Unix, so you cannot use it if you need to call libraries +compiled with the Unix compiler. + +Also, you must provide function prototypes for all functions that +take variable numbers of arguments (including @code{printf}); +otherwise incorrect code will be generated for calls to those +functions. + +In addition, seriously incorrect code will result if you call a +function with too many arguments. (Normally, extra arguments are +harmlessly ignored.) + +The @code{rtd} instruction is supported by the 68010 and 68020 +processors, but not by the 68000. +@end table + +@node VAX Options +@subsection VAX Options +@cindex VAX options + +These @samp{-m} options are defined for the Vax: + +@table @code +@item -munix +Do not output certain jump instructions (@code{aobleq} and so on) +that the Unix assembler for the Vax cannot handle across long +ranges. + +@item -mgnu +Do output those jump instructions, on the assumption that you +will assemble with the GNU assembler. + +@item -mg +Output code for g-format floating point numbers instead of d-format. +@end table + +@node SPARC Options +@subsection SPARC Options +@cindex SPARC options + +These @samp{-m} switches are supported on the SPARC: + +@table @code +@item -mno-app-regs +@itemx -mapp-regs +Specify @samp{-mapp-regs} to generate output using the global registers +2 through 4, which the SPARC SVR4 ABI reserves for applications. This +is the default. + +To be fully SVR4 ABI compliant at the cost of some performance loss, +specify @samp{-mno-app-regs}. You should compile libraries and system +software with this option. + +@item -mfpu +@itemx -mhard-float +Generate output containing floating point instructions. This is the +default. + +@item -mno-fpu +@itemx -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} there is no GNU floating-point library for SPARC. +Normally the facilities of the machine's usual C compiler are used, but +this cannot be done directly in cross-compilation. You must make your +own arrangements to provide suitable library functions for +cross-compilation. + +@samp{-msoft-float} changes the calling convention in the output file; +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 GNU CC, with @samp{-msoft-float} in order for +this to work. + +@item -mhard-quad-float +Generate output containing quad-word (long double) floating point +instructions. + +@item -msoft-quad-float +Generate output containing library calls for quad-word (long double) +floating point instructions. The functions called are those specified +in the SPARC ABI. This is the default. + +As of this writing, there are no sparc implementations that have hardware +support for the quad-word floating point instructions. They all invoke +a trap handler for one of these instructions, and then the trap handler +emulates the effect of the instruction. Because of the trap handler overhead, +this is much slower than calling the ABI library routines. Thus the +@samp{-msoft-quad-float} option is the default. + +@item -mno-epilogue +@itemx -mepilogue +With @samp{-mepilogue} (the default), the compiler always emits code for +function exit at the end of each function. Any function exit in +the middle of the function (such as a return statement in C) will +generate a jump to the exit code at the end of the function. + +With @samp{-mno-epilogue}, the compiler tries to emit exit code inline +at every function exit. + +@item -mno-flat +@itemx -mflat +With @samp{-mflat}, the compiler does not generate save/restore instructions +and will use a "flat" or single register window calling convention. +This model uses %i7 as the frame pointer and is compatible with the normal +register window model. Code from either may be intermixed although +debugger support is still incomplete. The local registers and the input +registers (0-5) are still treated as "call saved" registers and will be +saved on the stack as necessary. + +With @samp{-mno-flat} (the default), the compiler emits save/restore +instructions (except for leaf functions) and is the normal mode of operation. + +@item -mno-unaligned-doubles +@itemx -munaligned-doubles +Assume that doubles have 8 byte alignment. This is the default. + +With @samp{-munaligned-doubles}, GNU CC assumes that doubles have 8 byte +alignment only if they are contained in another type, or if they have an +absolute address. Otherwise, it assumes they have 4 byte alignment. +Specifying this option avoids some rare compatibility problems with code +generated by other compilers. It is not the default because it results +in a performance loss, especially for floating point code. + +@item -mv8 +@itemx -msparclite +These two options select variations on the SPARC architecture. + +By default (unless specifically configured for the Fujitsu SPARClite), +GCC generates code for the v7 variant of the SPARC architecture. + +@samp{-mv8} will give you SPARC v8 code. The only difference from v7 +code is that the compiler emits the integer multiply and integer +divide instructions which exist in SPARC v8 but not in SPARC v7. + +@samp{-msparclite} will give you SPARClite code. This adds the integer +multiply, integer divide step and scan (@code{ffs}) instructions which +exist in SPARClite but not in SPARC v7. + +@item -mcypress +@itemx -msupersparc +These two options select the processor for which the code is optimised. + +With @samp{-mcypress} (the default), the compiler optimizes code for the +Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series. +This is also apropriate for the older SparcStation 1, 2, IPX etc. + +With @samp{-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. +@end table + +In a future version of GCC, these options will very likely be +renamed to @samp{-mcpu=cypress} and @samp{-mcpu=supersparc}. + +These @samp{-m} switches are supported in addition to the above +on SPARC V9 processors: + +@table @code +@item -mmedlow +Generate code for the Medium/Low code model: assume a 32 bit address space. +Programs are statically linked, PIC is not supported. Pointers are still +64 bits. + +It is very likely that a future version of GCC will rename this option. + +@item -mmedany +Generate code for the Medium/Anywhere code model: assume a 32 bit text +segment starting at offset 0, and a 32 bit data segment starting anywhere +(determined at link time). Programs are statically linked, PIC is not +supported. Pointers are still 64 bits. + +It is very likely that a future version of GCC will rename this option. + +@item -mint64 +Types long and int are 64 bits. + +@item -mlong32 +Types long and int are 32 bits. + +@item -mlong64 +@itemx -mint32 +Type long is 64 bits, and type int is 32 bits. + +@item -mstack-bias +@itemx -mno-stack-bias +With @samp{-mstack-bias}, GNU CC assumes that the stack pointer, and +frame pointer if present, are offset by -2047 which must be added back +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 @code +@item -mc1 +Generate output for C1. The code will run on any Convex machine. +The preprocessor symbol @code{__convex__c1__} is defined. + +@item -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 +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 +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 +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 +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 +Omit the argument count word. This is the default. + +@item -mvolatile-cache +Allow volatile references to be cached. This is the default. + +@item -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 +Type long is 32 bits, the same as type int. This is the default. + +@item -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 @code +@item -mdw +@kindex -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 +@kindex -mndw +Generate code that assumes the @code{DW} bit is not set. + +@item -mbw +@kindex -mbw +@cindex byte writes (29k) +Generate code that assumes the system supports byte and halfword write +operations. This is the default. + +@item -mnbw +@kindex -mnbw +Generate code that assumes the systems does not support byte and +halfword write operations. @samp{-mnbw} implies @samp{-mndw}. + +@item -msmall +@kindex -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 +@kindex -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 +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 +@kindex -m29050 +@cindex processor selection (29k) +Generate code for the Am29050. + +@item -m29000 +@kindex -m29000 +Generate code for the Am29000. This is the default. + +@item -mkernel-registers +@kindex -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 +@kindex -muser-registers +Use the normal set of global registers, @code{gr96-gr127}. This is the +default. + +@item -mstack-check +@itemx -mno-stack-check +@kindex -mstack-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 +@kindex -mstorem-bug +@cindex storem bug (29k) +@samp{-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 +@kindex -mreuse-arg-regs +@samp{-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 -msoft-float +@kindex -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not part of GNU CC. +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. +@end table + +@node ARM Options +@subsection ARM Options +@cindex ARM options + +These @samp{-m} options are defined for Advanced RISC Machines (ARM) +architectures: + +@table @code +@item -m2 +@itemx -m3 +@kindex -m2 +@kindex -m3 +These options are identical. Generate code for the ARM2 and ARM3 +processors. This option is the default. You should also use this +option to generate code for ARM6 processors that are running with a +26-bit program counter. + +@item -m6 +@kindex -m6 +Generate code for the ARM6 processor when running with a 32-bit program +counter. + +@item -mapcs +@kindex -mapcs +Generate a stack frame that is compliant with the ARM Proceedure Call +Standard for all functions, even if this is not strictly necessary for +correct execution of the code. + +@item -mbsd +@kindex -mbsd +This option only applies to RISC iX. Emulate the native BSD-mode +compiler. This is the default if @samp{-ansi} is not specified. + +@item -mxopen +@kindex -mxopen +This option only applies to RISC iX. Emulate the native X/Open-mode +compiler. + +@item -mno-symrename +@kindex -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. +@end table + +@node M88K Options +@subsection M88K Options +@cindex M88k options + +These @samp{-m} options are defined for Motorola 88k architectures: + +@table @code +@item -m88000 +@kindex -m88000 +Generate code that works well on both the m88100 and the +m88110. + +@item -m88100 +@kindex -m88100 +Generate code that works best for the m88100, but that also +runs on the m88110. + +@item -m88110 +@kindex -m88110 +Generate code that works best for the m88110, and may not run +on the m88100. + +@item -mbig-pic +@kindex -mbig-pic +Obsolete option to be removed from the next revision. +Use @samp{-fPIC}. + +@item -midentify-revision +@kindex -midentify-revision +@kindex ident +@cindex identifying source, compiler (88k) +Include an @code{ident} directive in the assembler output recording the +source file name, compiler name and version, timestamp, and compilation +flags used. + +@item -mno-underscores +@kindex -mno-underscores +@cindex underscores, avoiding (88k) +In assembler output, emit symbol names without adding an underscore +character at the beginning of each name. The default is to use an +underscore as prefix on each name. + +@item -mocs-debug-info +@itemx -mno-ocs-debug-info +@kindex -mocs-debug-info +@kindex -mno-ocs-debug-info +@cindex OCS (88k) +@cindex debugging, 88k OCS +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. + +@item -mocs-frame-position +@kindex -mocs-frame-position +@cindex register positions in frame (88k) +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 +@samp{-mocs-frame-position}; other 88k configurations have the default +@samp{-mno-ocs-frame-position}. + +@item -mno-ocs-frame-position +@kindex -mno-ocs-frame-position +@cindex register positions in frame (88k) +When emitting COFF debugging information for automatic variables and +parameters stored on the stack, use the offset from the frame pointer +register (register 30). When this option is in effect, the frame +pointer is not eliminated when debugging information is selected by the +-g switch. + +@item -moptimize-arg-area +@itemx -mno-optimize-arg-area +@kindex -moptimize-arg-area +@kindex -mno-optimize-arg-area +@cindex arguments in frame (88k) +Control how function arguments are stored in stack frames. +@samp{-moptimize-arg-area} saves space by optimizing them, but this +conflicts with the 88open specifications. The opposite alternative, +@samp{-mno-optimize-arg-area}, agrees with 88open standards. By default +GNU CC does not optimize the argument area. + +@item -mshort-data-@var{num} +@kindex -mshort-data-@var{num} +@cindex smaller data references (88k) +@cindex r0-relative references (88k) +Generate smaller data references by making them relative to @code{r0}, +which allows loading a value using a single instruction (rather than the +usual two). You control which data references are affected by +specifying @var{num} with this option. For example, if you specify +@samp{-mshort-data-512}, then the data references affected are those +involving displacements of less than 512 bytes. +@samp{-mshort-data-@var{num}} is not effective for @var{num} greater +than 64k. + +@item -mserialize-volatile +@kindex -mserialize-volatile +@itemx -mno-serialize-volatile +@kindex -mno-serialize-volatile +@cindex sequential consistency on 88k +Do, or don't, generate code to guarantee sequential consistency +of volatile memory references. By default, consistency is +guaranteed. + +The order of memory references made by the MC88110 processor does +not always match the order of the instructions requesting those +references. In particular, a load instruction may execute before +a preceding store instruction. Such reordering violates +sequential consistency of volatile memory references, when there +are multiple processors. When consistency must be guaranteed, +GNU C generates special instructions, as needed, to force +execution in the proper order. + +The MC88100 processor does not reorder memory references and so +always provides sequential consistency. However, by default, GNU +C generates the special instructions to guarantee consistency +even when you use @samp{-m88100}, so that the code may be run on an +MC88110 processor. If you intend to run your code only on the +MC88100 processor, you may use @samp{-mno-serialize-volatile}. + +The extra code generated to guarantee consistency may affect the +performance of your application. If you know that you can safely +forgo this guarantee, you may use @samp{-mno-serialize-volatile}. + +@item -msvr4 +@itemx -msvr3 +@kindex -msvr4 +@kindex -msvr3 +@cindex assembler syntax, 88k +@cindex SVr4 +Turn on (@samp{-msvr4}) or off (@samp{-msvr3}) compiler extensions +related to System V release 4 (SVr4). This controls the following: + +@enumerate +@item +Which variant of the assembler syntax to emit. +@item +@samp{-msvr4} makes the C preprocessor recognize @samp{#pragma weak} +that is used on System V release 4. +@item +@samp{-msvr4} makes GNU CC issue additional declaration directives used in +SVr4. +@end enumerate + +@samp{-msvr4} is the default for the m88k-motorola-sysv4 and +m88k-dg-dgux m88k configurations. @samp{-msvr3} is the default for all +other m88k configurations. + +@item -mversion-03.00 +@kindex -mversion-03.00 +This option is obsolete, and is ignored. +@c ??? which asm syntax better for GAS? option there too? + +@item -mno-check-zero-division +@itemx -mcheck-zero-division +@kindex -mno-check-zero-division +@kindex -mcheck-zero-division +@cindex zero division on 88k +Do, or don't, generate code to guarantee that integer division by +zero will be detected. By default, detection is guaranteed. + +Some models of the MC88100 processor fail to trap upon integer +division by zero under certain conditions. By default, when +compiling code that might be run on such a processor, GNU C +generates code that explicitly checks for zero-valued divisors +and traps with exception number 503 when one is detected. Use of +mno-check-zero-division suppresses such checking for code +generated to run on an MC88100 processor. + +GNU C assumes that the MC88110 processor correctly detects all +instances of integer division by zero. When @samp{-m88110} is +specified, both @samp{-mcheck-zero-division} and +@samp{-mno-check-zero-division} are ignored, and no explicit checks for +zero-valued divisors are generated. + +@item -muse-div-instruction +@kindex -muse-div-instruction +@cindex divide instruction, 88k +Use the div instruction for signed integer division on the +MC88100 processor. By default, the div instruction is not used. + +On the MC88100 processor the signed integer division instruction +div) traps to the operating system on a negative operand. The +operating system transparently completes the operation, but at a +large cost in execution time. By default, when compiling code +that might be run on an MC88100 processor, GNU C emulates signed +integer division using the unsigned integer division instruction +divu), thereby avoiding the large penalty of a trap to the +operating system. Such emulation has its own, smaller, execution +cost in both time and space. To the extent that your code's +important signed integer division operations are performed on two +nonnegative operands, it may be desirable to use the div +instruction directly. + +On the MC88110 processor the div instruction (also known as the +divs instruction) processes negative operands without trapping to +the operating system. When @samp{-m88110} is specified, +@samp{-muse-div-instruction} is ignored, and the div instruction is used +for signed integer division. + +Note that the result of dividing INT_MIN by -1 is undefined. In +particular, the behavior of such a division with and without +@samp{-muse-div-instruction} may differ. + +@item -mtrap-large-shift +@itemx -mhandle-large-shift +@kindex -mtrap-large-shift +@kindex -mhandle-large-shift +@cindex bit shift overflow (88k) +@cindex large bit shifts (88k) +Include code to detect bit-shifts of more than 31 bits; respectively, +trap such shifts or emit code to handle them properly. By default GNU CC +makes no special provision for large bit shifts. + +@item -mwarn-passed-structs +@kindex -mwarn-passed-structs +@cindex structure passing (88k) +Warn when a function passes a struct as an argument or result. +Structure-passing conventions have changed during the evolution of the C +language, and are often the source of portability problems. By default, +GNU CC issues no such warning. +@end table + +@node RS/6000 and PowerPC Options +@subsection IBM RS/6000 and PowerPC Options +@cindex RS/6000 and PowerPC Options +@cindex IBM RS/6000 and PowerPC Options + +These @samp{-m} options are defined for the IBM RS/6000 and PowerPC: +@table @code +@item -mpower +@itemx -mno-power +@itemx -mpower2 +@itemx -mno-power2 +@itemx -mpowerpc +@itemx -mno-powerpc +@itemx -mpowerpc-gpopt +@itemx -mno-powerpc-gpopt +@itemx -mpowerpc-gfxopt +@itemx -mno-powerpc-gfxopt +@kindex -mpower +@kindex -mpower2 +@kindex -mpowerpc +@kindex -mpowerpc-gpopt +@kindex -mpowerpc-gfxopt +GNU CC supports two related instruction set architectures for the +RS/6000 and PowerPC. The @dfn{POWER} instruction set are those +instructions supported by the @samp{rios} chip set used in the original +RS/6000 systems and the @dfn{PowerPC} instruction set is the +architecture of the Motorola MPC6xx microprocessors. The PowerPC +architecture defines 64-bit instructions, but they are not supported by +any current processors. + +Neither architecture is a subset of the other. However there is a +large common subset of instructions supported by both. An MQ +register is included in processors supporting the POWER architecture. + +You use these options to specify which instructions are available on the +processor you are using. The default value of these options is +determined when configuring GNU CC. Specifying the +@samp{-mcpu=@var{cpu_type}} overrides the specification of these +options. We recommend you use that option rather than these. + +The @samp{-mpower} option allows GNU CC to generate instructions that +are found only in the POWER architecture and to use the MQ register. +Specifying @samp{-mpower2} implies @samp{-power} and also allows GNU CC +to generate instructions that are present in the POWER2 architecture but +not the original POWER architecture. + +The @samp{-mpowerpc} option allows GNU CC to generate instructions that +are found only in the 32-bit subset of the PowerPC architecture. +Specifying @samp{-mpowerpc-gpopt} implies @samp{-mpowerpc} and also allows +GNU CC to use the optional PowerPC architecture instructions in the +General Purpose group, including floating-point square root. Specifying +@samp{-mpowerpc-gfxopt} implies @samp{-mpowerpc} and also allows GNU CC to +use the optional PowerPC architecture instructions in the Graphics +group, including floating-point select. + +If you specify both @samp{-mno-power} and @samp{-mno-powerpc}, GNU CC +will use only the instructions in the common subset of both +architectures plus some special AIX common-mode calls, and will not use +the MQ register. Specifying both @samp{-mpower} and @samp{-mpowerpc} +permits GNU CC to use any instruction from either architecture and to +allow use of the MQ register; specify this for the Motorola MPC601. + +@item -mnew-mnemonics +@itemx -mold-mnemonics +@kindex -mnew-mnemonics +@kindex -mold-mnemonics +Select which mnemonics to use in the generated assembler code. +@samp{-mnew-mnemonics} requests output that uses the assembler mnemonics +defined for the PowerPC architecture, while @samp{-mold-mnemonics} +requests the assembler mnemonics defined for the POWER architecture. +Instructions defined in only one architecture have only one mnemonic; +GNU CC uses that mnemonic irrespective of which of thse options is +specified. + +PowerPC assemblers support both the old and new mnemonics, as will later +POWER assemblers. Current POWER assemblers only support the old +mnemonics. Specify @samp{-mnew-mnemonics} if you have an assembler that +supports them, otherwise specify @samp{-mold-mnemonics}. + +The default value of these options depends on how GNU CC was configured. +Specifing @samp{-mcpu=@var{cpu_type}} sometimes overrides the value of +these option. Unless you are building a cross-compiler, you should +normally not specify either @samp{-mnew-mnemonics} or +@samp{-mold-mnemonics}, but should instead accept the default. + +@item -mcpu=@var{cpu_type} +Set architecture type, register usage, choice of mnemonics, and +instruction scheduling parameters for machine type @var{cpu_type}. By +default, @var{cpu_type} is the target system defined when GNU CC was +configured. Supported values for @var{cpu_type} are @samp{rios1}, +@samp{rios2}, @samp{rsc}, @samp{601}, @samp{603}, @samp{604}, +@samp{power}, @samp{powerpc}, and @samp{common}. @samp{-mcpu=power} and +@samp{-mcpu=powerpc} specify generic POWER and pure PowerPC (i.e., not +MPC601) architecture machine types, with an appropriate, generic +processor model assumed for scheduling purposes.@refill + +Specifying @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc}, or +@samp{-mcpu=power} enables the @samp{-mpower} option and disables the +@samp{-mpowerpc} option; @samp{-mcpu=601} enables both the +@samp{-mpower} and @samp{-mpowerpc} options; @samp{-mcpu=603}, +@samp{-mcpu=604}, and @samp{-mcpu=powerpc} enable the @samp{-mpowerpc} +option and disable the @samp{-mpower} option; @samp{-mcpu=common} +disables both the @samp{-mpower} and @samp{-mpowerpc} options.@refill + +To generate code that will operate on all members of the RS/6000 and +PowerPC families, specify @samp{-mcpu=common}. In that case, GNU CC +will use only the instructions in the common subset of both +architectures plus some special AIX common-mode calls, and will not use +the MQ register. GNU CC assumes a generic processor model for scheduling +purposes. + +Specifying @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc}, or +@samp{-mcpu=power} also disables the @samp{new-mnemonics} option. +Specifying @samp{-mcpu=601}, @samp{-mcpu=603}, @samp{-mcpu=604}, or +@samp{-mcpu=powerpc} also enables the @samp{new-mnemonics} +option.@refill + +@item -mfull-toc +@itemx -mno-fp-in-toc +@itemx -mno-sum-in-toc +@itemx -mminimal-toc +Modify generation of the TOC (Table Of Contents), which is created for +every executable file. The @samp{-mfull-toc} option is selected by +default. In that case, GNU CC will allocate at least one TOC entry for +each unique non-automatic variable reference in your program. GNU CC +will also place floating-point constants in the TOC. However, only +16,384 entries are available in the TOC. + +If you receive a linker error message that saying you have overflowed +the available TOC space, you can reduce the amount of TOC space used +with the @samp{-mno-fp-in-toc} and @samp{-mno-sum-in-toc} options. +@samp{-mno-fp-in-toc} prevents GNU CC from putting floating-point +constants in the TOC and @samp{-mno-sum-in-toc} forces GNU CC to +generate code to calculate the sum of an address and a constant at +run-time instead of putting that sum into the TOC. You may specify one +or both of these options. Each causes GNU CC to produce very slightly +slower and larger code at the expense of conserving TOC space. + +If you still run out of space in the TOC even when you specify both of +these options, specify @samp{-mminimal-toc} instead. This option causes +GNU CC to make only one TOC entry for every file. When you specify this +option, GNU CC will produce code that is slower and larger but which +uses extremely little TOC space. You may wish to use this option +only on files that contain less frequently executed code. @refill +@end table +@node RT Options +@subsection IBM RT Options +@cindex RT options +@cindex IBM RT options + +These @samp{-m} options are defined for the IBM RT PC: + +@table @code +@item -min-line-mul +Use an in-line code sequence for integer multiplies. This is the +default. + +@item -mcall-lib-mul +Call @code{lmul$$} for integer multiples. + +@item -mfull-fp-blocks +Generate full-size floating point data blocks, including the minimum +amount of scratch space recommended by IBM. This is the default. + +@item -mminimum-fp-blocks +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 +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{stdargs.h} will not work with +floating point operands if this option is specified. + +@item -mfp-arg-in-gregs +Use the normal calling convention for floating point arguments. This is +the default. + +@item -mhc-struct-return +Return structures of more than one word in memory, rather than in a +register. This provides compatibility with the MetaWare HighC (hc) +compiler. Use the option @samp{-fpcc-struct-return} for compatibility +with the Portable C Compiler (pcc). + +@item -mnohc-struct-return +Return some structures of more than one word in registers, when +convenient. This is the default. For compatibility with the +IBM-supplied compilers, use the option @samp{-fpcc-struct-return} or the +option @samp{-mhc-struct-return}. +@end table + +@node MIPS Options +@subsection MIPS Options +@cindex MIPS options + +These @samp{-m} options are defined for the MIPS family of computers: + +@table @code +@item -mcpu=@var{cpu type} +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{r4000}, @samp{r4400}, @samp{r4600}, and @samp{r6000}. 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 +the @samp{-mips2} or @samp{-mips3} switches being used. + +@item -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. + +@item -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. + +@item -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. +This option does not change the sizes of any of the C data types. + +@item -mfp32 +Assume that 32 32-bit floating point registers are available. This is +the default. + +@item -mfp64 +Assume that 32 64-bit floating point registers are available. This is +the default when the @samp{-mips3} option is used. + +@item -mgp32 +Assume that 32 32-bit general purpose registers are available. This is +the default. + +@item -mgp64 +Assume that 32 64-bit general purpose registers are available. This is +the default when the @samp{-mips3} option is used. + +@item -mint64 +Types long, int, and pointer are 64 bits. This works only if @samp{-mips3} +is also specified. + +@item -mlong64 +Types long and pointer are 64 bits, and type int is 32 bits. +This works only if @samp{-mips3} is also specified. + +@item -mmips-as +Generate code for the MIPS assembler, and invoke @file{mips-tfile} to +add normal debug information. This is the default for all +platforms except for the OSF/1 reference platform, using the OSF/rose +object format. If the either of the @samp{-gstabs} or @samp{-gstabs+} +switches are used, the @file{mips-tfile} program will encapsulate the +stabs within MIPS ECOFF. + +@item -mgas +Generate code for the GNU assembler. This is the default on the OSF/1 +reference platform, using the OSF/rose object format. + +@item -mrnames +@itemx -mno-rnames +The @samp{-mrnames} switch says to output code using the MIPS software +names for the registers, instead of the hardware names (ie, @var{a0} +instead of @var{$4}). The only known assembler that supports this option +is the Algorithmics assembler. + +@item -mgpopt +@itemx -mno-gpopt +The @samp{-mgpopt} switch says to write all of the data declarations +before the instructions in the text section, this allows the MIPS +assembler to generate one word memory references instead of using two +words for short global or static data items. This is on by default if +optimization is selected. + +@item -mstats +@itemx -mno-stats +For each non-inline function processed, the @samp{-mstats} switch +causes the compiler to emit one line to the standard error file to +print statistics about the program (number of registers saved, stack +size, etc.). + +@item -mmemcpy +@itemx -mno-memcpy +The @samp{-mmemcpy} switch makes all block moves call the appropriate +string function (@samp{memcpy} or @samp{bcopy}) instead of possibly +generating inline code. + +@item -mmips-tfile +@itemx -mno-mips-tfile +The @samp{-mno-mips-tfile} switch causes the compiler not +postprocess the object file with the @file{mips-tfile} program, +after the MIPS assembler has generated it to add debug support. If +@file{mips-tfile} is not run, then no local variables will be +available to the debugger. In addition, @file{stage2} and +@file{stage3} objects will have the temporary file names passed to the +assembler embedded in the object file, which means the objects will +not compare the same. The @samp{-mno-mips-tfile} switch should only +be used when there are bugs in the @file{mips-tfile} program that +prevents compilation. + +@item -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not part of GNU CC. +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 -mhard-float +Generate output containing floating point instructions. This is the +default if you use the unmodified sources. + +@item -mabicalls +@itemx -mno-abicalls +Emit (or do not emit) the pseudo operations @samp{.abicalls}, +@samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for +position independent code. + +@item -mlong-calls +@itemx -mno-long-calls +Do all calls with the @samp{JALR} instruction, which requires +loading up a function's address into a register before the call. +You need to use this switch, if you call outside of the current +512 megabyte segment to functions that are not through pointers. + +@item -mhalf-pic +@itemx -mno-half-pic +Put pointers to extern references into the data section and load them +up, rather than put the references in the text section. + +@item -membedded-pic +@itemx -mno-embedded-pic +Generate PIC code suitable for some embedded systems. All calls are made +using PC relative address, and all data is addressed using the $gp register. +This requires GNU as and GNU ld which do most of the work. + +@item -membedded-data +@itemx -mno-embedded-data +Allocate variables to the read-only data section first if possible, then +next in the small data section if possible, otherwise in data. This gives +slightly slower code than the default, but reduces the amount of RAM required +when executing, and thus may be preferred for some embedded systems. + +@item -G @var{num} +@cindex smaller data references (MIPS) +@cindex gp-relative references (MIPS) +Put global and static items less than or equal to @var{num} bytes into +the small data or bss sections instead of the normal data or bss +section. This allows the assembler to emit one word memory reference +instructions based on the global pointer (@var{gp} or @var{$28}), +instead of the normal two words used. By default, @var{num} is 8 when +the MIPS assembler is used, and 0 when the GNU assembler is used. The +@samp{-G @var{num}} switch is also passed to the assembler and linker. +All modules should be compiled with the same @samp{-G @var{num}} +value. + +@item -nocpp +Tell the MIPS assembler to not run it's preprocessor over user +assembler files (with a @samp{.s} suffix) when assembling them. +@end table + +@ifset INTERNALS +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. +@end ifset + +@node i386 Options +@subsection Intel 386 Options +@cindex i386 Options +@cindex Intel 386 Options + +These @samp{-m} options are defined for the i386 family of computers: + +@table @code +@item -m486 +@itemx -mno-486 +Control whether or not code is optimized for a 486 instead of an +386. Code generated for an 486 will run on a 386 and vice versa. + +@item -mieee-fp +@itemx -m-no-ieee-fp +Control whether or not the compiler uses IEEE floating point +comparisons. These handle correctly the case where the result of a +comparison is unordered. + +@item -msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not part of GNU CC. +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. + +On machines where a function returns floating point results in the 80387 +register stack, some floating point opcodes may be emitted even if +@samp{-msoft-float} is used. + +@item -mno-fp-ret-in-387 +Do not use the FPU registers for return values of functions. + +The usual calling convention has functions return values of types +@code{float} and @code{double} in an FPU register, even if there +is no FPU. The idea is that the operating system should emulate +an FPU. + +The option @samp{-mno-fp-ret-in-387} causes such values to be returned +in ordinary CPU registers instead. + +@item -mno-fancy-math-387 +Some 387 emulators do not support the @code{sin}, @code{cos} and +@code{sqrt} instructions for the 387. Specify this option to avoid +generating those instructions. This option is the default on FreeBSD. +As of revision 2.6.1, these instructions are not generated unless you +also use the @samp{-ffast-math} switch. + +@item -msvr3-shlib +@itemx -mno-svr3-shlib +Control whether GNU CC places uninitialized locals into @code{bss} or +@code{data}. @samp{-msvr3-shlib} places these locals into @code{bss}. +These options are meaningful only on System V Release 3. + +@item -mno-wide-multiply +@itemx -mwide-multiply +Control whether GNU CC uses the @code{mul} and @code{imul} that produce +64 bit results in @code{eax:edx} from 32 bit operands to do @code{long +long} multiplies and 32-bit division by constants. + +@item -mreg-alloc=@var{regs} +Control the default allocation order of integer registers. The +string @var{regs} is a series of letters specifing a register. The +supported letters are: @code{a} allocate EAX; @code{b} allocate EBX; +@code{c} allocate ECX; @code{d} allocate EDX; @code{S} allocate ESI; +@code{D} allocate EDI; @code{B} allocate EBP. +@end table + +@node HPPA Options +@subsection HPPA Options +@cindex HPPA Options + +These @samp{-m} options are defined for the HPPA family of computers: + +@table @code +@item -mpa-risc-1-0 +Generate code for a PA 1.0 processor. + +@item -mpa-risc-1-1 +Generate code for a PA 1.1 processor. + +@item -mjump-in-delay +Fill delay slots of function calls with unconditional jump instructions +by modifying the return pointer for the function call to be the target +of the conditional jump. + +@item -mlong-calls +Generate code which allows calls to functions greater than 256k away from +the caller when the caller and callee are in the same source file. Do +not turn this option on unless code refuses to link with "branch out of +range errors" from the linker. + +@item -mdisable-fpregs +Prevent floating point registers from being used in any manner. This is +necessary for compiling kernels which perform lazy context switching of +floating point registers. If you use this option and attempt to perform +floating point operations, the compiler will abort. + +@item -mdisable-indexing +Prevent the compiler from using indexing address modes. This avoids some +rather obscure problems when compiling MIG generated code under MACH. + +@item -mportable-runtime +Use the portable calling conventions proposed by HP for ELF systems. Note +this option also enables @samp{-mlong-calls}. + +@item -mgas +Enable the use of assembler directives only GAS understands. +@end table + +@node Intel 960 Options +@subsection Intel 960 Options + +These @samp{-m} options are defined for the Intel 960 implementations: + +@table @code +@item -m@var{cpu type} +Assume the defaults for the machine type @var{cpu type} for some of +the other options, including instruction scheduling, floating point +support, and addressing modes. The choices for @var{cpu type} are +@samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf}, +@samp{sa}, and @samp{sb}. +The default is +@samp{kb}. + +@item -mnumerics +@itemx -msoft-float +The @samp{-mnumerics} option indicates that the processor does support +floating-point instructions. The @samp{-msoft-float} option indicates +that floating-point support should not be assumed. + +@item -mleaf-procedures +@itemx -mno-leaf-procedures +Do (or do not) attempt to alter leaf procedures to be callable with the +@code{bal} instruction as well as @code{call}. This will result in more +efficient code for explicit calls when the @code{bal} instruction can be +substituted by the assembler or linker, but less efficient code in other +cases, such as calls via function pointers, or using a linker that doesn't +support this optimization. + +@item -mtail-call +@itemx -mno-tail-call +Do (or do not) make additional attempts (beyond those of the +machine-independent portions of the compiler) to optimize tail-recursive +calls into branches. You may not want to do this because the detection of +cases where this is not valid is not totally complete. The default is +@samp{-mno-tail-call}. + +@item -mcomplex-addr +@itemx -mno-complex-addr +Assume (or do not assume) that the use of a complex addressing mode is a +win on this implementation of the i960. Complex addressing modes may not +be worthwhile on the K-series, but they definitely are on the C-series. +The default is currently @samp{-mcomplex-addr} for all processors except +the CB and CC. + +@item -mcode-align +@itemx -mno-code-align +Align code to 8-byte boundaries for faster fetching (or don't bother). +Currently turned on by default for C-series implementations only. + +@ignore +@item -mclean-linkage +@itemx -mno-clean-linkage +These options are not fully implemented. +@end ignore + +@item -mic-compat +@itemx -mic2.0-compat +@itemx -mic3.0-compat +Enable compatibility with iC960 v2.0 or v3.0. + +@item -masm-compat +@itemx -mintel-asm +Enable compatibility with the iC960 assembler. + +@item -mstrict-align +@itemx -mno-strict-align +Do not permit (do permit) unaligned accesses. + +@item -mold-align +Enable structure-alignment compatibility with Intel's gcc release version +1.3 (based on gcc 1.37). Currently this is buggy in that @samp{#pragma +align 1} is always assumed as well, and cannot be turned off. +@end table + +@node DEC Alpha Options +@subsection DEC Alpha Options + +These @samp{-m} options are defined for the DEC Alpha implementations: + +@table @code +@item -mno-soft-float +@itemx -msoft-float +Use (do not use) the hardware floating-point instructions for +floating-point operations. When @code{-msoft-float} is specified, +functions in @file{libgcc1.c} will be used to perform floating-point +operations. Unless they are replaced by routines that emulate the +floating-point operations, or compiled in such a way as to call such +emulations routines, these routines will issue floating-point +operations. If you are compiling for an Alpha without floating-point +operations, you must ensure that the library is built so as not to call +them. + +Note that Alpha implementations without floating-point operations are +required to have floating-point registers. + +@item -mfp-reg +@itemx -mno-fp-regs +Generate code that uses (does not use) the floating-point register set. +@code{-mno-fp-regs} implies @code{-msoft-float}. If the floating-point +register set is not used, floating point operands are passed in integer +registers as if they were integers and floating-point results are passed +in $0 instead of $f0. This is a non-standard calling sequence, so any +function with a floating-point argument or return value called by code +compiled with @code{-mno-fp-regs} must also be compiled with that +option. + +A typical use of this option is building a kernel that does not use, +and hence need not save and restore, any floating-point registers. +@end table + +@node Clipper Options +@subsection Clipper Options + +These @samp{-m} options are defined for the Clipper implementations: + +@table @code +@item -mc300 +Produce code for a C300 Clipper processor. This is the default. + +@itemx -mc400 +Produce code for a C400 Clipper processor i.e. use floting point +registers f8..f15. +@end table + +@node H8/300 Options +@subsection H8/300 Options + +These @samp{-m} options are defined for the H8/300 implementations: + +@table @code +@item -mrelax +Shorten some address references at link time, when possible; uses the +linker option @samp{-relax}. @xref{H8/300,, @code{ld} and the H8/300, +ld.info, Using ld}, for a fuller description. + +@item -mh +Generate code for the H8/300H. +@end table + +@node System V Options +@subsection Options for System V + +These additional options are available on System V Release 4 for +compatibility with other compilers on those systems: + +@table @code +@ignore +This should say *what the option does* and only then say +"For compatibility only..." +@item -G +On SVr4 systems, @code{gcc} accepts the option @samp{-G} (and passes +it to the system linker), for compatibility with other compilers. +However, we suggest you use @samp{-symbolic} or @samp{-shared} as +appropriate, instead of supplying linker options on the @code{gcc} +command line. +@end ignore + +@item -Qy +Identify the versions of each tool used by the compiler, in a +@code{.ident} assembler directive in the output. + +@item -Qn +Refrain from adding @code{.ident} directives to the output file (this is +the default). + +@item -YP,@var{dirs} +Search the directories @var{dirs}, and no others, for libraries +specified with @samp{-l}. + +@item -Ym,@var{dir} +Look in the directory @var{dir} to find the M4 preprocessor. +The assembler uses this option. +@c This is supposed to go with a -Yd for predefined M4 macro files, but +@c the generic assembler that comes with Solaris takes just -Ym. +@end table + +@node Code Gen Options +@section Options for Code Generation Conventions +@cindex code generation conventions +@cindex options, code generation +@cindex run-time options + +These machine-independent options control the interface conventions +used in code generation. + +Most of them have both positive and negative forms; the negative form +of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only +one of the forms is listed---the one which is not the default. You +can figure out the other form by either removing @samp{no-} or adding +it. + +@table @code +@item -fpcc-struct-return +Return ``short'' @code{struct} and @code{union} values in memory like +longer ones, rather than in registers. This convention is less +efficient, but it has the advantage of allowing intercallability between +GNU CC-compiled files and files compiled with other compilers. + +The precise convention for returning structures in memory depends +on the target configuration macros. + +Short structures and unions are those whose size and alignment match +that of some integer type. + +@item -freg-struct-return +Use the convention that @code{struct} and @code{union} values are +returned in registers when possible. This is more efficient for small +structures than @samp{-fpcc-struct-return}. + +If you specify neither @samp{-fpcc-struct-return} nor its contrary +@samp{-freg-struct-return}, GNU CC defaults to whichever convention is +standard for the target. If there is no standard convention, GNU CC +defaults to @samp{-fpcc-struct-return}, except on targets where GNU CC +is the principal compiler. In those cases, we can choose the standard, +and we chose the more efficient register return alternative. + +@item -fshort-enums +Allocate to an @code{enum} type only as many bytes as it needs for the +declared range of possible values. Specifically, the @code{enum} type +will be equivalent to the smallest integer type which has enough room. + +@item -fshort-double +Use the same size for @code{double} as for @code{float}. + +@item -fshared-data +Requests that the data and non-@code{const} variables of this +compilation be shared data rather than private data. The distinction +makes sense only on certain operating systems, where shared data is +shared between processes running the same program, while private data +exists in one copy per process. + +@item -fno-common +Allocate even uninitialized global variables in the bss section of the +object file, rather than generating them as common blocks. This has the +effect that if the same variable is declared (without @code{extern}) in +two different compilations, you will get an error when you link them. +The only reason this might be useful is if you wish to verify that the +program will work on other systems which always work this way. + +@item -fno-ident +Ignore the @samp{#ident} directive. + +@item -fno-gnu-linker +Do not output global initializations (such as C++ constructors and +destructors) in the form used by the GNU linker (on systems where the GNU +linker is the standard method of handling them). Use this option when +you want to use a non-GNU linker, which also requires using the +@code{collect2} program to make sure the system linker includes +constructors and destructors. (@code{collect2} is included in the GNU CC +distribution.) For systems which @emph{must} use @code{collect2}, the +compiler driver @code{gcc} is configured to do this automatically. + +@item -finhibit-size-directive +Don't output a @code{.size} assembler directive, or anything else that +would cause trouble if the function is split in the middle, and the +two halves are placed at locations far apart in memory. This option is +used when compiling @file{crtstuff.c}; you should not need to use it +for anything else. + +@item -fverbose-asm +Put extra commentary information in the generated assembly code to +make it more readable. This option is generally only of use to those +who actually need to read the generated assembly code (perhaps while +debugging the compiler itself). + +@item -fvolatile +Consider all memory references through pointers to be volatile. + +@item -fvolatile-global +Consider all memory references to extern and global data items to +be volatile. + +@item -fpic +@cindex global offset table +@cindex PIC +Generate position-independent code (PIC) suitable for use in a shared +library, if supported for the target machine. Such code accesses all +constant addresses through a global offset table (GOT). If the GOT size +for the linked executable exceeds a machine-specific maximum size, you +get an error message from the linker indicating that @samp{-fpic} does +not work; in that case, recompile with @samp{-fPIC} 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 +only on certain machines. For the 386, GNU CC supports PIC for System V +but not for the Sun 386i. Code generated for the IBM RS/6000 is always +position-independent. + +The GNU assembler does not fully support PIC. Currently, you must use +some other assembler in order for PIC to work. We would welcome +volunteers to upgrade GAS to handle this; the first part of the job is +to figure out what the assembler must do differently. + +@item -fPIC +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. + +Position-independent code requires special support, and therefore works +only on certain machines. + +@item -ffixed-@var{reg} +Treat the register named @var{reg} as a fixed register; generated code +should never refer to it (except perhaps as a stack pointer, frame +pointer or in some other fixed role). + +@var{reg} must be the name of a register. The register names accepted +are machine-specific and are defined in the @code{REGISTER_NAMES} +macro in the machine description macro file. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item -fcall-used-@var{reg} +Treat the register named @var{reg} as an allocatable register that is +clobbered by function calls. It may be allocated for temporaries or +variables that do not live across a call. Functions compiled this way +will not save and restore the register @var{reg}. + +Use of this flag for a register that has a fixed pervasive role in the +machine's execution model, such as the stack pointer or frame pointer, +will produce disastrous results. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item -fcall-saved-@var{reg} +Treat the register named @var{reg} as an allocatable register saved by +functions. It may be allocated even for temporaries or variables that +live across a call. Functions compiled this way will save and restore +the register @var{reg} if they use it. + +Use of this flag for a register that has a fixed pervasive role in the +machine's execution model, such as the stack pointer or frame pointer, +will produce disastrous results. + +A different sort of disaster will result from the use of this flag for +a register in which function values may be returned. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item +e0 +@itemx +e1 +Control whether virtual function definitions in classes are used to +generate code, or only to define interfaces for their callers. (C++ +only). + +These options are provided for compatibility with @code{cfront} 1.x +usage; the recommended alternative GNU C++ usage is in flux. @xref{C++ +Interface,,Declarations and Definitions in One Header}. + +With @samp{+e0}, virtual function definitions in classes are declared +@code{extern}; the declaration is used only as an interface +specification, not to generate code for the virtual functions (in this +compilation). + +With @samp{+e1}, G++ actually generates the code implementing virtual +functions defined in the code, and makes them publicly visible. +@end table + +@node Environment Variables +@section Environment Variables Affecting GNU CC +@cindex environment variables + +This section describes several environment variables that affect how GNU +CC operates. They work by specifying directories or prefixes to use +when searching for various kinds of files. + +@ifclear INTERNALS +Note that you can also specify places to search using options such as +@samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These +take precedence over places specified using environment variables, which +in turn take precedence over those specified by the configuration of GNU +CC. +@end ifclear +@ifset INTERNALS +Note that you can also specify places to search using options such as +@samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}). These +take precedence over places specified using environment variables, which +in turn take precedence over those specified by the configuration of GNU +CC. @xref{Driver}. +@end ifset + +@table @code +@item TMPDIR +@findex TMPDIR +If @code{TMPDIR} is set, it specifies the directory to use for temporary +files. GNU CC uses temporary files to hold the output of one stage of +compilation which is to be used as input to the next stage: for example, +the output of the preprocessor, which is the input to the compiler +proper. + +@item GCC_EXEC_PREFIX +@findex GCC_EXEC_PREFIX +If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the +names of the subprograms executed by the compiler. No slash is added +when this prefix is combined with the name of a subprogram, but you can +specify a prefix that ends with a slash if you wish. + +If GNU CC cannot find the subprogram using the specified prefix, it +tries looking in the usual places for the subprogram. + +The default value of @code{GCC_EXEC_PREFIX} is +@file{@var{prefix}/lib/gcc-lib/@var{machine}/@var{version}/} where +@var{prefix} is the value of @code{prefix} when you ran the +@file{configure} script and @var{machine} and @var{version} are the +configuration name and version number of GNU CC, respectively. + +Other prefixes specified with @samp{-B} take precedence over this prefix. + +This prefix is also used for finding files such as @file{crt0.o} that are +used for linking. + +In addition, the prefix is used in an unusual way in finding the +directories to search for header files. For each of the standard +directories whose name normally begins with @samp{/usr/local/lib/gcc-lib} +(more precisely, with the value of @code{GCC_INCLUDE_DIR}), GNU CC tries +replacing that beginning with the specified prefix to produce an +alternate directory name. Thus, with @samp{-Bfoo/}, GNU CC will search +@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}. +These alternate directories are searched first; the standard directories +come next. + +@item COMPILER_PATH +@findex COMPILER_PATH +The value of @code{COMPILER_PATH} is a colon-separated list of +directories, much like @code{PATH}. GNU CC tries the directories thus +specified when searching for subprograms, if it can't find the +subprograms using @code{GCC_EXEC_PREFIX}. + +@item LIBRARY_PATH +@findex LIBRARY_PATH +The value of @code{LIBRARY_PATH} is a colon-separated list of +directories, much like @code{PATH}. GNU CC tries the directories thus +specified when searching for special linker files, if it can't find them +using @code{GCC_EXEC_PREFIX}. Linking using GNU CC also uses these +directories when searching for ordinary libraries for the @samp{-l} +option (but directories specified with @samp{-L} come first). + +@item C_INCLUDE_PATH +@itemx CPLUS_INCLUDE_PATH +@itemx OBJC_INCLUDE_PATH +@findex C_INCLUDE_PATH +@findex CPLUS_INCLUDE_PATH +@findex OBJC_INCLUDE_PATH +@c @itemx OBJCPLUS_INCLUDE_PATH +These environment variables pertain to particular languages. Each +variable's value is a colon-separated list of directories, much like +@code{PATH}. When GNU CC searches for header files, it tries the +directories listed in the variable for the language you are using, after +the directories specified with @samp{-I} but before the standard header +file directories. + +@item DEPENDENCIES_OUTPUT +@findex 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 header files processed by the compiler. This +output looks much like the output from the @samp{-M} option +(@pxref{Preprocessor Options}), but it goes to a separate file, and is +in addition to the usual results of compilation. + +The value of @code{DEPENDENCIES_OUTPUT} can be just a file name, in +which case the Make rules are written to that file, guessing the target +name from the source file name. Or the value can have the form +@samp{@var{file} @var{target}}, in which case the rules are written to +file @var{file} using @var{target} as the target name. +@end table + +@node Running Protoize +@section Running Protoize + +The program @code{protoize} is an optional part of GNU C. You can use +it to add prototypes to a program, thus converting the program to ANSI +C in one respect. The companion program @code{unprotoize} does the +reverse: it removes argument types from any prototypes that are found. + +When you run these programs, you must specify a set of source files as +command line arguments. The conversion programs start out by compiling +these files to see what functions they define. The information gathered +about a file @var{foo} is saved in a file named @file{@var{foo}.X}. + +After scanning comes actual conversion. The specified files are all +eligible to be converted; any files they include (whether sources or +just headers) are eligible as well. + +But not all the eligible files are converted. By default, +@code{protoize} and @code{unprotoize} convert only source and header +files in the current directory. You can specify additional directories +whose files should be converted with the @samp{-d @var{directory}} +option. You can also specify particular files to exclude with the +@samp{-x @var{file}} option. A file is converted if it is eligible, its +directory name matches one of the specified directory names, and its +name within the directory has not been excluded. + +Basic conversion with @code{protoize} consists of rewriting most +function definitions and function declarations to specify the types of +the arguments. The only ones not rewritten are those for varargs +functions. + +@code{protoize} optionally inserts prototype declarations at the +beginning of the source file, to make them available for any calls that +precede the function's definition. Or it can insert prototype +declarations with block scope in the blocks where undeclared functions +are called. + +Basic conversion with @code{unprotoize} consists of rewriting most +function declarations to remove any argument types, and rewriting +function definitions to the old-style pre-ANSI form. + +Both conversion programs print a warning for any function declaration or +definition that they can't convert. You can suppress these warnings +with @samp{-q}. + +The output from @code{protoize} or @code{unprotoize} replaces the +original source file. The original file is renamed to a name ending +with @samp{.save}. If the @samp{.save} file already exists, then +the source file is simply discarded. + +@code{protoize} and @code{unprotoize} both depend on GNU CC itself to +scan the program and collect information about the functions it uses. +So neither of these programs will work until GNU CC is installed. + +Here is a table of the options you can use with @code{protoize} and +@code{unprotoize}. Each option works with both programs unless +otherwise stated. + +@table @code +@item -B @var{directory} +Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the +usual directory (normally @file{/usr/local/lib}). This file contains +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 +produce the @samp{.X} files. The special option @samp{-aux-info} is +always passed in addition, to tell @code{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 +to make them a single word in the shell. + +There are certain @code{gcc} arguments that you cannot use, because they +would produce the wrong kind of output. These include @samp{-g}, +@samp{-O}, @samp{-c}, @samp{-S}, and @samp{-o} If you include these in +the @var{compilation-options}, they are ignored. + +@item -C +Rename files to end in @samp{.C} instead of @samp{.c}. +This is convenient if you are converting a C program to C++. +This option applies only to @code{protoize}. + +@item -g +Add explicit global declarations. This means inserting explicit +declarations at the beginning of each source file for each function +that is called in the file and was not declared. These declarations +precede the first function definition that contains a call to an +undeclared function. This option applies only to @code{protoize}. + +@item -i @var{string} +Indent old-style parameter declarations with the string @var{string}. +This option applies only to @code{protoize}. + +@code{unprotoize} converts prototyped function definitions to old-style +function definitions, where the arguments are declared between the +argument list and the initial @samp{@{}. By default, @code{unprotoize} +uses five spaces as the indentation. If you want to indent with just +one space instead, use @samp{-i " "}. + +@item -k +Keep the @samp{.X} files. Normally, they are deleted after conversion +is finished. + +@item -l +Add explicit local declarations. @code{protoize} with @samp{-l} inserts +a prototype declaration for each function in each block which calls the +function without any declaration. This option applies only to +@code{protoize}. + +@item -n +Make no real changes. This mode just prints information about the conversions +that would have been done without @samp{-n}. + +@item -N +Make no @samp{.save} files. The original files are simply deleted. +Use this option with caution. + +@item -p @var{program} +Use the program @var{program} as the compiler. Normally, the name +@file{gcc} is used. + +@item -q +Work quietly. Most warnings are suppressed. + +@item -v +Print the version number, just like @samp{-v} for @code{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 +appropriate options and the option @samp{-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. +For example: + +@example +gcc -Dfoo=bar file1.c -aux-info +protoize *.c +@end example + +@noindent +You need to include the special files along with the rest in the +@code{protoize} command, even though their @samp{.X} files already +exist, because otherwise they won't get converted. + +@xref{Protoize Caveats}, for more information on how to use +@code{protoize} successfully. + diff --git a/gnu/usr.bin/cc/doc/md.texi b/gnu/usr.bin/cc/doc/md.texi new file mode 100644 index 0000000..d29eabb --- /dev/null +++ b/gnu/usr.bin/cc/doc/md.texi @@ -0,0 +1,3965 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@ifset INTERNALS +@node Machine Desc +@chapter Machine Descriptions +@cindex machine descriptions + +A machine description has two parts: a file of instruction patterns +(@file{.md} file) and a C header file of macro definitions. + +The @file{.md} file for a target machine contains a pattern for each +instruction that the target machine supports (or at least each instruction +that is worth telling the compiler about). It may also contain comments. +A semicolon causes the rest of the line to be a comment, unless the semicolon +is inside a quoted string. + +See the next chapter for information on the C header file. + +@menu +* Patterns:: How to write instruction patterns. +* Example:: An explained example of a @code{define_insn} pattern. +* RTL Template:: The RTL template defines what insns match a pattern. +* Output Template:: The output template says how to make assembler code + from such an insn. +* Output Statement:: For more generality, write C code to output + the assembler code. +* Constraints:: When not all operands are general operands. +* Standard Names:: Names mark patterns to use for code generation. +* Pattern Ordering:: When the order of patterns makes a difference. +* Dependent Patterns:: Having one pattern may make you need another. +* Jump Patterns:: Special considerations for patterns for jump insns. +* Insn Canonicalizations::Canonicalization of Instructions +* Peephole Definitions::Defining machine-specific peephole optimizations. +* Expander Definitions::Generating a sequence of several RTL insns + for a standard operation. +* Insn Splitting:: Splitting Instructions into Multiple Instructions +* Insn Attributes:: Specifying the value of attributes for generated insns. +@end menu + +@node Patterns +@section Everything about Instruction Patterns +@cindex patterns +@cindex instruction patterns + +@findex define_insn +Each instruction pattern contains an incomplete RTL expression, with pieces +to be filled in later, operand constraints that restrict how the pieces can +be filled in, and an output pattern or C code to generate the assembler +output, all wrapped up in a @code{define_insn} expression. + +A @code{define_insn} is an RTL expression containing four or five operands: + +@enumerate +@item +An optional name. The presence of a name indicate that this instruction +pattern can perform a certain standard job for the RTL-generation +pass of the compiler. This pass knows certain names and will use +the instruction patterns with those names, if the names are defined +in the machine description. + +The absence of a name is indicated by writing an empty string +where the name should go. Nameless instruction patterns are never +used for generating RTL code, but they may permit several simpler insns +to be combined later on. + +Names that are not thus known and used in RTL-generation have no +effect; they are equivalent to no name at all. + +@item +The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete +RTL expressions which show what the instruction should look like. It is +incomplete because it may contain @code{match_operand}, +@code{match_operator}, and @code{match_dup} expressions that stand for +operands of the instruction. + +If the vector has only one element, that element is the template for the +instruction pattern. If the vector has multiple elements, then the +instruction pattern is a @code{parallel} expression containing the +elements described. + +@item +@cindex pattern conditions +@cindex conditions, in patterns +A condition. This is a string which contains a C expression that is +the final test to decide whether an insn body matches this pattern. + +@cindex named patterns and conditions +For a named pattern, the condition (if present) may not depend on +the data in the insn being matched, but only the target-machine-type +flags. The compiler needs to test these conditions during +initialization in order to learn exactly which named instructions are +available in a particular run. + +@findex operands +For nameless patterns, the condition is applied only when matching an +individual insn, and only after the insn has matched the pattern's +recognition template. The insn's operands may be found in the vector +@code{operands}. + +@item +The @dfn{output template}: a string that says how to output matching +insns as assembler code. @samp{%} in this string specifies where +to substitute the value of an operand. @xref{Output Template}. + +When simple substitution isn't general enough, you can specify a piece +of C code to compute the output. @xref{Output Statement}. + +@item +Optionally, a vector containing the values of attributes for insns matching +this pattern. @xref{Insn Attributes}. +@end enumerate + +@node Example +@section Example of @code{define_insn} +@cindex @code{define_insn} example + +Here is an actual example of an instruction pattern, for the 68000/68020. + +@example +(define_insn "tstsi" + [(set (cc0) + (match_operand:SI 0 "general_operand" "rm"))] + "" + "* +@{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0])) + return \"tstl %0\"; + return \"cmpl #0,%0\"; @}") +@end example + +This is an instruction that sets the condition codes based on the value of +a general operand. It has no condition, so any insn whose RTL description +has the form shown may be handled according to this pattern. The name +@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation +pass that, when it is necessary to test such a value, an insn to do so +can be constructed using this pattern. + +The output control string is a piece of C code which chooses which +output template to return based on the kind of operand and the specific +type of CPU for which code is being generated. + +@samp{"rm"} is an operand constraint. Its meaning is explained below. + +@node RTL Template +@section RTL Template +@cindex RTL insn template +@cindex generating insns +@cindex insns, generating +@cindex recognizing insns +@cindex insns, recognizing + +The RTL template is used to define which insns match the particular pattern +and how to find their operands. For named patterns, the RTL template also +says how to construct an insn from specified operands. + +Construction involves substituting specified operands into a copy of the +template. Matching involves determining the values that serve as the +operands in the insn being matched. Both of these activities are +controlled by special expression types that direct matching and +substitution of the operands. + +@table @code +@findex match_operand +@item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint}) +This expression is a placeholder for operand number @var{n} of +the insn. When constructing an insn, operand number @var{n} +will be substituted at this point. When matching an insn, whatever +appears at this position in the insn will be taken as operand +number @var{n}; but it must satisfy @var{predicate} or this instruction +pattern will not match at all. + +Operand numbers must be chosen consecutively counting from zero in +each instruction pattern. There may be only one @code{match_operand} +expression in the pattern for each operand number. Usually operands +are numbered in the order of appearance in @code{match_operand} +expressions. + +@var{predicate} is a string that is the name of a C function that accepts two +arguments, an expression and a machine mode. During matching, the +function will be called with the putative operand as the expression and +@var{m} as the mode argument (if @var{m} is not specified, +@code{VOIDmode} will be used, which normally causes @var{predicate} to accept +any mode). If it returns zero, this instruction pattern fails to match. +@var{predicate} may be an empty string; then it means no test is to be done +on the operand, so anything which occurs in this position is valid. + +Most of the time, @var{predicate} will reject modes other than @var{m}---but +not always. For example, the predicate @code{address_operand} uses +@var{m} as the mode of memory ref that the address should be valid for. +Many predicates accept @code{const_int} nodes even though their mode is +@code{VOIDmode}. + +@var{constraint} controls reloading and the choice of the best register +class to use for a value, as explained later (@pxref{Constraints}). + +People are often unclear on the difference between the constraint and the +predicate. The predicate helps decide whether a given insn matches the +pattern. The constraint plays no role in this decision; instead, it +controls various decisions in the case of an insn which does match. + +@findex general_operand +On CISC machines, the most common @var{predicate} is +@code{"general_operand"}. This function checks that the putative +operand is either a constant, a register or a memory reference, and that +it is valid for mode @var{m}. + +@findex register_operand +For an operand that must be a register, @var{predicate} should be +@code{"register_operand"}. Using @code{"general_operand"} would be +valid, since the reload pass would copy any non-register operands +through registers, but this would make GNU CC do extra work, it would +prevent invariant operands (such as constant) from being removed from +loops, and it would prevent the register allocator from doing the best +possible job. On RISC machines, it is usually most efficient to allow +@var{predicate} to accept only objects that the constraints allow. + +@findex immediate_operand +For an operand that must be a constant, you must be sure to either use +@code{"immediate_operand"} for @var{predicate}, or make the instruction +pattern's extra condition require a constant, or both. You cannot +expect the constraints to do this work! If the constraints allow only +constants, but the predicate allows something else, the compiler will +crash when that case arises. + +@findex match_scratch +@item (match_scratch:@var{m} @var{n} @var{constraint}) +This expression is also a placeholder for operand number @var{n} +and indicates that operand must be a @code{scratch} or @code{reg} +expression. + +When matching patterns, this is equivalent to + +@smallexample +(match_operand:@var{m} @var{n} "scratch_operand" @var{pred}) +@end smallexample + +but, when generating RTL, it produces a (@code{scratch}:@var{m}) +expression. + +If the last few expressions in a @code{parallel} are @code{clobber} +expressions whose operands are either a hard register or +@code{match_scratch}, the combiner can add or delete them when +necessary. @xref{Side Effects}. + +@findex match_dup +@item (match_dup @var{n}) +This expression is also a placeholder for operand number @var{n}. +It is used when the operand needs to appear more than once in the +insn. + +In construction, @code{match_dup} acts just like @code{match_operand}: +the operand is substituted into the insn being constructed. But in +matching, @code{match_dup} behaves differently. It assumes that operand +number @var{n} has already been determined by a @code{match_operand} +appearing earlier in the recognition template, and it matches only an +identical-looking expression. + +@findex match_operator +@item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}]) +This pattern is a kind of placeholder for a variable RTL expression +code. + +When constructing an insn, it stands for an RTL expression whose +expression code is taken from that of operand @var{n}, and whose +operands are constructed from the patterns @var{operands}. + +When matching an expression, it matches an expression if the function +@var{predicate} returns nonzero on that expression @emph{and} the +patterns @var{operands} match the operands of the expression. + +Suppose that the function @code{commutative_operator} is defined as +follows, to match any expression whose operator is one of the +commutative arithmetic operators of RTL and whose mode is @var{mode}: + +@smallexample +int +commutative_operator (x, mode) + rtx x; + enum machine_mode mode; +@{ + enum rtx_code code = GET_CODE (x); + if (GET_MODE (x) != mode) + return 0; + return (GET_RTX_CLASS (code) == 'c' + || code == EQ || code == NE); +@} +@end smallexample + +Then the following pattern will match any RTL expression consisting +of a commutative operator applied to two general operands: + +@smallexample +(match_operator:SI 3 "commutative_operator" + [(match_operand:SI 1 "general_operand" "g") + (match_operand:SI 2 "general_operand" "g")]) +@end smallexample + +Here the vector @code{[@var{operands}@dots{}]} contains two patterns +because the expressions to be matched all contain two operands. + +When this pattern does match, the two operands of the commutative +operator are recorded as operands 1 and 2 of the insn. (This is done +by the two instances of @code{match_operand}.) Operand 3 of the insn +will be the entire commutative expression: use @code{GET_CODE +(operands[3])} to see which commutative operator was used. + +The machine mode @var{m} of @code{match_operator} works like that of +@code{match_operand}: it is passed as the second argument to the +predicate function, and that function is solely responsible for +deciding whether the expression to be matched ``has'' that mode. + +When constructing an insn, argument 3 of the gen-function will specify +the operation (i.e. the expression code) for the expression to be +made. It should be an RTL expression, whose expression code is copied +into a new expression whose operands are arguments 1 and 2 of the +gen-function. The subexpressions of argument 3 are not used; +only its expression code matters. + +When @code{match_operator} is used in a pattern for matching an insn, +it usually best if the operand number of the @code{match_operator} +is higher than that of the actual operands of the insn. This improves +register allocation because the register allocator often looks at +operands 1 and 2 of insns to see if it can do register tying. + +There is no way to specify constraints in @code{match_operator}. The +operand of the insn which corresponds to the @code{match_operator} +never has any constraints because it is never reloaded as a whole. +However, if parts of its @var{operands} are matched by +@code{match_operand} patterns, those parts may have constraints of +their own. + +@findex match_op_dup +@item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}]) +Like @code{match_dup}, except that it applies to operators instead of +operands. When constructing an insn, operand number @var{n} will be +substituted at this point. But in matching, @code{match_op_dup} behaves +differently. It assumes that operand number @var{n} has already been +determined by a @code{match_operator} appearing earlier in the +recognition template, and it matches only an identical-looking +expression. + +@findex match_parallel +@item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}]) +This pattern is a placeholder for an insn that consists of a +@code{parallel} expression with a variable number of elements. This +expression should only appear at the top level of an insn pattern. + +When constructing an insn, operand number @var{n} will be substituted at +this point. When matching an insn, it matches if the body of the insn +is a @code{parallel} expression with at least as many elements as the +vector of @var{subpat} expressions in the @code{match_parallel}, if each +@var{subpat} matches the corresponding element of the @code{parallel}, +@emph{and} the function @var{predicate} returns nonzero on the +@code{parallel} that is the body of the insn. It is the responsibility +of the predicate to validate elements of the @code{parallel} beyond +those listed in the @code{match_parallel}.@refill + +A typical use of @code{match_parallel} is to match load and store +multiple expressions, which can contain a variable number of elements +in a @code{parallel}. For example, +@c the following is *still* going over. need to change the code. +@c also need to work on grouping of this example. --mew 1feb93 + +@smallexample +(define_insn "" + [(match_parallel 0 "load_multiple_operation" + [(set (match_operand:SI 1 "gpc_reg_operand" "=r") + (match_operand:SI 2 "memory_operand" "m")) + (use (reg:SI 179)) + (clobber (reg:SI 179))])] + "" + "loadm 0,0,%1,%2") +@end smallexample + +This example comes from @file{a29k.md}. The function +@code{load_multiple_operations} is defined in @file{a29k.c} and checks +that subsequent elements in the @code{parallel} are the same as the +@code{set} in the pattern, except that they are referencing subsequent +registers and memory locations. + +An insn that matches this pattern might look like: + +@smallexample +(parallel + [(set (reg:SI 20) (mem:SI (reg:SI 100))) + (use (reg:SI 179)) + (clobber (reg:SI 179)) + (set (reg:SI 21) + (mem:SI (plus:SI (reg:SI 100) + (const_int 4)))) + (set (reg:SI 22) + (mem:SI (plus:SI (reg:SI 100) + (const_int 8))))]) +@end smallexample + +@findex match_par_dup +@item (match_par_dup @var{n} [@var{subpat}@dots{}]) +Like @code{match_op_dup}, but for @code{match_parallel} instead of +@code{match_operator}. + +@findex address +@item (address (match_operand:@var{m} @var{n} "address_operand" "")) +This complex of expressions is a placeholder for an operand number +@var{n} in a ``load address'' instruction: an operand which specifies +a memory location in the usual way, but for which the actual operand +value used is the address of the location, not the contents of the +location. + +@code{address} expressions never appear in RTL code, only in machine +descriptions. And they are used only in machine descriptions that do +not use the operand constraint feature. When operand constraints are +in use, the letter @samp{p} in the constraint serves this purpose. + +@var{m} is the machine mode of the @emph{memory location being +addressed}, not the machine mode of the address itself. That mode is +always the same on a given target machine (it is @code{Pmode}, which +normally is @code{SImode}), so there is no point in mentioning it; +thus, no machine mode is written in the @code{address} expression. If +some day support is added for machines in which addresses of different +kinds of objects appear differently or are used differently (such as +the PDP-10), different formats would perhaps need different machine +modes and these modes might be written in the @code{address} +expression. +@end table + +@node Output Template +@section Output Templates and Operand Substitution +@cindex output templates +@cindex operand substitution + +@cindex @samp{%} in template +@cindex percent sign +The @dfn{output template} is a string which specifies how to output the +assembler code for an instruction pattern. Most of the template is a +fixed string which is output literally. The character @samp{%} is used +to specify where to substitute an operand; it can also be used to +identify places where different variants of the assembler require +different syntax. + +In the simplest case, a @samp{%} followed by a digit @var{n} says to output +operand @var{n} at that point in the string. + +@samp{%} followed by a letter and a digit says to output an operand in an +alternate fashion. Four letters have standard, built-in meanings described +below. The machine description macro @code{PRINT_OPERAND} can define +additional letters with nonstandard meanings. + +@samp{%c@var{digit}} can be used to substitute an operand that is a +constant value without the syntax that normally indicates an immediate +operand. + +@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of +the constant is negated before printing. + +@samp{%a@var{digit}} can be used to substitute an operand as if it were a +memory reference, with the actual operand treated as the address. This may +be useful when outputting a ``load address'' instruction, because often the +assembler syntax for such an instruction requires you to write the operand +as if it were a memory reference. + +@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump +instruction. + +@samp{%=} outputs a number which is unique to each instruction in the +entire compilation. This is useful for making local labels to be +referred to more than once in a single template that generates multiple +assembler instructions. + +@samp{%} followed by a punctuation character specifies a substitution that +does not use an operand. Only one case is standard: @samp{%%} outputs a +@samp{%} into the assembler code. Other nonstandard cases can be +defined in the @code{PRINT_OPERAND} macro. You must also define +which punctuation characters are valid with the +@code{PRINT_OPERAND_PUNCT_VALID_P} macro. + +@cindex \ +@cindex backslash +The template may generate multiple assembler instructions. Write the text +for the instructions, with @samp{\;} between them. + +@cindex matching operands +When the RTL contains two operands which are required by constraint to match +each other, the output template must refer only to the lower-numbered operand. +Matching operands are not always identical, and the rest of the compiler +arranges to put the proper RTL expression for printing into the lower-numbered +operand. + +One use of nonstandard letters or punctuation following @samp{%} is to +distinguish between different assembler languages for the same machine; for +example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax +requires periods in most opcode names, while MIT syntax does not. For +example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola +syntax. The same file of patterns is used for both kinds of output syntax, +but the character sequence @samp{%.} is used in each place where Motorola +syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax +defines the sequence to output a period; the macro for MIT syntax defines +it to do nothing. + +@cindex @code{#} in template +As a special case, a template consisting of the single character @code{#} +instructs the compiler to first split the insn, and then output the +resulting instructions separately. This helps eliminate redundancy in the +output templates. If you have a @code{define_insn} that needs to emit +multiple assembler instructions, and there is an matching @code{define_split} +already defined, then you can simply use @code{#} as the output template +instead of writing an output template that emits the multiple assembler +instructions. + +If @code{ASSEMBLER_DIALECT} is defined, you can use +@samp{@{option0|option1|option2@}} constructs in the templates. These +describe multiple variants of assembler language syntax. +@xref{Instruction Output}. + +@node Output Statement +@section C Statements for Assembler Output +@cindex output statements +@cindex C statements for assembler output +@cindex generating assembler output + +Often a single fixed template string cannot produce correct and efficient +assembler code for all the cases that are recognized by a single +instruction pattern. For example, the opcodes may depend on the kinds of +operands; or some unfortunate combinations of operands may require extra +machine instructions. + +If the output control string starts with a @samp{@@}, then it is actually +a series of templates, each on a separate line. (Blank lines and +leading spaces and tabs are ignored.) The templates correspond to the +pattern's constraint alternatives (@pxref{Multi-Alternative}). For example, +if a target machine has a two-address add instruction @samp{addr} to add +into a register and another @samp{addm} to add a register to memory, you +might write this pattern: + +@smallexample +(define_insn "addsi3" + [(set (match_operand:SI 0 "general_operand" "=r,m") + (plus:SI (match_operand:SI 1 "general_operand" "0,0") + (match_operand:SI 2 "general_operand" "g,r")))] + "" + "@@ + addr %2,%0 + addm %2,%0") +@end smallexample + +@cindex @code{*} in template +@cindex asterisk in template +If the output control string starts with a @samp{*}, then it is not an +output template but rather a piece of C program that should compute a +template. It should execute a @code{return} statement to return the +template-string you want. Most such templates use C string literals, which +require doublequote characters to delimit them. To include these +doublequote characters in the string, prefix each one with @samp{\}. + +The operands may be found in the array @code{operands}, whose C data type +is @code{rtx []}. + +It is very common to select different ways of generating assembler code +based on whether an immediate operand is within a certain range. Be +careful when doing this, because the result of @code{INTVAL} is an +integer on the host machine. If the host machine has more bits in an +@code{int} than the target machine has in the mode in which the constant +will be used, then some of the bits you get from @code{INTVAL} will be +superfluous. For proper results, you must carefully disregard the +values of those bits. + +@findex output_asm_insn +It is possible to output an assembler instruction and then go on to output +or compute more of them, using the subroutine @code{output_asm_insn}. This +receives two arguments: a template-string and a vector of operands. The +vector may be @code{operands}, or it may be another array of @code{rtx} +that you declare locally and initialize yourself. + +@findex which_alternative +When an insn pattern has multiple alternatives in its constraints, often +the appearance of the assembler code is determined mostly by which alternative +was matched. When this is so, the C code can test the variable +@code{which_alternative}, which is the ordinal number of the alternative +that was actually satisfied (0 for the first, 1 for the second alternative, +etc.). + +For example, suppose there are two opcodes for storing zero, @samp{clrreg} +for registers and @samp{clrmem} for memory locations. Here is how +a pattern could use @code{which_alternative} to choose between them: + +@smallexample +(define_insn "" + [(set (match_operand:SI 0 "general_operand" "=r,m") + (const_int 0))] + "" + "* + return (which_alternative == 0 + ? \"clrreg %0\" : \"clrmem %0\"); + ") +@end smallexample + +The example above, where the assembler code to generate was +@emph{solely} determined by the alternative, could also have been specified +as follows, having the output control string start with a @samp{@@}: + +@smallexample +@group +(define_insn "" + [(set (match_operand:SI 0 "general_operand" "=r,m") + (const_int 0))] + "" + "@@ + clrreg %0 + clrmem %0") +@end group +@end smallexample +@end ifset + +@c Most of this node appears by itself (in a different place) even +@c when the INTERNALS flag is clear. Passages that require the full +@c manual's context are conditionalized to appear only in the full manual. +@ifset INTERNALS +@node Constraints +@section Operand Constraints +@cindex operand constraints +@cindex constraints + +Each @code{match_operand} in an instruction pattern can specify a +constraint for the type of operands allowed. +@end ifset +@ifclear INTERNALS +@node Constraints +@section Constraints for @code{asm} Operands +@cindex operand constraints, @code{asm} +@cindex constraints, @code{asm} +@cindex @code{asm} constraints + +Here are specific details on what constraint letters you can use with +@code{asm} operands. +@end ifclear +Constraints can say whether +an operand may be in a register, and which kinds of register; whether the +operand can be a memory reference, and which kinds of address; whether the +operand may be an immediate constant, and which possible values it may +have. Constraints can also require two operands to match. + +@ifset INTERNALS +@menu +* Simple Constraints:: Basic use of constraints. +* Multi-Alternative:: When an insn has two alternative constraint-patterns. +* Class Preferences:: Constraints guide which hard register to put things in. +* Modifiers:: More precise control over effects of constraints. +* Machine Constraints:: Existing constraints for some particular machines. +* No Constraints:: Describing a clean machine without constraints. +@end menu +@end ifset + +@ifclear INTERNALS +@menu +* Simple Constraints:: Basic use of constraints. +* Multi-Alternative:: When an insn has two alternative constraint-patterns. +* Modifiers:: More precise control over effects of constraints. +* Machine Constraints:: Special constraints for some particular machines. +@end menu +@end ifclear + +@node Simple Constraints +@subsection Simple Constraints +@cindex simple constraints + +The simplest kind of constraint is a string full of letters, each of +which describes one kind of operand that is permitted. Here are +the letters that are allowed: + +@table @asis +@cindex @samp{m} in constraint +@cindex memory references in constraints +@item @samp{m} +A memory operand is allowed, with any kind of address that the machine +supports in general. + +@cindex offsettable address +@cindex @samp{o} in constraint +@item @samp{o} +A memory operand is allowed, but only if the address is +@dfn{offsettable}. This means that adding a small integer (actually, +the width in bytes of the operand, as determined by its machine mode) +may be added to the address and the result is also a valid memory +address. + +@cindex autoincrement/decrement addressing +For example, an address which is constant is offsettable; so is an +address that is the sum of a register and a constant (as long as a +slightly larger constant is also within the range of address-offsets +supported by the machine); but an autoincrement or autodecrement +address is not offsettable. More complicated indirect/indexed +addresses may or may not be offsettable depending on the other +addressing modes that the machine supports. + +Note that in an output operand which can be matched by another +operand, the constraint letter @samp{o} is valid only when accompanied +by both @samp{<} (if the target machine has predecrement addressing) +and @samp{>} (if the target machine has preincrement addressing). + +@cindex @samp{V} in constraint +@item @samp{V} +A memory operand that is not offsettable. In other words, anything that +would fit the @samp{m} constraint but not the @samp{o} constraint. + +@cindex @samp{<} in constraint +@item @samp{<} +A memory operand with autodecrement addressing (either predecrement or +postdecrement) is allowed. + +@cindex @samp{>} in constraint +@item @samp{>} +A memory operand with autoincrement addressing (either preincrement or +postincrement) is allowed. + +@cindex @samp{r} in constraint +@cindex registers in constraints +@item @samp{r} +A register operand is allowed provided that it is in a general +register. + +@cindex @samp{d} in constraint +@item @samp{d}, @samp{a}, @samp{f}, @dots{} +Other letters can be defined in machine-dependent fashion to stand for +particular classes of registers. @samp{d}, @samp{a} and @samp{f} are +defined on the 68000/68020 to stand for data, address and floating +point registers. + +@cindex constants in constraints +@cindex @samp{i} in constraint +@item @samp{i} +An immediate integer operand (one with constant value) is allowed. +This includes symbolic constants whose values will be known only at +assembly time. + +@cindex @samp{n} in constraint +@item @samp{n} +An immediate integer operand with a known numeric value is allowed. +Many systems cannot support assembly-time constants for operands less +than a word wide. Constraints for these operands should use @samp{n} +rather than @samp{i}. + +@cindex @samp{I} in constraint +@item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P} +Other letters in the range @samp{I} through @samp{P} may be defined in +a machine-dependent fashion to permit immediate integer operands with +explicit integer values in specified ranges. For example, on the +68000, @samp{I} is defined to stand for the range of values 1 to 8. +This is the range permitted as a shift count in the shift +instructions. + +@cindex @samp{E} in constraint +@item @samp{E} +An immediate floating operand (expression code @code{const_double}) is +allowed, but only if the target floating point format is the same as +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. + +@cindex @samp{G} in constraint +@cindex @samp{H} in constraint +@item @samp{G}, @samp{H} +@samp{G} and @samp{H} may be defined in a machine-dependent fashion to +permit immediate floating operands in particular ranges of values. + +@cindex @samp{s} in constraint +@item @samp{s} +An immediate integer operand whose value is not an explicit integer is +allowed. + +This might appear strange; if an insn allows a constant operand with a +value not known at compile time, it certainly must allow any known +value. So why use @samp{s} instead of @samp{i}? Sometimes it allows +better code to be generated. + +For example, on the 68000 in a fullword instruction it is possible to +use an immediate operand; but if the immediate value is between -128 +and 127, better code results from loading the value into a register and +using the register. This is because the load into the register can be +done with a @samp{moveq} instruction. We arrange for this to happen +by defining the letter @samp{K} to mean ``any integer outside the +range -128 to 127'', and then specifying @samp{Ks} in the operand +constraints. + +@cindex @samp{g} in constraint +@item @samp{g} +Any register, memory or immediate integer operand is allowed, except for +registers that are not general registers. + +@cindex @samp{X} in constraint +@item @samp{X} +@ifset INTERNALS +Any operand whatsoever is allowed, even if it does not satisfy +@code{general_operand}. This is normally used in the constraint of +a @code{match_scratch} when certain alternatives will not actually +require a scratch register. +@end ifset +@ifclear INTERNALS +Any operand whatsoever is allowed. +@end ifclear + +@cindex @samp{0} in constraint +@cindex digits in constraint +@item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9} +An operand that matches the specified operand number is allowed. If a +digit is used together with letters within the same alternative, the +digit should come last. + +@cindex matching constraint +@cindex constraint, matching +This is called a @dfn{matching constraint} and what it really means is +that the assembler has only a single operand that fills two roles +@ifset INTERNALS +considered separate in the RTL insn. For example, an add insn has two +input operands and one output operand in the RTL, but on most CISC +@end ifset +@ifclear INTERNALS +which @code{asm} distinguishes. For example, an add instruction uses +two input operands and an output operand, but on most CISC +@end ifclear +machines an add instruction really has only two operands, one of them an +input-output operand: + +@smallexample +addl #35,r12 +@end smallexample + +Matching constraints are used in these circumstances. +More precisely, the two operands that match must include one input-only +operand and one output-only operand. Moreover, the digit must be a +smaller number than the number of the operand that uses it in the +constraint. + +@ifset INTERNALS +For operands to match in a particular case usually means that they +are identical-looking RTL expressions. But in a few special cases +specific kinds of dissimilarity are allowed. For example, @code{*x} +as an input operand will match @code{*x++} as an output operand. +For proper results in such cases, the output template should always +use the output-operand's number when printing the operand. +@end ifset + +@cindex load address instruction +@cindex push address instruction +@cindex address constraints +@cindex @samp{p} in constraint +@item @samp{p} +An operand that is a valid memory address is allowed. This is +for ``load address'' and ``push address'' instructions. + +@findex address_operand +@samp{p} in the constraint must be accompanied by @code{address_operand} +as the predicate in the @code{match_operand}. This predicate interprets +the mode specified in the @code{match_operand} as the mode of the memory +reference for which the address would be valid. + +@cindex extensible constraints +@cindex @samp{Q}, in constraint +@item @samp{Q}, @samp{R}, @samp{S}, @dots{} @samp{U} +Letters in the range @samp{Q} through @samp{U} may be defined in a +machine-dependent fashion to stand for arbitrary operand types. +@ifset INTERNALS +The machine description macro @code{EXTRA_CONSTRAINT} is passed the +operand as its first argument and the constraint letter as its +second operand. + +A typical use for this would be to distinguish certain types of +memory references that affect other insn operands. + +Do not define these constraint letters to accept register references +(@code{reg}); the reload pass does not expect this and would not handle +it properly. +@end ifset +@end table + +@ifset INTERNALS +In order to have valid assembler code, each operand must satisfy +its constraint. But a failure to do so does not prevent the pattern +from applying to an insn. Instead, it directs the compiler to modify +the code so that the constraint will be satisfied. Usually this is +done by copying an operand into a register. + +Contrast, therefore, the two instruction patterns that follow: + +@smallexample +(define_insn "" + [(set (match_operand:SI 0 "general_operand" "=r") + (plus:SI (match_dup 0) + (match_operand:SI 1 "general_operand" "r")))] + "" + "@dots{}") +@end smallexample + +@noindent +which has two operands, one of which must appear in two places, and + +@smallexample +(define_insn "" + [(set (match_operand:SI 0 "general_operand" "=r") + (plus:SI (match_operand:SI 1 "general_operand" "0") + (match_operand:SI 2 "general_operand" "r")))] + "" + "@dots{}") +@end smallexample + +@noindent +which has three operands, two of which are required by a constraint to be +identical. If we are considering an insn of the form + +@smallexample +(insn @var{n} @var{prev} @var{next} + (set (reg:SI 3) + (plus:SI (reg:SI 6) (reg:SI 109))) + @dots{}) +@end smallexample + +@noindent +the first pattern would not apply at all, because this insn does not +contain two identical subexpressions in the right place. The pattern would +say, ``That does not look like an add instruction; try other patterns.'' +The second pattern would say, ``Yes, that's an add instruction, but there +is something wrong with it.'' It would direct the reload pass of the +compiler to generate additional insns to make the constraint true. The +results might look like this: + +@smallexample +(insn @var{n2} @var{prev} @var{n} + (set (reg:SI 3) (reg:SI 6)) + @dots{}) + +(insn @var{n} @var{n2} @var{next} + (set (reg:SI 3) + (plus:SI (reg:SI 3) (reg:SI 109))) + @dots{}) +@end smallexample + +It is up to you to make sure that each operand, in each pattern, has +constraints that can handle any RTL expression that could be present for +that operand. (When multiple alternatives are in use, each pattern must, +for each possible combination of operand expressions, have at least one +alternative which can handle that combination of operands.) The +constraints don't need to @emph{allow} any possible operand---when this is +the case, they do not constrain---but they must at least point the way to +reloading any possible operand so that it will fit. + +@itemize @bullet +@item +If the constraint accepts whatever operands the predicate permits, +there is no problem: reloading is never necessary for this operand. + +For example, an operand whose constraints permit everything except +registers is safe provided its predicate rejects registers. + +An operand whose predicate accepts only constant values is safe +provided its constraints include the letter @samp{i}. If any possible +constant value is accepted, then nothing less than @samp{i} will do; +if the predicate is more selective, then the constraints may also be +more selective. + +@item +Any operand expression can be reloaded by copying it into a register. +So if an operand's constraints allow some kind of register, it is +certain to be safe. It need not permit all classes of registers; the +compiler knows how to copy a register into another register of the +proper class in order to make an instruction valid. + +@cindex nonoffsettable memory reference +@cindex memory reference, nonoffsettable +@item +A nonoffsettable memory reference can be reloaded by copying the +address into a register. So if the constraint uses the letter +@samp{o}, all memory references are taken care of. + +@item +A constant operand can be reloaded by allocating space in memory to +hold it as preinitialized data. Then the memory reference can be used +in place of the constant. So if the constraint uses the letters +@samp{o} or @samp{m}, constant operands are not a problem. + +@item +If the constraint permits a constant and a pseudo register used in an insn +was not allocated to a hard register and is equivalent to a constant, +the register will be replaced with the constant. If the predicate does +not permit a constant and the insn is re-recognized for some reason, the +compiler will crash. Thus the predicate must always recognize any +objects allowed by the constraint. +@end itemize + +If the operand's predicate can recognize registers, but the constraint does +not permit them, it can make the compiler crash. When this operand happens +to be a register, the reload pass will be stymied, because it does not know +how to copy a register temporarily into memory. +@end ifset + +@node Multi-Alternative +@subsection Multiple Alternative Constraints +@cindex multiple alternative constraints + +Sometimes a single instruction has multiple alternative sets of possible +operands. For example, on the 68000, a logical-or instruction can combine +register or an immediate value into memory, or it can combine any kind of +operand into a register; but it cannot combine one memory location into +another. + +These constraints are represented as multiple alternatives. An alternative +can be described by a series of letters for each operand. The overall +constraint for an operand is made from the letters for this operand +from the first alternative, a comma, the letters for this operand from +the second alternative, a comma, and so on until the last alternative. +@ifset INTERNALS +Here is how it is done for fullword logical-or on the 68000: + +@smallexample +(define_insn "iorsi3" + [(set (match_operand:SI 0 "general_operand" "=m,d") + (ior:SI (match_operand:SI 1 "general_operand" "%0,0") + (match_operand:SI 2 "general_operand" "dKs,dmKs")))] + @dots{}) +@end smallexample + +The first alternative has @samp{m} (memory) for operand 0, @samp{0} for +operand 1 (meaning it must match operand 0), and @samp{dKs} for operand +2. The second alternative has @samp{d} (data register) for operand 0, +@samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and +@samp{%} in the constraints apply to all the alternatives; their +meaning is explained in the next section (@pxref{Class Preferences}). +@end ifset + +@c FIXME Is this ? and ! stuff of use in asm()? If not, hide unless INTERNAL +If all the operands fit any one alternative, the instruction is valid. +Otherwise, for each alternative, the compiler counts how many instructions +must be added to copy the operands so that that alternative applies. +The alternative requiring the least copying is chosen. If two alternatives +need the same amount of copying, the one that comes first is chosen. +These choices can be altered with the @samp{?} and @samp{!} characters: + +@table @code +@cindex @samp{?} in constraint +@cindex question mark +@item ? +Disparage slightly the alternative that the @samp{?} appears in, +as a choice when no alternative applies exactly. The compiler regards +this alternative as one unit more costly for each @samp{?} that appears +in it. + +@cindex @samp{!} in constraint +@cindex exclamation point +@item ! +Disparage severely the alternative that the @samp{!} appears in. +This alternative can still be used if it fits without reloading, +but if reloading is needed, some other alternative will be used. +@end table + +@ifset INTERNALS +When an insn pattern has multiple alternatives in its constraints, often +the appearance of the assembler code is determined mostly by which +alternative was matched. When this is so, the C code for writing the +assembler code can use the variable @code{which_alternative}, which is +the ordinal number of the alternative that was actually satisfied (0 for +the first, 1 for the second alternative, etc.). @xref{Output Statement}. +@end ifset + +@ifset INTERNALS +@node Class Preferences +@subsection Register Class Preferences +@cindex class preference constraints +@cindex register class preference constraints + +@cindex voting between constraint alternatives +The operand constraints have another function: they enable the compiler +to decide which kind of hardware register a pseudo register is best +allocated to. The compiler examines the constraints that apply to the +insns that use the pseudo register, looking for the machine-dependent +letters such as @samp{d} and @samp{a} that specify classes of registers. +The pseudo register is put in whichever class gets the most ``votes''. +The constraint letters @samp{g} and @samp{r} also vote: they vote in +favor of a general register. The machine description says which registers +are considered general. + +Of course, on some machines all registers are equivalent, and no register +classes are defined. Then none of this complexity is relevant. +@end ifset + +@node Modifiers +@subsection Constraint Modifier Characters +@cindex modifiers in constraints +@cindex constraint modifier characters + +@c prevent bad page break with this line +Here are constraint modifier characters. + +@table @samp +@cindex @samp{=} in constraint +@item = +Means that this operand is write-only for this instruction: the previous +value is discarded and replaced by output data. + +@cindex @samp{+} in constraint +@item + +Means that this operand is both read and written by the instruction. + +When the compiler fixes up the operands to satisfy the constraints, +it needs to know which operands are inputs to the instruction and +which are outputs from it. @samp{=} identifies an output; @samp{+} +identifies an operand that is both input and output; all other operands +are assumed to be input only. + +@cindex @samp{&} in constraint +@item & +Means (in a particular alternative) that this operand is written +before the instruction is finished using the input operands. +Therefore, this operand may not lie in a register that is used as an +input operand or as part of any memory address. + +@samp{&} applies only to the alternative in which it is written. In +constraints with multiple alternatives, sometimes one alternative +requires @samp{&} while others do not. See, for example, the +@samp{movdf} insn of the 68000. + +@samp{&} does not obviate the need to write @samp{=}. + +@cindex @samp{%} in constraint +@item % +Declares the instruction to be commutative for this operand and the +following operand. This means that the compiler may interchange the +two operands if that is the cheapest way to make all operands fit the +constraints. +@ifset INTERNALS +This is often used in patterns for addition instructions +that really have only two operands: the result must go in one of the +arguments. Here for example, is how the 68000 halfword-add +instruction is defined: + +@smallexample +(define_insn "addhi3" + [(set (match_operand:HI 0 "general_operand" "=m,r") + (plus:HI (match_operand:HI 1 "general_operand" "%0,0") + (match_operand:HI 2 "general_operand" "di,g")))] + @dots{}) +@end smallexample +@end ifset + +@cindex @samp{#} in constraint +@item # +Says that all following characters, up to the next comma, are to be +ignored as a constraint. They are significant only for choosing +register preferences. + +@ifset INTERNALS +@cindex @samp{*} in constraint +@item * +Says that the following character should be ignored when choosing +register preferences. @samp{*} has no effect on the meaning of the +constraint as a constraint, and no effect on reloading. + +Here is an example: the 68000 has an instruction to sign-extend a +halfword in a data register, and can also sign-extend a value by +copying it into an address register. While either kind of register is +acceptable, the constraints on an address-register destination are +less strict, so it is best if register allocation makes an address +register its goal. Therefore, @samp{*} is used so that the @samp{d} +constraint letter (for data register) is ignored when computing +register preferences. + +@smallexample +(define_insn "extendhisi2" + [(set (match_operand:SI 0 "general_operand" "=*d,a") + (sign_extend:SI + (match_operand:HI 1 "general_operand" "0,g")))] + @dots{}) +@end smallexample +@end ifset +@end table + +@node Machine Constraints +@subsection Constraints for Particular Machines +@cindex machine specific constraints +@cindex constraints, machine specific + +Whenever possible, you should use the general-purpose constraint letters +in @code{asm} arguments, since they will convey meaning more readily to +people reading your code. Failing that, use the constraint letters +that usually have very similar meanings across architectures. The most +commonly used constraints are @samp{m} and @samp{r} (for memory and +general-purpose registers respectively; @pxref{Simple Constraints}), and +@samp{I}, usually the letter indicating the most common +immediate-constant format. + +For each machine architecture, the @file{config/@var{machine}.h} file +defines additional constraints. These constraints are used by the +compiler itself for instruction generation, as well as for @code{asm} +statements; therefore, some of the constraints are not particularly +interesting for @code{asm}. The constraints are defined through these +macros: + +@table @code +@item REG_CLASS_FROM_LETTER +Register class constraints (usually lower case). + +@item CONST_OK_FOR_LETTER_P +Immediate constant constraints, for non-floating point constants of +word size or smaller precision (usually upper case). + +@item CONST_DOUBLE_OK_FOR_LETTER_P +Immediate constant constraints, for all floating point constants and for +constants of greater than word size precision (usually upper case). + +@item EXTRA_CONSTRAINT +Special cases of registers or memory. This macro is not required, and +is only defined for some machines. +@end table + +Inspecting these macro definitions in the compiler source for your +machine is the best way to be certain you have the right constraints. +However, here is a summary of the machine-dependent constraints +available on some particular machines. + +@table @emph +@item ARM family---@file{arm.h} +@table @code +@item f +Floating-point register + +@item F +One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0 +or 10.0 + +@item G +Floating-point constant that would satisfy the constraint @samp{F} if it +were negated + +@item I +Integer that is valid as an immediate operand in a data processing +instruction. That is, an integer in the range 0 to 255 rotated by a +multiple of 2 + +@item J +Integer in the range -4095 to 4095 + +@item K +Integer that satisfies constraint @samp{I} when inverted (ones complement) + +@item L +Integer that satisfies constraint @samp{I} when negated (twos complement) + +@item M +Integer in the range 0 to 32 + +@item Q +A memory reference where the exact address is in a single register +(`@samp{m}' is preferable for @code{asm} statements) + +@item R +An item in the constant pool + +@item S +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 IBM RS6000---@file{rs6000.h} +@table @code +@item b +Address base register + +@item f +Floating point register + +@item h +@samp{MQ}, @samp{CTR}, or @samp{LINK} register + +@item q +@samp{MQ} register + +@item c +@samp{CTR} register + +@item l +@samp{LINK} register + +@item x +@samp{CR} register (condition register) number 0 + +@item y +@samp{CR} register (condition register) + +@item I +Signed 16 bit constant + +@item J +Constant whose low 16 bits are 0 + +@item K +Constant whose high 16 bits are 0 + +@item L +Constant suitable as a mask operand + +@item M +Constant larger than 31 + +@item N +Exact power of 2 + +@item O +Zero + +@item P +Constant whose negation is a signed 16 bit constant + +@item G +Floating point constant that can be loaded into a register with one +instruction per word + +@item Q +Memory operand that is an offset from a register (@samp{m} is preferable +for @code{asm} statements) +@end table + +@item Intel 386---@file{i386.h} +@table @code +@item q +@samp{a}, @code{b}, @code{c}, or @code{d} register + +@item A +@samp{a}, or @code{d} register (for 64-bit ints) + +@item f +Floating point register + +@item t +First (top of stack) floating point register + +@item u +Second floating point register + +@item a +@samp{a} register + +@item b +@samp{b} register + +@item c +@samp{c} register + +@item d +@samp{d} register + +@item D +@samp{di} register + +@item S +@samp{si} register + +@item I +Constant in range 0 to 31 (for 32 bit shifts) + +@item J +Constant in range 0 to 63 (for 64 bit shifts) + +@item K +@samp{0xff} + +@item L +@samp{0xffff} + +@item M +0, 1, 2, or 3 (shifts for @code{lea} instruction) + +@item G +Standard 80387 floating point constant +@end table + +@item Intel 960---@file{i960.h} +@table @code +@item f +Floating point register (@code{fp0} to @code{fp3}) + +@item l +Local register (@code{r0} to @code{r15}) + +@item b +Global register (@code{g0} to @code{g15}) + +@item d +Any local or global register + +@item I +Integers from 0 to 31 + +@item J +0 + +@item K +Integers from -31 to 0 + +@item G +Floating point 0 + +@item H +Floating point 1 +@end table + +@item MIPS---@file{mips.h} +@table @code +@item d +General-purpose integer register + +@item f +Floating-point register (if available) + +@item h +@samp{Hi} register + +@item l +@samp{Lo} register + +@item x +@samp{Hi} or @samp{Lo} register + +@item y +General-purpose integer register + +@item z +Floating-point status register + +@item I +Signed 16 bit constant (for arithmetic instructions) + +@item J +Zero + +@item K +Zero-extended 16-bit constant (for logic instructions) + +@item L +Constant with low 16 bits zero (can be loaded with @code{lui}) + +@item M +32 bit constant which requires two instructions to load (a constant +which is not @samp{I}, @samp{K}, or @samp{L}) + +@item N +Negative 16 bit constant + +@item O +Exact power of two + +@item P +Positive 16 bit constant + +@item G +Floating point zero + +@item Q +Memory reference that can be loaded with more than one instruction +(@samp{m} is preferable for @code{asm} statements) + +@item R +Memory reference that can be loaded with one instruction +(@samp{m} is preferable for @code{asm} statements) + +@item S +Memory reference in external OSF/rose PIC format +(@samp{m} is preferable for @code{asm} statements) +@end table + +@item Motorola 680x0---@file{m68k.h} +@table @code +@item a +Address register + +@item d +Data register + +@item f +68881 floating-point register, if available + +@item x +Sun FPA (floating-point) register, if available + +@item y +First 16 Sun FPA registers, if available + +@item I +Integer in the range 1 to 8 + +@item J +16 bit signed number + +@item K +Signed number whose magnitude is greater than 0x80 + +@item L +Integer in the range -8 to -1 + +@item G +Floating point constant that is not a 68881 constant + +@item H +Floating point constant that can be used by Sun FPA +@end table + +@need 1000 +@item SPARC---@file{sparc.h} +@table @code +@item f +Floating-point register + +@item I +Signed 13 bit constant + +@item J +Zero + +@item K +32 bit constant with the low 12 bits clear (a constant that can be +loaded with the @code{sethi} instruction) + +@item G +Floating-point zero + +@item H +Signed 13 bit constant, sign-extended to 32 or 64 bits + +@item Q +Memory reference that can be loaded with one instruction (@samp{m} is +more appropriate for @code{asm} statements) + +@item S +Constant, or memory address + +@item T +Memory address aligned to an 8-byte boundary + +@item U +Even register +@end table +@end table + +@ifset INTERNALS +@node No Constraints +@subsection Not Using Constraints +@cindex no constraints +@cindex not using constraints + +Some machines are so clean that operand constraints are not required. For +example, on the Vax, an operand valid in one context is valid in any other +context. On such a machine, every operand constraint would be @samp{g}, +excepting only operands of ``load address'' instructions which are +written as if they referred to a memory location's contents but actual +refer to its address. They would have constraint @samp{p}. + +@cindex empty constraints +For such machines, instead of writing @samp{g} and @samp{p} for all +the constraints, you can choose to write a description with empty constraints. +Then you write @samp{""} for the constraint in every @code{match_operand}. +Address operands are identified by writing an @code{address} expression +around the @code{match_operand}, not by their constraints. + +When the machine description has just empty constraints, certain parts +of compilation are skipped, making the compiler faster. However, +few machines actually do not need constraints; all machine descriptions +now in existence use constraints. +@end ifset + +@ifset INTERNALS +@node Standard Names +@section Standard Pattern Names For Generation +@cindex standard pattern names +@cindex pattern names +@cindex names, pattern + +Here is a table of the instruction names that are meaningful in the RTL +generation pass of the compiler. Giving one of these names to an +instruction pattern tells the RTL generation pass that it can use the +pattern in to accomplish a certain task. + +@table @asis +@cindex @code{mov@var{m}} instruction pattern +@item @samp{mov@var{m}} +Here @var{m} stands for a two-letter machine mode name, in lower case. +This instruction pattern moves data with that machine mode from operand +1 to operand 0. For example, @samp{movsi} moves full-word data. + +If operand 0 is a @code{subreg} with mode @var{m} of a register whose +own mode is wider than @var{m}, the effect of this instruction is +to store the specified value in the part of the register that corresponds +to mode @var{m}. The effect on the rest of the register is undefined. + +This class of patterns is special in several ways. First of all, each +of these names @emph{must} be defined, because there is no other way +to copy a datum from one place to another. + +Second, these patterns are not used solely in the RTL generation pass. +Even the reload pass can generate move insns to copy values from stack +slots into temporary registers. When it does so, one of the operands is +a hard register and the other is an operand that can need to be reloaded +into a register. + +@findex force_reg +Therefore, when given such a pair of operands, the pattern must generate +RTL which needs no reloading and needs no temporary registers---no +registers other than the operands. For example, if you support the +pattern with a @code{define_expand}, then in such a case the +@code{define_expand} mustn't call @code{force_reg} or any other such +function which might generate new pseudo registers. + +This requirement exists even for subword modes on a RISC machine where +fetching those modes from memory normally requires several insns and +some temporary registers. Look in @file{spur.md} to see how the +requirement can be satisfied. + +@findex change_address +During reload a memory reference with an invalid address may be passed +as an operand. Such an address will be replaced with a valid address +later in the reload pass. In this case, nothing may be done with the +address except to use it as it stands. If it is copied, it will not be +replaced with a valid address. No attempt should be made to make such +an address into a valid address and no routine (such as +@code{change_address}) that will do so may be called. Note that +@code{general_operand} will fail when applied to such an address. + +@findex reload_in_progress +The global variable @code{reload_in_progress} (which must be explicitly +declared if required) can be used to determine whether such special +handling is required. + +The variety of operands that have reloads depends on the rest of the +machine description, but typically on a RISC machine these can only be +pseudo registers that did not get hard registers, while on other +machines explicit memory references will get optional reloads. + +If a scratch register is required to move an object to or from memory, +it can be allocated using @code{gen_reg_rtx} prior to reload. But this +is impossible during and after reload. If there are cases needing +scratch registers after reload, you must define +@code{SECONDARY_INPUT_RELOAD_CLASS} and perhaps also +@code{SECONDARY_OUTPUT_RELOAD_CLASS} to detect them, and provide +patterns @samp{reload_in@var{m}} or @samp{reload_out@var{m}} to handle +them. @xref{Register Classes}. + +The constraints on a @samp{move@var{m}} must permit moving any hard +register to any other hard register provided that +@code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and +@code{REGISTER_MOVE_COST} applied to their classes returns a value of 2. + +It is obligatory to support floating point @samp{move@var{m}} +instructions into and out of any registers that can hold fixed point +values, because unions and structures (which have modes @code{SImode} or +@code{DImode}) can be in those registers and they may have floating +point members. + +There may also be a need to support fixed point @samp{move@var{m}} +instructions in and out of floating point registers. Unfortunately, I +have forgotten why this was so, and I don't know whether it is still +true. If @code{HARD_REGNO_MODE_OK} rejects fixed point values in +floating point registers, then the constraints of the fixed point +@samp{move@var{m}} instructions must be designed to avoid ever trying to +reload into a floating point register. + +@cindex @code{reload_in} instruction pattern +@cindex @code{reload_out} instruction pattern +@item @samp{reload_in@var{m}} +@itemx @samp{reload_out@var{m}} +Like @samp{mov@var{m}}, but used when a scratch register is required to +move between operand 0 and operand 1. Operand 2 describes the scratch +register. See the discussion of the @code{SECONDARY_RELOAD_CLASS} +macro in @pxref{Register Classes}. + +@cindex @code{movstrict@var{m}} instruction pattern +@item @samp{movstrict@var{m}} +Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg} +with mode @var{m} of a register whose natural mode is wider, +the @samp{movstrict@var{m}} instruction is guaranteed not to alter +any of the register except the part which belongs to mode @var{m}. + +@cindex @code{load_multiple} instruction pattern +@item @samp{load_multiple} +Load several consecutive memory locations into consecutive registers. +Operand 0 is the first of the consecutive registers, operand 1 +is the first memory location, and operand 2 is a constant: the +number of consecutive registers. + +Define this only if the target machine really has such an instruction; +do not define this if the most efficient way of loading consecutive +registers from memory is to do them one at a time. + +On some machines, there are restrictions as to which consecutive +registers can be stored into memory, such as particular starting or +ending register numbers or only a range of valid counts. For those +machines, use a @code{define_expand} (@pxref{Expander Definitions}) +and make the pattern fail if the restrictions are not met. + +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. + +@cindex @samp{store_multiple} instruction pattern +@item @samp{store_multiple} +Similar to @samp{load_multiple}, but store several consecutive registers +into consecutive memory locations. Operand 0 is the first of the +consecutive memory locations, operand 1 is the first register, and +operand 2 is a constant: the number of consecutive registers. + +@cindex @code{add@var{m}3} instruction pattern +@item @samp{add@var{m}3} +Add operand 2 and operand 1, storing the result in operand 0. All operands +must have mode @var{m}. This can be used even on two-address machines, by +means of constraints requiring operands 1 and 0 to be the same location. + +@cindex @code{sub@var{m}3} instruction pattern +@cindex @code{mul@var{m}3} instruction pattern +@cindex @code{div@var{m}3} instruction pattern +@cindex @code{udiv@var{m}3} instruction pattern +@cindex @code{mod@var{m}3} instruction pattern +@cindex @code{umod@var{m}3} instruction pattern +@cindex @code{min@var{m}3} instruction pattern +@cindex @code{max@var{m}3} instruction pattern +@cindex @code{umin@var{m}3} instruction pattern +@cindex @code{umax@var{m}3} instruction pattern +@cindex @code{and@var{m}3} instruction pattern +@cindex @code{ior@var{m}3} instruction pattern +@cindex @code{xor@var{m}3} instruction pattern +@item @samp{sub@var{m}3}, @samp{mul@var{m}3} +@itemx @samp{div@var{m}3}, @samp{udiv@var{m}3}, @samp{mod@var{m}3}, @samp{umod@var{m}3} +@itemx @samp{smin@var{m}3}, @samp{smax@var{m}3}, @samp{umin@var{m}3}, @samp{umax@var{m}3} +@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} +Similar, for other arithmetic operations. + +@cindex @code{mulhisi3} instruction pattern +@item @samp{mulhisi3} +Multiply operands 1 and 2, which have mode @code{HImode}, and store +a @code{SImode} product in operand 0. + +@cindex @code{mulqihi3} instruction pattern +@cindex @code{mulsidi3} instruction pattern +@item @samp{mulqihi3}, @samp{mulsidi3} +Similar widening-multiplication instructions of other widths. + +@cindex @code{umulqihi3} instruction pattern +@cindex @code{umulhisi3} instruction pattern +@cindex @code{umulsidi3} instruction pattern +@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3} +Similar widening-multiplication instructions that do unsigned +multiplication. + +@cindex @code{divmod@var{m}4} instruction pattern +@item @samp{divmod@var{m}4} +Signed division that produces both a quotient and a remainder. +Operand 1 is divided by operand 2 to produce a quotient stored +in operand 0 and a remainder stored in operand 3. + +For machines with an instruction that produces both a quotient and a +remainder, provide a pattern for @samp{divmod@var{m}4} but do not +provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This +allows optimization in the relatively common case when both the quotient +and remainder are computed. + +If an instruction that just produces a quotient or just a remainder +exists and is more efficient than the instruction that produces both, +write the output routine of @samp{divmod@var{m}4} to call +@code{find_reg_note} and look for a @code{REG_UNUSED} note on the +quotient or remainder and generate the appropriate instruction. + +@cindex @code{udivmod@var{m}4} instruction pattern +@item @samp{udivmod@var{m}4} +Similar, but does unsigned division. + +@cindex @code{ashl@var{m}3} instruction pattern +@item @samp{ashl@var{m}3} +Arithmetic-shift operand 1 left by a number of bits specified by operand +2, and store the result in operand 0. Here @var{m} is the mode of +operand 0 and operand 1; operand 2's mode is specified by the +instruction pattern, and the compiler will convert the operand to that +mode before generating the instruction. + +@cindex @code{ashr@var{m}3} instruction pattern +@cindex @code{lshr@var{m}3} instruction pattern +@cindex @code{rotl@var{m}3} instruction pattern +@cindex @code{rotr@var{m}3} instruction pattern +@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3} +Other shift and rotate instructions, analogous to the +@code{ashl@var{m}3} instructions. + +@cindex @code{neg@var{m}2} instruction pattern +@item @samp{neg@var{m}2} +Negate operand 1 and store the result in operand 0. + +@cindex @code{abs@var{m}2} instruction pattern +@item @samp{abs@var{m}2} +Store the absolute value of operand 1 into operand 0. + +@cindex @code{sqrt@var{m}2} instruction pattern +@item @samp{sqrt@var{m}2} +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}. + +@cindex @code{ffs@var{m}2} instruction pattern +@item @samp{ffs@var{m}2} +Store into operand 0 one plus the index of the least significant 1-bit +of operand 1. If operand 1 is zero, store zero. @var{m} is the mode +of operand 0; operand 1's mode is specified by the instruction +pattern, and the compiler will convert the operand to that mode before +generating the instruction. + +The @code{ffs} built-in function of C always uses the mode which +corresponds to the C data type @code{int}. + +@cindex @code{one_cmpl@var{m}2} instruction pattern +@item @samp{one_cmpl@var{m}2} +Store the bitwise-complement of operand 1 into operand 0. + +@cindex @code{cmp@var{m}} instruction pattern +@item @samp{cmp@var{m}} +Compare operand 0 and operand 1, and set the condition codes. +The RTL pattern should look like this: + +@smallexample +(set (cc0) (compare (match_operand:@var{m} 0 @dots{}) + (match_operand:@var{m} 1 @dots{}))) +@end smallexample + +@cindex @code{tst@var{m}} instruction pattern +@item @samp{tst@var{m}} +Compare operand 0 against zero, and set the condition codes. +The RTL pattern should look like this: + +@smallexample +(set (cc0) (match_operand:@var{m} 0 @dots{})) +@end smallexample + +@samp{tst@var{m}} patterns should not be defined for machines that do +not use @code{(cc0)}. Doing so would confuse the optimizer since it +would no longer be clear which @code{set} operations were comparisons. +The @samp{cmp@var{m}} patterns should be used instead. + +@cindex @code{movstr@var{m}} instruction pattern +@item @samp{movstr@var{m}} +Block move instruction. The addresses of the destination and source +strings are the first two operands, and both are in mode @code{Pmode}. +The number of bytes to move is the third operand, in mode @var{m}. + +The fourth operand is the known shared alignment of the source and +destination, in the form of a @code{const_int} rtx. Thus, if the +compiler knows that both source and destination are word-aligned, +it may provide the value 4 for this operand. + +These patterns need not give special consideration to the possibility +that the source and destination strings might overlap. + +@cindex @code{cmpstr@var{m}} instruction pattern +@item @samp{cmpstr@var{m}} +Block compare instruction, with five operands. Operand 0 is the output; +it has mode @var{m}. The remaining four operands are like the operands +of @samp{movstr@var{m}}. The two memory blocks specified are compared +byte by byte in lexicographic order. The effect of the instruction is +to store a value in operand 0 whose sign indicates the result of the +comparison. + +@cindex @code{strlen@var{m}} instruction pattern +Compute the length of a string, with three operands. +Operand 0 is the result (of mode @var{m}), operand 1 is +a @code{mem} referring to the first character of the string, +operand 2 is the character to search for (normally zero), +and operand 3 is a constant describing the known alignment +of the beginning of the string. + +@cindex @code{float@var{mn}2} instruction pattern +@item @samp{float@var{m}@var{n}2} +Convert signed integer operand 1 (valid for fixed point mode @var{m}) to +floating point mode @var{n} and store in operand 0 (which has mode +@var{n}). + +@cindex @code{floatuns@var{mn}2} instruction pattern +@item @samp{floatuns@var{m}@var{n}2} +Convert unsigned integer operand 1 (valid for fixed point mode @var{m}) +to floating point mode @var{n} and store in operand 0 (which has mode +@var{n}). + +@cindex @code{fix@var{mn}2} instruction pattern +@item @samp{fix@var{m}@var{n}2} +Convert operand 1 (valid for floating point mode @var{m}) to fixed +point mode @var{n} as a signed number and store in operand 0 (which +has mode @var{n}). This instruction's result is defined only when +the value of operand 1 is an integer. + +@cindex @code{fixuns@var{mn}2} instruction pattern +@item @samp{fixuns@var{m}@var{n}2} +Convert operand 1 (valid for floating point mode @var{m}) to fixed +point mode @var{n} as an unsigned number and store in operand 0 (which +has mode @var{n}). This instruction's result is defined only when the +value of operand 1 is an integer. + +@cindex @code{ftrunc@var{m}2} instruction pattern +@item @samp{ftrunc@var{m}2} +Convert operand 1 (valid for floating point mode @var{m}) to an +integer value, still represented in floating point mode @var{m}, and +store it in operand 0 (valid for floating point mode @var{m}). + +@cindex @code{fix_trunc@var{mn}2} instruction pattern +@item @samp{fix_trunc@var{m}@var{n}2} +Like @samp{fix@var{m}@var{n}2} but works for any floating point value +of mode @var{m} by converting the value to an integer. + +@cindex @code{fixuns_trunc@var{mn}2} instruction pattern +@item @samp{fixuns_trunc@var{m}@var{n}2} +Like @samp{fixuns@var{m}@var{n}2} but works for any floating point +value of mode @var{m} by converting the value to an integer. + +@cindex @code{trunc@var{mn}} instruction pattern +@item @samp{trunc@var{m}@var{n}} +Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and +store in operand 0 (which has mode @var{n}). Both modes must be fixed +point or both floating point. + +@cindex @code{extend@var{mn}} instruction pattern +@item @samp{extend@var{m}@var{n}} +Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and +store in operand 0 (which has mode @var{n}). Both modes must be fixed +point or both floating point. + +@cindex @code{zero_extend@var{mn}} instruction pattern +@item @samp{zero_extend@var{m}@var{n}} +Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and +store in operand 0 (which has mode @var{n}). Both modes must be fixed +point. + +@cindex @code{extv} instruction pattern +@item @samp{extv} +Extract a bit field from operand 1 (a register or memory operand), where +operand 2 specifies the width in bits and operand 3 the starting bit, +and store it in operand 0. Operand 0 must have mode @code{word_mode}. +Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often +@code{word_mode} is allowed only for registers. Operands 2 and 3 must +be valid for @code{word_mode}. + +The RTL generation pass generates this instruction only with constants +for operands 2 and 3. + +The bit-field value is sign-extended to a full word integer +before it is stored in operand 0. + +@cindex @code{extzv} instruction pattern +@item @samp{extzv} +Like @samp{extv} except that the bit-field value is zero-extended. + +@cindex @code{insv} instruction pattern +@item @samp{insv} +Store operand 3 (which must be valid for @code{word_mode}) into a bit +field in operand 0, where operand 1 specifies the width in bits and +operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or +@code{word_mode}; often @code{word_mode} is allowed only for registers. +Operands 1 and 2 must be valid for @code{word_mode}. + +The RTL generation pass generates this instruction only with constants +for operands 1 and 2. + +@cindex @code{s@var{cond}} instruction pattern +@item @samp{s@var{cond}} +Store zero or nonzero in the operand according to the condition codes. +Value stored is nonzero iff the condition @var{cond} is true. +@var{cond} is the name of a comparison operation expression code, such +as @code{eq}, @code{lt} or @code{leu}. + +You specify the mode that the operand must have when you write the +@code{match_operand} expression. The compiler automatically sees +which mode you have used and supplies an operand of that mode. + +The value stored for a true condition must have 1 as its low bit, or +else must be negative. Otherwise the instruction is not suitable and +you should omit it from the machine description. You describe to the +compiler exactly which value is stored by defining the macro +@code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be +found that can be used for all the @samp{s@var{cond}} patterns, you +should omit those operations from the machine description. + +These operations may fail, but should do so only in relatively +uncommon cases; if they would fail for common cases involving +integer comparisons, it is best to omit these patterns. + +If these operations are omitted, the compiler will usually generate code +that copies the constant one to the target and branches around an +assignment of zero to the target. If this code is more efficient than +the potential instructions used for the @samp{s@var{cond}} pattern +followed by those required to convert the result into a 1 or a zero in +@code{SImode}, you should omit the @samp{s@var{cond}} operations from +the machine description. + +@cindex @code{b@var{cond}} instruction pattern +@item @samp{b@var{cond}} +Conditional branch instruction. Operand 0 is a @code{label_ref} that +refers to the label to jump to. Jump if the condition codes meet +condition @var{cond}. + +Some machines do not follow the model assumed here where a comparison +instruction is followed by a conditional branch instruction. In that +case, the @samp{cmp@var{m}} (and @samp{tst@var{m}}) patterns should +simply store the operands away and generate all the required insns in a +@code{define_expand} (@pxref{Expander Definitions}) for the conditional +branch operations. All calls to expand @samp{b@var{cond}} patterns are +immediately preceded by calls to expand either a @samp{cmp@var{m}} +pattern or a @samp{tst@var{m}} pattern. + +Machines that use a pseudo register for the condition code value, or +where the mode used for the comparison depends on the condition being +tested, should also use the above mechanism. @xref{Jump Patterns} + +The above discussion also applies to @samp{s@var{cond}} patterns. + +@cindex @code{call} instruction pattern +@item @samp{call} +Subroutine call instruction returning no value. Operand 0 is the +function to call; operand 1 is the number of bytes of arguments pushed +(in mode @code{SImode}, except it is normally a @code{const_int}); +operand 2 is the number of registers used as operands. + +On most machines, operand 2 is not actually stored into the RTL +pattern. It is supplied for the sake of some RISC machines which need +to put this information into the assembler code; they can put it in +the RTL instead of operand 1. + +Operand 0 should be a @code{mem} RTX whose address is the address of the +function. Note, however, that this address can be a @code{symbol_ref} +expression even if it would not be a legitimate memory address on the +target machine. If it is also not a valid argument for a call +instruction, the pattern for this operation should be a +@code{define_expand} (@pxref{Expander Definitions}) that places the +address into a register and uses that register in the call instruction. + +@cindex @code{call_value} instruction pattern +@item @samp{call_value} +Subroutine call instruction returning a value. Operand 0 is the hard +register in which the value is returned. There are three more +operands, the same as the three operands of the @samp{call} +instruction (but with numbers increased by one). + +Subroutines that return @code{BLKmode} objects use the @samp{call} +insn. + +@cindex @code{call_pop} instruction pattern +@cindex @code{call_value_pop} instruction pattern +@item @samp{call_pop}, @samp{call_value_pop} +Similar to @samp{call} and @samp{call_value}, except used if defined and +if @code{RETURN_POPS_ARGS} is non-zero. They should emit a @code{parallel} +that contains both the function call and a @code{set} to indicate the +adjustment made to the frame pointer. + +For machines where @code{RETURN_POPS_ARGS} can be non-zero, the use of these +patterns increases the number of functions for which the frame pointer +can be eliminated, if desired. + +@cindex @code{untyped_call} instruction pattern +@item @samp{untyped_call} +Subroutine call instruction returning a value of any type. Operand 0 is +the function to call; operand 1 is a memory location where the result of +calling the function is to be stored; operand 2 is a @code{parallel} +expression where each element is a @code{set} expression that indicates +the saving of a function return value into the result block. + +This instruction pattern should be defined to support +@code{__builtin_apply} on machines where special instructions are needed +to call a subroutine with arbitrary arguments or to save the value +returned. This instruction pattern is required on machines that have +multiple registers that can hold a return value (i.e. +@code{FUNCTION_VALUE_REGNO_P} is true for more than one register). + +@cindex @code{return} instruction pattern +@item @samp{return} +Subroutine return instruction. This instruction pattern name should be +defined only if a single instruction can do all the work of returning +from a function. + +Like the @samp{mov@var{m}} patterns, this pattern is also used after the +RTL generation phase. In this case it is to support machines where +multiple instructions are usually needed to return from a function, but +some class of functions only requires one instruction to implement a +return. Normally, the applicable functions are those which do not need +to save any registers or allocate stack space. + +@findex reload_completed +@findex leaf_function_p +For such machines, the condition specified in this pattern should only +be true when @code{reload_completed} is non-zero and the function's +epilogue would only be a single instruction. For machines with register +windows, the routine @code{leaf_function_p} may be used to determine if +a register window push is required. + +Machines that have conditional return instructions should define patterns +such as + +@smallexample +(define_insn "" + [(set (pc) + (if_then_else (match_operator + 0 "comparison_operator" + [(cc0) (const_int 0)]) + (return) + (pc)))] + "@var{condition}" + "@dots{}") +@end smallexample + +where @var{condition} would normally be the same condition specified on the +named @samp{return} pattern. + +@cindex @code{untyped_return} instruction pattern +@item @samp{untyped_return} +Untyped subroutine return instruction. This instruction pattern should +be defined to support @code{__builtin_return} on machines where special +instructions are needed to return a value of any type. + +Operand 0 is a memory location where the result of calling a function +with @code{__builtin_apply} is stored; operand 1 is a @code{parallel} +expression where each element is a @code{set} expression that indicates +the restoring of a function return value from the result block. + +@cindex @code{nop} instruction pattern +@item @samp{nop} +No-op instruction. This instruction pattern name should always be defined +to output a no-op in assembler code. @code{(const_int 0)} will do as an +RTL pattern. + +@cindex @code{indirect_jump} instruction pattern +@item @samp{indirect_jump} +An instruction to jump to an address which is operand zero. +This pattern name is mandatory on all machines. + +@cindex @code{casesi} instruction pattern +@item @samp{casesi} +Instruction to jump through a dispatch table, including bounds checking. +This instruction takes five operands: + +@enumerate +@item +The index to dispatch on, which has mode @code{SImode}. + +@item +The lower bound for indices in the table, an integer constant. + +@item +The total range of indices in the table---the largest index +minus the smallest one (both inclusive). + +@item +A label that precedes the table itself. + +@item +A label to jump to if the index has a value outside the bounds. +(If the machine-description macro @code{CASE_DROPS_THROUGH} is defined, +then an out-of-bounds index drops through to the code following +the jump table instead of jumping to this label. In that case, +this label is not actually used by the @samp{casesi} instruction, +but it is always provided as an operand.) +@end enumerate + +The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a +@code{jump_insn}. The number of elements in the table is one plus the +difference between the upper bound and the lower bound. + +@cindex @code{tablejump} instruction pattern +@item @samp{tablejump} +Instruction to jump to a variable address. This is a low-level +capability which can be used to implement a dispatch table when there +is no @samp{casesi} pattern. + +This pattern requires two operands: the address or offset, and a label +which should immediately precede the jump table. If the macro +@code{CASE_VECTOR_PC_RELATIVE} is defined then the first operand is an +offset which counts from the address of the table; otherwise, it is an +absolute address to jump to. In either case, the first operand has +mode @code{Pmode}. + +The @samp{tablejump} insn is always the last insn before the jump +table it uses. Its assembler code normally has no need to use the +second operand, but you should incorporate it in the RTL pattern so +that the jump optimizer will not delete the table as unreachable code. + +@cindex @code{save_stack_block} instruction pattern +@cindex @code{save_stack_function} instruction pattern +@cindex @code{save_stack_nonlocal} instruction pattern +@cindex @code{restore_stack_block} instruction pattern +@cindex @code{restore_stack_function} instruction pattern +@cindex @code{restore_stack_nonlocal} instruction pattern +@item @samp{save_stack_block} +@itemx @samp{save_stack_function} +@itemx @samp{save_stack_nonlocal} +@itemx @samp{restore_stack_block} +@itemx @samp{restore_stack_function} +@itemx @samp{restore_stack_nonlocal} +Most machines save and restore the stack pointer by copying it to or +from an object of mode @code{Pmode}. Do not define these patterns on +such machines. + +Some machines require special handling for stack pointer saves and +restores. On those machines, define the patterns corresponding to the +non-standard cases by using a @code{define_expand} (@pxref{Expander +Definitions}) that produces the required insns. The three types of +saves and restores are: + +@enumerate +@item +@samp{save_stack_block} saves the stack pointer at the start of a block +that allocates a variable-sized object, and @samp{restore_stack_block} +restores the stack pointer when the block is exited. + +@item +@samp{save_stack_function} and @samp{restore_stack_function} do a +similar job for the outermost block of a function and are used when the +function allocates variable-sized objects or calls @code{alloca}. Only +the epilogue uses the restored stack pointer, allowing a simpler save or +restore sequence on some machines. + +@item +@samp{save_stack_nonlocal} is used in functions that contain labels +branched to by nested functions. It saves the stack pointer in such a +way that the inner function can use @samp{restore_stack_nonlocal} to +restore the stack pointer. The compiler generates code to restore the +frame and argument pointer registers, but some machines require saving +and restoring additional data such as register window information or +stack backchains. Place insns in these patterns to save and restore any +such required data. +@end enumerate + +When saving the stack pointer, operand 0 is the save area and operand 1 +is the stack pointer. The mode used to allocate the save area is the +mode of operand 0. You must specify an integral mode, or +@code{VOIDmode} if no save area is needed for a particular type of save +(either because no save is needed or because a machine-specific save +area can be used). Operand 0 is the stack pointer and operand 1 is the +save area for restore operations. If @samp{save_stack_block} is +defined, operand 0 must not be @code{VOIDmode} since these saves can be +arbitrarily nested. + +A save area is a @code{mem} that is at a constant offset from +@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by +nonlocal gotos and a @code{reg} in the other two cases. + +@cindex @code{allocate_stack} instruction pattern +@item @samp{allocate_stack} +Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 0 from +the stack pointer to create space for dynamically allocated data. + +Do not define this pattern if all that must be done is the subtraction. +Some machines require other operations such as stack probes or +maintaining the back chain. Define this pattern to emit those +operations in addition to updating the stack pointer. +@end table + +@node Pattern Ordering +@section When the Order of Patterns Matters +@cindex Pattern Ordering +@cindex Ordering of Patterns + +Sometimes an insn can match more than one instruction pattern. Then the +pattern that appears first in the machine description is the one used. +Therefore, more specific patterns (patterns that will match fewer things) +and faster instructions (those that will produce better code when they +do match) should usually go first in the description. + +In some cases the effect of ordering the patterns can be used to hide +a pattern when it is not valid. For example, the 68000 has an +instruction for converting a fullword to floating point and another +for converting a byte to floating point. An instruction converting +an integer to floating point could match either one. We put the +pattern to convert the fullword first to make sure that one will +be used rather than the other. (Otherwise a large integer might +be generated as a single-byte immediate quantity, which would not work.) +Instead of using this pattern ordering it would be possible to make the +pattern for convert-a-byte smart enough to deal properly with any +constant value. + +@node Dependent Patterns +@section Interdependence of Patterns +@cindex Dependent Patterns +@cindex Interdependence of Patterns + +Every machine description must have a named pattern for each of the +conditional branch names @samp{b@var{cond}}. The recognition template +must always have the form + +@example +(set (pc) + (if_then_else (@var{cond} (cc0) (const_int 0)) + (label_ref (match_operand 0 "" "")) + (pc))) +@end example + +@noindent +In addition, every machine description must have an anonymous pattern +for each of the possible reverse-conditional branches. Their templates +look like + +@example +(set (pc) + (if_then_else (@var{cond} (cc0) (const_int 0)) + (pc) + (label_ref (match_operand 0 "" "")))) +@end example + +@noindent +They are necessary because jump optimization can turn direct-conditional +branches into reverse-conditional branches. + +It is often convenient to use the @code{match_operator} construct to +reduce the number of patterns that must be specified for branches. For +example, + +@example +(define_insn "" + [(set (pc) + (if_then_else (match_operator 0 "comparison_operator" + [(cc0) (const_int 0)]) + (pc) + (label_ref (match_operand 1 "" ""))))] + "@var{condition}" + "@dots{}") +@end example + +In some cases machines support instructions identical except for the +machine mode of one or more operands. For example, there may be +``sign-extend halfword'' and ``sign-extend byte'' instructions whose +patterns are + +@example +(set (match_operand:SI 0 @dots{}) + (extend:SI (match_operand:HI 1 @dots{}))) + +(set (match_operand:SI 0 @dots{}) + (extend:SI (match_operand:QI 1 @dots{}))) +@end example + +@noindent +Constant integers do not specify a machine mode, so an instruction to +extend a constant value could match either pattern. The pattern it +actually will match is the one that appears first in the file. For correct +results, this must be the one for the widest possible mode (@code{HImode}, +here). If the pattern matches the @code{QImode} instruction, the results +will be incorrect if the constant value does not actually fit that mode. + +Such instructions to extend constants are rarely generated because they are +optimized away, but they do occasionally happen in nonoptimized +compilations. + +If a constraint in a pattern allows a constant, the reload pass may +replace a register with a constant permitted by the constraint in some +cases. Similarly for memory references. You must ensure that the +predicate permits all objects allowed by the constraints to prevent the +compiler from crashing. + +Because of this substitution, you should not provide separate patterns +for increment and decrement instructions. Instead, they should be +generated from the same pattern that supports register-register add +insns by examining the operands and generating the appropriate machine +instruction. + +@node Jump Patterns +@section Defining Jump Instruction Patterns +@cindex jump instruction patterns +@cindex defining jump instruction patterns + +For most machines, GNU CC assumes that the machine has a condition code. +A comparison insn sets the condition code, recording the results of both +signed and unsigned comparison of the given operands. A separate branch +insn tests the condition code and branches or not according its value. +The branch insns come in distinct signed and unsigned flavors. Many +common machines, such as the Vax, the 68000 and the 32000, work this +way. + +Some machines have distinct signed and unsigned compare instructions, and +only one set of conditional branch instructions. The easiest way to handle +these machines is to treat them just like the others until the final stage +where assembly code is written. At this time, when outputting code for the +compare instruction, peek ahead at the following branch using +@code{next_cc0_user (insn)}. (The variable @code{insn} refers to the insn +being output, in the output-writing code in an instruction pattern.) If +the RTL says that is an unsigned branch, output an unsigned compare; +otherwise output a signed compare. When the branch itself is output, you +can treat signed and unsigned branches identically. + +The reason you can do this is that GNU CC always generates a pair of +consecutive RTL insns, possibly separated by @code{note} insns, one to +set the condition code and one to test it, and keeps the pair inviolate +until the end. + +To go with this technique, you must define the machine-description macro +@code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no +compare instruction is superfluous. + +Some machines have compare-and-branch instructions and no condition code. +A similar technique works for them. When it is time to ``output'' a +compare instruction, record its operands in two static variables. When +outputting the branch-on-condition-code instruction that follows, actually +output a compare-and-branch instruction that uses the remembered operands. + +It also works to define patterns for compare-and-branch instructions. +In optimizing compilation, the pair of compare and branch instructions +will be combined according to these patterns. But this does not happen +if optimization is not requested. So you must use one of the solutions +above in addition to any special patterns you define. + +In many RISC machines, most instructions do not affect the condition +code and there may not even be a separate condition code register. On +these machines, the restriction that the definition and use of the +condition code be adjacent insns is not necessary and can prevent +important optimizations. For example, on the IBM RS/6000, there is a +delay for taken branches unless the condition code register is set three +instructions earlier than the conditional branch. The instruction +scheduler cannot perform this optimization if it is not permitted to +separate the definition and use of the condition code register. + +On these machines, do not use @code{(cc0)}, but instead use a register +to represent the condition code. If there is a specific condition code +register in the machine, use a hard register. If the condition code or +comparison result can be placed in any general register, or if there are +multiple condition registers, use a pseudo register. + +@findex prev_cc0_setter +@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 +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 +and use of the condition code must be adjacent (separated only by +@code{note} insns) allowing flags in @code{cc_status} to be used. +(@xref{Condition Code}.) Also, the comparison and branch insns can be +located from each other by using the functions @code{prev_cc0_setter} +and @code{next_cc0_user}. + +However, this is not true on machines that do not use @code{(cc0)}. On +those machines, no assumptions can be made about the adjacency of the +compare and branch insns and the above methods cannot be used. Instead, +we use the machine mode of the condition code register to record +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 +additional modes required (@pxref{Condition Code}). Also define +@code{EXTRA_CC_NAMES} to list the names of those modes and +@code{SELECT_CC_MODE} to choose a mode given an operand of a compare. + +If it is known during RTL generation that a different mode will be +required (for example, if the machine has separate compare instructions +for signed and unsigned quantities, like most IBM processors), they can +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 +discussed above, we have the pattern + +@smallexample +(define_insn "" + [(set (reg:CC_NOOV 0) + (compare:CC_NOOV + (plus:SI (match_operand:SI 0 "register_operand" "%r") + (match_operand:SI 1 "arith_operand" "rI")) + (const_int 0)))] + "" + "@dots{}") +@end smallexample + +The @code{SELECT_CC_MODE} macro on the Sparc returns @code{CC_NOOVmode} +for comparisons whose argument is a @code{plus}. + +@node Insn Canonicalizations +@section Canonicalization of Instructions +@cindex canonicalization of instructions +@cindex insn canonicalization + +There are often cases where multiple RTL expressions could represent an +operation performed by a single machine instruction. This situation is +most commonly encountered with logical, branch, and multiply-accumulate +instructions. In such cases, the compiler attempts to convert these +multiple RTL expressions into a single canonical form to reduce the +number of insn patterns required. + +In addition to algebraic simplifications, following canonicalizations +are performed: + +@itemize @bullet +@item +For commutative and comparison operators, a constant is always made the +second operand. If a machine only supports a constant as the second +operand, only patterns that match a constant in the second operand need +be supplied. + +@cindex @code{neg}, canonicalization of +@cindex @code{not}, canonicalization of +@cindex @code{mult}, canonicalization of +@cindex @code{plus}, canonicalization of +@cindex @code{minus}, canonicalization of +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. + +@cindex @code{compare}, canonicalization of +@item +For the @code{compare} operator, a constant is always the second operand +on machines where @code{cc0} is used (@pxref{Jump Patterns}). On other +machines, there are rare cases where the compiler might want to construct +a @code{compare} with a constant as the first operand. However, these +cases are not common enough for it to be worthwhile to provide a pattern +matching a constant as the first operand unless the machine actually has +such an instruction. + +An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or +@code{minus} is made the first operand under the same conditions as +above. + +@item +@code{(minus @var{x} (const_int @var{n}))} is converted to +@code{(plus @var{x} (const_int @var{-n}))}. + +@item +Within address computations (i.e., inside @code{mem}), a left shift is +converted into the appropriate multiplication by a power of two. + +@cindex @code{ior}, canonicalization of +@cindex @code{and}, canonicalization of +@cindex De Morgan's law +De`Morgan's Law is used to move bitwise negation inside a bitwise +logical-and or logical-or operation. If this results in only one +operand being a @code{not} expression, it will be the first one. + +A machine that has an instruction that performs a bitwise logical-and of one +operand with the bitwise negation of the other should specify the pattern +for that instruction as + +@example +(define_insn "" + [(set (match_operand:@var{m} 0 @dots{}) + (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) + (match_operand:@var{m} 2 @dots{})))] + "@dots{}" + "@dots{}") +@end example + +@noindent +Similarly, a pattern for a ``NAND'' instruction should be written + +@example +(define_insn "" + [(set (match_operand:@var{m} 0 @dots{}) + (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{})) + (not:@var{m} (match_operand:@var{m} 2 @dots{}))))] + "@dots{}" + "@dots{}") +@end example + +In both cases, it is not necessary to include patterns for the many +logically equivalent RTL expressions. + +@cindex @code{xor}, canonicalization of +@item +The only possible RTL expressions involving both bitwise exclusive-or +and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})} +and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.@refill + +@item +The sum of three items, one of which is a constant, will only appear in +the form + +@example +(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant}) +@end example + +@item +On machines that do not use @code{cc0}, +@code{(compare @var{x} (const_int 0))} will be converted to +@var{x}.@refill + +@cindex @code{zero_extract}, canonicalization of +@cindex @code{sign_extract}, canonicalization of +@item +Equality comparisons of a group of bits (usually a single bit) with zero +will be written using @code{zero_extract} rather than the equivalent +@code{and} or @code{sign_extract} operations. + +@end itemize + +@node Peephole Definitions +@section Machine-Specific Peephole Optimizers +@cindex peephole optimizer definitions +@cindex defining peephole optimizers + +In addition to instruction patterns the @file{md} file may contain +definitions of machine-specific peephole optimizations. + +The combiner does not notice certain peephole optimizations when the data +flow in the program does not suggest that it should try them. For example, +sometimes two consecutive insns related in purpose can be combined even +though the second one does not appear to use a register computed in the +first one. A machine-specific peephole optimizer can detect such +opportunities. + +@need 1000 +A definition looks like this: + +@smallexample +(define_peephole + [@var{insn-pattern-1} + @var{insn-pattern-2} + @dots{}] + "@var{condition}" + "@var{template}" + "@var{optional insn-attributes}") +@end smallexample + +@noindent +The last string operand may be omitted if you are not using any +machine-specific information in this machine description. If present, +it must obey the same rules as in a @code{define_insn}. + +In this skeleton, @var{insn-pattern-1} and so on are patterns to match +consecutive insns. The optimization applies to a sequence of insns when +@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches +the next, and so on.@refill + +Each of the insns matched by a peephole must also match a +@code{define_insn}. Peepholes are checked only at the last stage just +before code generation, and only optionally. Therefore, any insn which +would match a peephole but no @code{define_insn} will cause a crash in code +generation in an unoptimized compilation, or at various optimization +stages. + +The operands of the insns are matched with @code{match_operands}, +@code{match_operator}, and @code{match_dup}, as usual. What is not +usual is that the operand numbers apply to all the insn patterns in the +definition. So, you can check for identical operands in two insns by +using @code{match_operand} in one insn and @code{match_dup} in the +other. + +The operand constraints used in @code{match_operand} patterns do not have +any direct effect on the applicability of the peephole, but they will +be validated afterward, so make sure your constraints are general enough +to apply whenever the peephole matches. If the peephole matches +but the constraints are not satisfied, the compiler will crash. + +It is safe to omit constraints in all the operands of the peephole; or +you can write constraints which serve as a double-check on the criteria +previously tested. + +Once a sequence of insns matches the patterns, the @var{condition} is +checked. This is a C expression which makes the final decision whether to +perform the optimization (we do so if the expression is nonzero). If +@var{condition} is omitted (in other words, the string is empty) then the +optimization is applied to every sequence of insns that matches the +patterns. + +The defined peephole optimizations are applied after register allocation +is complete. Therefore, the peephole definition can check which +operands have ended up in which kinds of registers, just by looking at +the operands. + +@findex prev_nonnote_insn +The way to refer to the operands in @var{condition} is to write +@code{operands[@var{i}]} for operand number @var{i} (as matched by +@code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} +to refer to the last of the insns being matched; use +@code{prev_nonnote_insn} to find the preceding insns. + +@findex dead_or_set_p +When optimizing computations with intermediate results, you can use +@var{condition} to match only when the intermediate results are not used +elsewhere. Use the C expression @code{dead_or_set_p (@var{insn}, +@var{op})}, where @var{insn} is the insn in which you expect the value +to be used for the last time (from the value of @code{insn}, together +with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate +value (from @code{operands[@var{i}]}).@refill + +Applying the optimization means replacing the sequence of insns with one +new insn. The @var{template} controls ultimate output of assembler code +for this combined insn. It works exactly like the template of a +@code{define_insn}. Operand numbers in this template are the same ones +used in matching the original sequence of insns. + +The result of a defined peephole optimizer does not need to match any of +the insn patterns in the machine description; it does not even have an +opportunity to match them. The peephole optimizer definition itself serves +as the insn pattern to control how the insn is output. + +Defined peephole optimizers are run as assembler code is being output, +so the insns they produce are never combined or rearranged in any way. + +Here is an example, taken from the 68000 machine description: + +@smallexample +(define_peephole + [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4))) + (set (match_operand:DF 0 "register_operand" "=f") + (match_operand:DF 1 "register_operand" "ad"))] + "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])" + "* +@{ + rtx xoperands[2]; + xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1); +#ifdef MOTOROLA + output_asm_insn (\"move.l %1,(sp)\", xoperands); + output_asm_insn (\"move.l %1,-(sp)\", operands); + return \"fmove.d (sp)+,%0\"; +#else + output_asm_insn (\"movel %1,sp@@\", xoperands); + output_asm_insn (\"movel %1,sp@@-\", operands); + return \"fmoved sp@@+,%0\"; +#endif +@} +") +@end smallexample + +@need 1000 +The effect of this optimization is to change + +@smallexample +@group +jbsr _foobar +addql #4,sp +movel d1,sp@@- +movel d0,sp@@- +fmoved sp@@+,fp0 +@end group +@end smallexample + +@noindent +into + +@smallexample +@group +jbsr _foobar +movel d1,sp@@ +movel d0,sp@@- +fmoved sp@@+,fp0 +@end group +@end smallexample + +@ignore +@findex CC_REVERSED +If a peephole matches a sequence including one or more jump insns, you must +take account of the flags such as @code{CC_REVERSED} which specify that the +condition codes are represented in an unusual manner. The compiler +automatically alters any ordinary conditional jumps which occur in such +situations, but the compiler cannot alter jumps which have been replaced by +peephole optimizations. So it is up to you to alter the assembler code +that the peephole produces. Supply C code to write the assembler output, +and in this C code check the condition code status flags and change the +assembler code as appropriate. +@end ignore + +@var{insn-pattern-1} and so on look @emph{almost} like the second +operand of @code{define_insn}. There is one important difference: the +second operand of @code{define_insn} consists of one or more RTX's +enclosed in square brackets. Usually, there is only one: then the same +action can be written as an element of a @code{define_peephole}. But +when there are multiple actions in a @code{define_insn}, they are +implicitly enclosed in a @code{parallel}. Then you must explicitly +write the @code{parallel}, and the square brackets within it, in the +@code{define_peephole}. Thus, if an insn pattern looks like this, + +@smallexample +(define_insn "divmodsi4" + [(set (match_operand:SI 0 "general_operand" "=d") + (div:SI (match_operand:SI 1 "general_operand" "0") + (match_operand:SI 2 "general_operand" "dmsK"))) + (set (match_operand:SI 3 "general_operand" "=d") + (mod:SI (match_dup 1) (match_dup 2)))] + "TARGET_68020" + "divsl%.l %2,%3:%0") +@end smallexample + +@noindent +then the way to mention this insn in a peephole is as follows: + +@smallexample +(define_peephole + [@dots{} + (parallel + [(set (match_operand:SI 0 "general_operand" "=d") + (div:SI (match_operand:SI 1 "general_operand" "0") + (match_operand:SI 2 "general_operand" "dmsK"))) + (set (match_operand:SI 3 "general_operand" "=d") + (mod:SI (match_dup 1) (match_dup 2)))]) + @dots{}] + @dots{}) +@end smallexample + +@node Expander Definitions +@section Defining RTL Sequences for Code Generation +@cindex expander definitions +@cindex code generation RTL sequences +@cindex defining RTL sequences for code generation + +On some target machines, some standard pattern names for RTL generation +cannot be handled with single insn, but a sequence of RTL insns can +represent them. For these target machines, you can write a +@code{define_expand} to specify how to generate the sequence of RTL. + +@findex define_expand +A @code{define_expand} is an RTL expression that looks almost like a +@code{define_insn}; but, unlike the latter, a @code{define_expand} is used +only for RTL generation and it can produce more than one RTL insn. + +A @code{define_expand} RTX has four operands: + +@itemize @bullet +@item +The name. Each @code{define_expand} must have a name, since the only +use for it is to refer to it by name. + +@findex define_peephole +@item +The RTL template. This is just like the RTL template for a +@code{define_peephole} in that it is a vector of RTL expressions +each being one insn. + +@item +The condition, a string containing a C expression. This expression is +used to express how the availability of this pattern depends on +subclasses of target machine, selected by command-line options when +GNU CC is run. This is just like the condition of a +@code{define_insn} that has a standard name. + +@item +The preparation statements, a string containing zero or more C +statements which are to be executed before RTL code is generated from +the RTL template. + +Usually these statements prepare temporary registers for use as +internal operands in the RTL template, but they can also generate RTL +insns directly by calling routines such as @code{emit_insn}, etc. +Any such insns precede the ones that come from the RTL template. +@end itemize + +Every RTL insn emitted by a @code{define_expand} must match some +@code{define_insn} in the machine description. Otherwise, the compiler +will crash when trying to generate code for the insn or trying to optimize +it. + +The RTL template, in addition to controlling generation of RTL insns, +also describes the operands that need to be specified when this pattern +is used. In particular, it gives a predicate for each operand. + +A true operand, which needs to be specified in order to generate RTL from +the pattern, should be described with a @code{match_operand} in its first +occurrence in the RTL template. This enters information on the operand's +predicate into the tables that record such things. GNU CC uses the +information to preload the operand into a register if that is required for +valid RTL code. If the operand is referred to more than once, subsequent +references should use @code{match_dup}. + +The RTL template may also refer to internal ``operands'' which are +temporary registers or labels used only within the sequence made by the +@code{define_expand}. Internal operands are substituted into the RTL +template with @code{match_dup}, never with @code{match_operand}. The +values of the internal operands are not passed in as arguments by the +compiler when it requests use of this pattern. Instead, they are computed +within the pattern, in the preparation statements. These statements +compute the values and store them into the appropriate elements of +@code{operands} so that @code{match_dup} can find them. + +There are two special macros defined for use in the preparation statements: +@code{DONE} and @code{FAIL}. Use them with a following semicolon, +as a statement. + +@table @code + +@findex DONE +@item DONE +Use the @code{DONE} macro to end RTL generation for the pattern. The +only RTL insns resulting from the pattern on this occasion will be +those already emitted by explicit calls to @code{emit_insn} within the +preparation statements; the RTL template will not be generated. + +@findex FAIL +@item FAIL +Make the pattern fail on this occasion. When a pattern fails, it means +that the pattern was not truly available. The calling routines in the +compiler will try other strategies for code generation using other patterns. + +Failure is currently supported only for binary (addition, multiplication, +shifting, etc.) and bitfield (@code{extv}, @code{extzv}, and @code{insv}) +operations. +@end table + +Here is an example, the definition of left-shift for the SPUR chip: + +@smallexample +@group +(define_expand "ashlsi3" + [(set (match_operand:SI 0 "register_operand" "") + (ashift:SI +@end group +@group + (match_operand:SI 1 "register_operand" "") + (match_operand:SI 2 "nonmemory_operand" "")))] + "" + " +@end group +@end smallexample + +@smallexample +@group +@{ + if (GET_CODE (operands[2]) != CONST_INT + || (unsigned) INTVAL (operands[2]) > 3) + FAIL; +@}") +@end group +@end smallexample + +@noindent +This example uses @code{define_expand} so that it can generate an RTL insn +for shifting when the shift-count is in the supported range of 0 to 3 but +fail in other cases where machine insns aren't available. When it fails, +the compiler tries another strategy using different patterns (such as, a +library call). + +If the compiler were able to handle nontrivial condition-strings in +patterns with names, then it would be possible to use a +@code{define_insn} in that case. Here is another case (zero-extension +on the 68000) which makes more use of the power of @code{define_expand}: + +@smallexample +(define_expand "zero_extendhisi2" + [(set (match_operand:SI 0 "general_operand" "") + (const_int 0)) + (set (strict_low_part + (subreg:HI + (match_dup 0) + 0)) + (match_operand:HI 1 "general_operand" ""))] + "" + "operands[1] = make_safe_from (operands[1], operands[0]);") +@end smallexample + +@noindent +@findex make_safe_from +Here two RTL insns are generated, one to clear the entire output operand +and the other to copy the input operand into its low half. This sequence +is incorrect if the input operand refers to [the old value of] the output +operand, so the preparation statement makes sure this isn't so. The +function @code{make_safe_from} copies the @code{operands[1]} into a +temporary register if it refers to @code{operands[0]}. It does this +by emitting another RTL insn. + +Finally, a third example shows the use of an internal operand. +Zero-extension on the SPUR chip is done by @code{and}-ing the result +against a halfword mask. But this mask cannot be represented by a +@code{const_int} because the constant value is too large to be legitimate +on this machine. So it must be copied into a register with +@code{force_reg} and then the register used in the @code{and}. + +@smallexample +(define_expand "zero_extendhisi2" + [(set (match_operand:SI 0 "register_operand" "") + (and:SI (subreg:SI + (match_operand:HI 1 "register_operand" "") + 0) + (match_dup 2)))] + "" + "operands[2] + = force_reg (SImode, gen_rtx (CONST_INT, + VOIDmode, 65535)); ") +@end smallexample + +@strong{Note:} If the @code{define_expand} is used to serve a +standard binary or unary arithmetic operation or a bitfield operation, +then the last insn it generates must not be a @code{code_label}, +@code{barrier} or @code{note}. It must be an @code{insn}, +@code{jump_insn} or @code{call_insn}. If you don't need a real insn +at the end, emit an insn to copy the result of the operation into +itself. Such an insn will generate no code, but it can avoid problems +in the compiler.@refill + +@node Insn Splitting +@section Defining How to Split Instructions +@cindex insn splitting +@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. + +Often you can rewrite the single insn as a list of individual insns, +each corresponding to one machine instruction. The disadvantage of +doing so is that it will cause the compilation to be slower and require +more space. If the resulting insns are too complex, it may also +suppress some optimizations. The compiler splits the insn if there is a +reason to believe that it might improve instruction or delay slot +scheduling. + +The insn combiner phase also splits putative insns. If three insns are +merged into one insn with a complex expression that cannot be matched by +some @code{define_insn} pattern, the combiner phase attempts to split +the complex pattern into two insns that are recognized. Usually it can +break the complex pattern into two patterns by splitting out some +subexpression. However, in some other cases, such as performing an +addition of a large constant in two insns on a RISC machine, the way to +split the addition into two insns is machine-dependent. + +@cindex define_split +The @code{define_split} definition tells the compiler how to split a +complex insn into several simpler insns. It looks like this: + +@smallexample +(define_split + [@var{insn-pattern}] + "@var{condition}" + [@var{new-insn-pattern-1} + @var{new-insn-pattern-2} + @dots{}] + "@var{preparation statements}") +@end smallexample + +@var{insn-pattern} is a pattern that needs to be split and +@var{condition} is the final condition to be tested, as in a +@code{define_insn}. When an insn matching @var{insn-pattern} and +satisfying @var{condition} is found, it is replaced in the insn list +with the insns given by @var{new-insn-pattern-1}, +@var{new-insn-pattern-2}, etc. + +The @var{preparation statements} are similar to those statements that +are specified for @code{define_expand} (@pxref{Expander Definitions}) +and are executed before the new RTL is generated to prepare for the +generated code or emit some insns whose pattern is not fixed. Unlike +those in @code{define_expand}, however, these statements must not +generate any new pseudo-registers. Once reload has completed, they also +must not allocate any space in the stack frame. + +Patterns are matched against @var{insn-pattern} in two different +circumstances. If an insn needs to be split for delay slot scheduling +or insn scheduling, the insn is already known to be valid, which means +that it must have been matched by some @code{define_insn} and, if +@code{reload_completed} is non-zero, is known to satisfy the constraints +of that @code{define_insn}. In that case, the new insn patterns must +also be insns that are matched by some @code{define_insn} and, if +@code{reload_completed} is non-zero, must also satisfy the constraints +of those definitions. + +As an example of this usage of @code{define_split}, consider the following +example from @file{a29k.md}, which splits a @code{sign_extend} from +@code{HImode} to @code{SImode} into a pair of shift insns: + +@smallexample +(define_split + [(set (match_operand:SI 0 "gen_reg_operand" "") + (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))] + "" + [(set (match_dup 0) + (ashift:SI (match_dup 1) + (const_int 16))) + (set (match_dup 0) + (ashiftrt:SI (match_dup 0) + (const_int 16)))] + " +@{ operands[1] = gen_lowpart (SImode, operands[1]); @}") +@end smallexample + +When the combiner phase tries to split an insn pattern, it is always the +case that the pattern is @emph{not} matched by any @code{define_insn}. +The combiner pass first tries to split a single @code{set} expression +and then the same @code{set} expression inside a @code{parallel}, but +followed by a @code{clobber} of a pseudo-reg to use as a scratch +register. In these cases, the combiner expects exactly two new insn +patterns to be generated. It will verify that these patterns match some +@code{define_insn} definitions, so you need not do this test in the +@code{define_split} (of course, there is no point in writing a +@code{define_split} that will never produce insns that match). + +Here is an example of this use of @code{define_split}, taken from +@file{rs6000.md}: + +@smallexample +(define_split + [(set (match_operand:SI 0 "gen_reg_operand" "") + (plus:SI (match_operand:SI 1 "gen_reg_operand" "") + (match_operand:SI 2 "non_add_cint_operand" "")))] + "" + [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3))) + (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))] +" +@{ + int low = INTVAL (operands[2]) & 0xffff; + int high = (unsigned) INTVAL (operands[2]) >> 16; + + if (low & 0x8000) + high++, low |= 0xffff0000; + + operands[3] = gen_rtx (CONST_INT, VOIDmode, high << 16); + operands[4] = gen_rtx (CONST_INT, VOIDmode, low); +@}") +@end smallexample + +Here the predicate @code{non_add_cint_operand} matches any +@code{const_int} that is @emph{not} a valid operand of a single add +insn. The add with the smaller displacement is written so that it +can be substituted into the address of a subsequent operation. + +An example that uses a scratch register, from the same file, generates +an equality comparison of a register and a large constant: + +@smallexample +(define_split + [(set (match_operand:CC 0 "cc_reg_operand" "") + (compare:CC (match_operand:SI 1 "gen_reg_operand" "") + (match_operand:SI 2 "non_short_cint_operand" ""))) + (clobber (match_operand:SI 3 "gen_reg_operand" ""))] + "find_single_use (operands[0], insn, 0) + && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ + || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)" + [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4))) + (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))] + " +@{ + /* Get the constant we are comparing against, C, and see what it + looks like sign-extended to 16 bits. Then see what constant + could be XOR'ed with C to get the sign-extended value. */ + + int c = INTVAL (operands[2]); + int sextc = (c << 16) >> 16; + int xorv = c ^ sextc; + + operands[4] = gen_rtx (CONST_INT, VOIDmode, xorv); + operands[5] = gen_rtx (CONST_INT, VOIDmode, sextc); +@}") +@end smallexample + +To avoid confusion, don't write a single @code{define_split} that +accepts some insns that match some @code{define_insn} as well as some +insns that don't. Instead, write two separate @code{define_split} +definitions, one for the insns that are valid and one for the insns that +are not valid. + +@node Insn Attributes +@section Instruction Attributes +@cindex insn attributes +@cindex instruction attributes + +In addition to describing the instruction supported by the target machine, +the @file{md} file also defines a group of @dfn{attributes} and a set of +values for each. Every generated insn is assigned a value for each attribute. +One possible attribute would be the effect that the insn has on the machine's +condition code. This attribute can then be used by @code{NOTICE_UPDATE_CC} +to track the condition codes. + +@menu +* Defining Attributes:: Specifying attributes and their values. +* Expressions:: Valid expressions for attribute values. +* Tagging Insns:: Assigning attribute values to insns. +* Attr Example:: An example of assigning attributes. +* 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. +@end menu + +@node Defining Attributes +@subsection Defining Attributes and their Values +@cindex defining attributes and their values +@cindex attributes, defining + +@findex define_attr +The @code{define_attr} expression is used to define each attribute required +by the target machine. It looks like: + +@smallexample +(define_attr @var{name} @var{list-of-values} @var{default}) +@end smallexample + +@var{name} is a string specifying the name of the attribute being defined. + +@var{list-of-values} is either a string that specifies a comma-separated +list of values that can be assigned to the attribute, or a null string to +indicate that the attribute takes numeric values. + +@var{default} is an attribute expression that gives the value of this +attribute for insns that match patterns whose definition does not include +an explicit value for this attribute. @xref{Attr Example}, for more +information on the handling of defaults. @xref{Constant Attributes}, +for information on attributes that do not depend on any particular insn. + +@findex insn-attr.h +For each defined attribute, a number of definitions are written to the +@file{insn-attr.h} file. For cases where an explicit set of values is +specified for an attribute, the following are defined: + +@itemize @bullet +@item +A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}. + +@item +An enumeral class is defined for @samp{attr_@var{name}} with +elements of the form @samp{@var{upper-name}_@var{upper-value}} where +the attribute name and value are first converted to upper case. + +@item +A function @samp{get_attr_@var{name}} is defined that is passed an insn and +returns the attribute value for that insn. +@end itemize + +For example, if the following is present in the @file{md} file: + +@smallexample +(define_attr "type" "branch,fp,load,store,arith" @dots{}) +@end smallexample + +@noindent +the following lines will be written to the file @file{insn-attr.h}. + +@smallexample +#define HAVE_ATTR_type +enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD, + TYPE_STORE, TYPE_ARITH@}; +extern enum attr_type get_attr_type (); +@end smallexample + +If the attribute takes numeric values, no @code{enum} type will be +defined and the function to obtain the attribute's value will return +@code{int}. + +@node Expressions +@subsection Attribute Expressions +@cindex attribute expressions + +RTL expressions used to define attributes use the codes described above +plus a few specific to attribute definitions, to be discussed below. +Attribute value expressions must have one of the following forms: + +@table @code +@cindex @code{const_int} and attributes +@item (const_int @var{i}) +The integer @var{i} specifies the value of a numeric attribute. @var{i} +must be non-negative. + +The value of a numeric attribute can be specified either with a +@code{const_int} or as an integer represented as a string in +@code{const_string}, @code{eq_attr} (see below), and @code{set_attr} +(@pxref{Tagging Insns}) expressions. + +@cindex @code{const_string} and attributes +@item (const_string @var{value}) +The string @var{value} specifies a constant attribute value. +If @var{value} is specified as @samp{"*"}, it means that the default value of +the attribute is to be used for the insn containing this expression. +@samp{"*"} obviously cannot be used in the @var{default} expression +of a @code{define_attr}.@refill + +If the attribute whose value is being specified is numeric, @var{value} +must be a string containing a non-negative integer (normally +@code{const_int} would be used in this case). Otherwise, it must +contain one of the valid values for the attribute. + +@cindex @code{if_then_else} and attributes +@item (if_then_else @var{test} @var{true-value} @var{false-value}) +@var{test} specifies an attribute test, whose format is defined below. +The value of this expression is @var{true-value} if @var{test} is true, +otherwise it is @var{false-value}. + +@cindex @code{cond} and attributes +@item (cond [@var{test1} @var{value1} @dots{}] @var{default}) +The first operand of this expression is a vector containing an even +number of expressions and consisting of pairs of @var{test} and @var{value} +expressions. The value of the @code{cond} expression is that of the +@var{value} corresponding to the first true @var{test} expression. If +none of the @var{test} expressions are true, the value of the @code{cond} +expression is that of the @var{default} expression. +@end table + +@var{test} expressions can have one of the following forms: + +@table @code +@cindex @code{const_int} and attribute tests +@item (const_int @var{i}) +This test is true if @var{i} is non-zero and false otherwise. + +@cindex @code{not} and attributes +@cindex @code{ior} and attributes +@cindex @code{and} and attributes +@item (not @var{test}) +@itemx (ior @var{test1} @var{test2}) +@itemx (and @var{test1} @var{test2}) +These tests are true if the indicated logical function is true. + +@cindex @code{match_operand} and attributes +@item (match_operand:@var{m} @var{n} @var{pred} @var{constraints}) +This test is true if operand @var{n} of the insn whose attribute value +is being determined has mode @var{m} (this part of the test is ignored +if @var{m} is @code{VOIDmode}) and the function specified by the string +@var{pred} returns a non-zero value when passed operand @var{n} and mode +@var{m} (this part of the test is ignored if @var{pred} is the null +string). + +The @var{constraints} operand is ignored and should be the null string. + +@cindex @code{le} and attributes +@cindex @code{leu} and attributes +@cindex @code{lt} and attributes +@cindex @code{gt} and attributes +@cindex @code{gtu} and attributes +@cindex @code{ge} and attributes +@cindex @code{geu} and attributes +@cindex @code{ne} and attributes +@cindex @code{eq} and attributes +@cindex @code{plus} and attributes +@cindex @code{minus} and attributes +@cindex @code{mult} and attributes +@cindex @code{div} and attributes +@cindex @code{mod} and attributes +@cindex @code{abs} and attributes +@cindex @code{neg} and attributes +@cindex @code{ashift} and attributes +@cindex @code{lshiftrt} and attributes +@cindex @code{ashiftrt} and attributes +@item (le @var{arith1} @var{arith2}) +@itemx (leu @var{arith1} @var{arith2}) +@itemx (lt @var{arith1} @var{arith2}) +@itemx (ltu @var{arith1} @var{arith2}) +@itemx (gt @var{arith1} @var{arith2}) +@itemx (gtu @var{arith1} @var{arith2}) +@itemx (ge @var{arith1} @var{arith2}) +@itemx (geu @var{arith1} @var{arith2}) +@itemx (ne @var{arith1} @var{arith2}) +@itemx (eq @var{arith1} @var{arith2}) +These tests are true if the indicated comparison of the two arithmetic +expressions is true. Arithmetic expressions are formed with +@code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod}, +@code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not}, +@code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions.@refill + +@findex get_attr +@code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn +Lengths},for additional forms). @code{symbol_ref} is a string +denoting a C expression that yields an @code{int} when evaluated by the +@samp{get_attr_@dots{}} routine. It should normally be a global +variable.@refill + +@findex eq_attr +@item (eq_attr @var{name} @var{value}) +@var{name} is a string specifying the name of an attribute. + +@var{value} is a string that is either a valid value for attribute +@var{name}, a comma-separated list of values, or @samp{!} followed by a +value or list. If @var{value} does not begin with a @samp{!}, this +test is true if the value of the @var{name} attribute of the current +insn is in the list specified by @var{value}. If @var{value} begins +with a @samp{!}, this test is true if the attribute's value is +@emph{not} in the specified list. + +For example, + +@smallexample +(eq_attr "type" "load,store") +@end smallexample + +@noindent +is equivalent to + +@smallexample +(ior (eq_attr "type" "load") (eq_attr "type" "store")) +@end smallexample + +If @var{name} specifies an attribute of @samp{alternative}, it refers to the +value of the compiler variable @code{which_alternative} +(@pxref{Output Statement}) and the values must be small integers. For +example,@refill + +@smallexample +(eq_attr "alternative" "2,3") +@end smallexample + +@noindent +is equivalent to + +@smallexample +(ior (eq (symbol_ref "which_alternative") (const_int 2)) + (eq (symbol_ref "which_alternative") (const_int 3))) +@end smallexample + +Note that, for most attributes, an @code{eq_attr} test is simplified in cases +where the value of the attribute being tested is known for all insns matching +a particular pattern. This is by far the most common case.@refill + +@findex attr_flag +@item (attr_flag @var{name}) +The value of an @code{attr_flag} expression is true if the flag +specified by @var{name} is true for the @code{insn} currently being +scheduled. + +@var{name} is a string specifying one of a fixed set of flags to test. +Test the flags @code{forward} and @code{backward} to determine the +direction of a conditional branch. Test the flags @code{very_likely}, +@code{likely}, @code{very_unlikely}, and @code{unlikely} to determine +if a conditional branch is expected to be taken. + +If the @code{very_likely} flag is true, then the @code{likely} flag is also +true. Likewise for the @code{very_unlikely} and @code{unlikely} flags. + +This example describes a conditional branch delay slot which +can be nullified for forward branches that are taken (annul-true) or +for backward branches which are not taken (annul-false). + +@smallexample +(define_delay (eq_attr "type" "cbranch") + [(eq_attr "in_branch_delay" "true") + (and (eq_attr "in_branch_delay" "true") + (attr_flag "forward")) + (and (eq_attr "in_branch_delay" "true") + (attr_flag "backward"))]) +@end smallexample + +The @code{forward} and @code{backward} flags are false if the current +@code{insn} being scheduled is not a conditional branch. + +The @code{very_likely} and @code{likely} flags are true if the +@code{insn} being scheduled is not a conditional branch. The +The @code{very_unlikely} and @code{unlikely} flags are false if the +@code{insn} being scheduled is not a conditional branch. + +@code{attr_flag} is only used during delay slot scheduling and has no +meaning to other passes of the compiler. +@end table + +@node Tagging Insns +@subsection Assigning Attribute Values to Insns +@cindex tagging insns +@cindex assigning attribute values to insns + +The value assigned to an attribute of an insn is primarily determined by +which pattern is matched by that insn (or which @code{define_peephole} +generated it). Every @code{define_insn} and @code{define_peephole} can +have an optional last argument to specify the values of attributes for +matching insns. The value of any attribute not specified in a particular +insn is set to the default value for that attribute, as specified in its +@code{define_attr}. Extensive use of default values for attributes +permits the specification of the values for only one or two attributes +in the definition of most insn patterns, as seen in the example in the +next section.@refill + +The optional last argument of @code{define_insn} and +@code{define_peephole} is a vector of expressions, each of which defines +the value for a single attribute. The most general way of assigning an +attribute's value is to use a @code{set} expression whose first operand is an +@code{attr} expression giving the name of the attribute being set. The +second operand of the @code{set} is an attribute expression +(@pxref{Expressions}) giving the value of the attribute.@refill + +When the attribute value depends on the @samp{alternative} attribute +(i.e., which is the applicable alternative in the constraint of the +insn), the @code{set_attr_alternative} expression can be used. It +allows the specification of a vector of attribute expressions, one for +each alternative. + +@findex set_attr +When the generality of arbitrary attribute expressions is not required, +the simpler @code{set_attr} expression can be used, which allows +specifying a string giving either a single attribute value or a list +of attribute values, one for each alternative. + +The form of each of the above specifications is shown below. In each case, +@var{name} is a string specifying the attribute to be set. + +@table @code +@item (set_attr @var{name} @var{value-string}) +@var{value-string} is either a string giving the desired attribute value, +or a string containing a comma-separated list giving the values for +succeeding alternatives. The number of elements must match the number +of alternatives in the constraint of the insn pattern. + +Note that it may be useful to specify @samp{*} for some alternative, in +which case the attribute will assume its default value for insns matching +that alternative. + +@findex set_attr_alternative +@item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}]) +Depending on the alternative of the insn, the value will be one of the +specified values. This is a shorthand for using a @code{cond} with +tests on the @samp{alternative} attribute. + +@findex attr +@item (set (attr @var{name}) @var{value}) +The first operand of this @code{set} must be the special RTL expression +@code{attr}, whose sole operand is a string giving the name of the +attribute being set. @var{value} is the value of the attribute. +@end table + +The following shows three different ways of representing the same +attribute value specification: + +@smallexample +(set_attr "type" "load,store,arith") + +(set_attr_alternative "type" + [(const_string "load") (const_string "store") + (const_string "arith")]) + +(set (attr "type") + (cond [(eq_attr "alternative" "1") (const_string "load") + (eq_attr "alternative" "2") (const_string "store")] + (const_string "arith"))) +@end smallexample + +@need 1000 +@findex define_asm_attributes +The @code{define_asm_attributes} expression provides a mechanism to +specify the attributes assigned to insns produced from an @code{asm} +statement. It has the form: + +@smallexample +(define_asm_attributes [@var{attr-sets}]) +@end smallexample + +@noindent +where @var{attr-sets} is specified the same as for both the +@code{define_insn} and the @code{define_peephole} expressions. + +These values will typically be the ``worst case'' attribute values. For +example, they might indicate that the condition code will be clobbered. + +A specification for a @code{length} attribute is handled specially. The +way to compute the length of an @code{asm} insn is to multiply the +length specified in the expression @code{define_asm_attributes} by the +number of machine instructions specified in the @code{asm} statement, +determined by counting the number of semicolons and newlines in the +string. Therefore, the value of the @code{length} attribute specified +in a @code{define_asm_attributes} should be the maximum possible length +of a single machine instruction. + +@node Attr Example +@subsection Example of Attribute Specifications +@cindex attribute specifications example +@cindex attribute specifications + +The judicious use of defaulting is important in the efficient use of +insn attributes. Typically, insns are divided into @dfn{types} and an +attribute, customarily called @code{type}, is used to represent this +value. This attribute is normally used only to define the default value +for other attributes. An example will clarify this usage. + +Assume we have a RISC machine with a condition code and in which only +full-word operations are performed in registers. Let us assume that we +can divide all insns into loads, stores, (integer) arithmetic +operations, floating point operations, and branches. + +Here we will concern ourselves with determining the effect of an insn on +the condition code and will limit ourselves to the following possible +effects: The condition code can be set unpredictably (clobbered), not +be changed, be set to agree with the results of the operation, or only +changed if the item previously set into the condition code has been +modified. + +Here is part of a sample @file{md} file for such a machine: + +@smallexample +(define_attr "type" "load,store,arith,fp,branch" (const_string "arith")) + +(define_attr "cc" "clobber,unchanged,set,change0" + (cond [(eq_attr "type" "load") + (const_string "change0") + (eq_attr "type" "store,branch") + (const_string "unchanged") + (eq_attr "type" "arith") + (if_then_else (match_operand:SI 0 "" "") + (const_string "set") + (const_string "clobber"))] + (const_string "clobber"))) + +(define_insn "" + [(set (match_operand:SI 0 "general_operand" "=r,r,m") + (match_operand:SI 1 "general_operand" "r,m,r"))] + "" + "@@ + move %0,%1 + load %0,%1 + store %0,%1" + [(set_attr "type" "arith,load,store")]) +@end smallexample + +Note that we assume in the above example that arithmetic operations +performed on quantities smaller than a machine word clobber the condition +code since they will set the condition code to a value corresponding to the +full-word result. + +@node Insn Lengths +@subsection Computing the Length of an Insn +@cindex insn lengths, computing +@cindex computing the length of an insn + +For many machines, multiple types of branch instructions are provided, each +for different length branch displacements. In most cases, the assembler +will choose the correct instruction to use. However, when the assembler +cannot do so, GCC can when a special attribute, the @samp{length} +attribute, is defined. This attribute must be defined to have numeric +values by specifying a null string in its @code{define_attr}. + +In the case of the @samp{length} attribute, two additional forms of +arithmetic terms are allowed in test expressions: + +@table @code +@cindex @code{match_dup} and attributes +@item (match_dup @var{n}) +This refers to the address of operand @var{n} of the current insn, which +must be a @code{label_ref}. + +@cindex @code{pc} and attributes +@item (pc) +This refers to the address of the @emph{current} insn. It might have +been more consistent with other usage to make this the address of the +@emph{next} insn but this would be confusing because the length of the +current insn is to be computed. +@end table + +@cindex @code{addr_vec}, length of +@cindex @code{addr_diff_vec}, length of +For normal insns, the length will be determined by value of the +@samp{length} attribute. In the case of @code{addr_vec} and +@code{addr_diff_vec} insn patterns, the length is computed as +the number of vectors multiplied by the size of each vector. + +Lengths are measured in addressable storage units (bytes). + +The following macros can be used to refine the length computation: + +@table @code +@findex FIRST_INSN_ADDRESS +@item FIRST_INSN_ADDRESS +When the @code{length} insn attribute is used, this macro specifies the +value to be assigned to the address of the first insn in a function. If +not specified, 0 is used. + +@findex ADJUST_INSN_LENGTH +@item ADJUST_INSN_LENGTH (@var{insn}, @var{length}) +If defined, modifies the length assigned to instruction @var{insn} as a +function of the context in which it is used. @var{length} is an lvalue +that contains the initially computed length of the insn and should be +updated with the correct length of the insn. If updating is required, +@var{insn} must not be a varying-length insn. + +This macro will normally not be required. A case in which it is +required is the ROMP. On this machine, the size of an @code{addr_vec} +insn must be increased by two to compensate for the fact that alignment +may be required. +@end table + +@findex get_attr_length +The routine that returns @code{get_attr_length} (the value of the +@code{length} attribute) can be used by the output routine to +determine the form of the branch instruction to be written, as the +example below illustrates. + +As an example of the specification of variable-length branches, consider +the IBM 360. If we adopt the convention that a register will be set to +the starting address of a function, we can jump to labels within 4k of +the start using a four-byte instruction. Otherwise, we need a six-byte +sequence to load the address from memory and then branch to it. + +On such a machine, a pattern for a branch instruction might be specified +as follows: + +@smallexample +(define_insn "jump" + [(set (pc) + (label_ref (match_operand 0 "" "")))] + "" + "* +@{ + return (get_attr_length (insn) == 4 + ? \"b %l0\" : \"l r15,=a(%l0); br r15\"); +@}" + [(set (attr "length") (if_then_else (lt (match_dup 0) (const_int 4096)) + (const_int 4) + (const_int 6)))]) +@end smallexample + +@node Constant Attributes +@subsection Constant Attributes +@cindex constant attributes + +A special form of @code{define_attr}, where the expression for the +default value is a @code{const} expression, indicates an attribute that +is constant for a given run of the compiler. Constant attributes may be +used to specify which variety of processor is used. For example, + +@smallexample +(define_attr "cpu" "m88100,m88110,m88000" + (const + (cond [(symbol_ref "TARGET_88100") (const_string "m88100") + (symbol_ref "TARGET_88110") (const_string "m88110")] + (const_string "m88000")))) + +(define_attr "memory" "fast,slow" + (const + (if_then_else (symbol_ref "TARGET_FAST_MEM") + (const_string "fast") + (const_string "slow")))) +@end smallexample + +The routine generated for constant attributes has no parameters as it +does not depend on any particular insn. RTL expressions used to define +the value of a constant attribute may use the @code{symbol_ref} form, +but may not use either the @code{match_operand} form or @code{eq_attr} +forms involving insn attributes. + +@node Delay Slots +@subsection Delay Slot Scheduling +@cindex delay slots, defining + +The insn attribute mechanism can be used to specify the requirements for +delay slots, if any, on a target machine. An instruction is said to +require a @dfn{delay slot} if some instructions that are physically +after the instruction are executed as if they were located before it. +Classic examples are branch and call instructions, which often execute +the following instruction before the branch or call is performed. + +On some machines, conditional branch instructions can optionally +@dfn{annul} instructions in the delay slot. This means that the +instruction will not be executed for certain branch outcomes. Both +instructions that annul if the branch is true and instructions that +annul if the branch is false are supported. + +Delay slot scheduling differs from instruction scheduling in that +determining whether an instruction needs a delay slot is dependent only +on the type of instruction being generated, not on data flow between the +instructions. See the next section for a discussion of data-dependent +instruction scheduling. + +@findex define_delay +The requirement of an insn needing one or more delay slots is indicated +via the @code{define_delay} expression. It has the following form: + +@smallexample +(define_delay @var{test} + [@var{delay-1} @var{annul-true-1} @var{annul-false-1} + @var{delay-2} @var{annul-true-2} @var{annul-false-2} + @dots{}]) +@end smallexample + +@var{test} is an attribute test that indicates whether this +@code{define_delay} applies to a particular insn. If so, the number of +required delay slots is determined by the length of the vector specified +as the second argument. An insn placed in delay slot @var{n} must +satisfy attribute test @var{delay-n}. @var{annul-true-n} is an +attribute test that specifies which insns may be annulled if the branch +is true. Similarly, @var{annul-false-n} specifies which insns in the +delay slot may be annulled if the branch is false. If annulling is not +supported for that delay slot, @code{(nil)} should be coded.@refill + +For example, in the common case where branch and call insns require +a single delay slot, which may contain any insn other than a branch or +call, the following would be placed in the @file{md} file: + +@smallexample +(define_delay (eq_attr "type" "branch,call") + [(eq_attr "type" "!branch,call") (nil) (nil)]) +@end smallexample + +Multiple @code{define_delay} expressions may be specified. In this +case, each such expression specifies different delay slot requirements +and there must be no insn for which tests in two @code{define_delay} +expressions are both true. + +For example, if we have a machine that requires one delay slot for branches +but two for calls, no delay slot can contain a branch or call insn, +and any valid insn in the delay slot for the branch can be annulled if the +branch is true, we might represent this as follows: + +@smallexample +(define_delay (eq_attr "type" "branch") + [(eq_attr "type" "!branch,call") + (eq_attr "type" "!branch,call") + (nil)]) + +(define_delay (eq_attr "type" "call") + [(eq_attr "type" "!branch,call") (nil) (nil) + (eq_attr "type" "!branch,call") (nil) (nil)]) +@end smallexample +@c the above is *still* too long. --mew 4feb93 + +@node Function Units +@subsection Specifying Function Units +@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. + +In addition, many newer microprocessors have multiple function units, usually +one for integer and one for floating point, and often will incur pipeline +stalls when a result that is needed is not yet ready. + +The descriptions in this section allow the specification of how much +time must elapse between the execution of an instruction and the time +when its result is used. It also allows specification of when the +execution of an instruction will delay execution of similar instructions +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. + +@findex define_function_unit +Each usage of a function units by a class of insns is specified with a +@code{define_function_unit} expression, which looks like this: + +@smallexample +(define_function_unit @var{name} @var{multiplicity} @var{simultaneity} + @var{test} @var{ready-delay} @var{issue-delay} + [@var{conflict-list}]) +@end smallexample + +@var{name} is a string giving the name of the function unit. + +@var{multiplicity} is an integer specifying the number of identical +units in the processor. If more than one unit is specified, they will +be scheduled independently. Only truly independent units should be +counted; a pipelined unit should be specified as a single unit. (The +only common example of a machine that has multiple function units for a +single instruction class that are truly independent and not pipelined +are the two multiply and two increment units of the CDC 6600.) + +@var{simultaneity} specifies the maximum number of insns that can be +executing in each instance of the function unit simultaneously or zero +if the unit is pipelined and has no limit. + +All @code{define_function_unit} definitions referring to function unit +@var{name} must have the same name and values for @var{multiplicity} and +@var{simultaneity}. + +@var{test} is an attribute test that selects the insns we are describing +in this definition. Note that an insn may use more than one function +unit and a function unit may be specified in more than one +@code{define_function_unit}. + +@var{ready-delay} is an integer that specifies the number of cycles +after which the result of the instruction can be used without +introducing any stalls. + +@var{issue-delay} is an integer that specifies the number of cycles +after the instruction matching the @var{test} expression begins using +this unit until a subsequent instruction can begin. A cost of @var{N} +indicates an @var{N-1} cycle delay. A subsequent instruction may also +be delayed if an earlier instruction has a longer @var{ready-delay} +value. This blocking effect is computed using the @var{simultaneity}, +@var{ready-delay}, @var{issue-delay}, and @var{conflict-list} terms. +For a normal non-pipelined function unit, @var{simultaneity} is one, the +unit is taken to block for the @var{ready-delay} cycles of the executing +insn, and smaller values of @var{issue-delay} are ignored. + +@var{conflict-list} is an optional list giving detailed conflict costs +for this unit. If specified, it is a list of condition test expressions +to be applied to insns chosen to execute in @var{name} following the +particular insn matching @var{test} that is already executing in +@var{name}. For each insn in the list, @var{issue-delay} specifies the +conflict cost; for insns not in the list, the cost is zero. If not +specified, @var{conflict-list} defaults to all instructions that use the +function unit. + +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: + +@smallexample +(define_function_unit "memory" 1 1 (eq_attr "type" "load") 2 0) +@end smallexample + +For the case of a floating point function unit that can pipeline either +single or double precision, but not both, the following could be specified: + +@smallexample +(define_function_unit + "fp" 1 0 (eq_attr "type" "sp_fp") 4 4 [(eq_attr "type" "dp_fp")]) +(define_function_unit + "fp" 1 0 (eq_attr "type" "dp_fp") 4 4 [(eq_attr "type" "sp_fp")]) +@end smallexample + +@strong{Note:} The scheduler attempts to avoid function unit conflicts +and uses all the specifications in the @code{define_function_unit} +expression. It has recently come to our attention that these +specifications may not allow modeling of some of the newer +``superscalar'' processors that have insns using multiple pipelined +units. These insns will cause a potential conflict for the second unit +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. +@end ifset diff --git a/gnu/usr.bin/cc/doc/reno.texi b/gnu/usr.bin/cc/doc/reno.texi new file mode 100644 index 0000000..59c3448 --- /dev/null +++ b/gnu/usr.bin/cc/doc/reno.texi @@ -0,0 +1,752 @@ +\input texinfo @c -*- Texinfo -*- +@setfilename reno-1.info + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Reno 1: (reno-1). The GNU C++ Renovation Project, Phase 1. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@setchapternewpage odd +@settitle GNU C++ Renovation Project +@c @smallbook + +@titlepage +@finalout +@title GNU C++ Renovation Project +@subtitle Phase 1.3 +@author Brendan Kehoe, Jason Merrill, +@author Mike Stump, Michael Tiemann +@page + +Edited March, 1994 by Roland Pesch (@code{pesch@@cygnus.com}) +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage + +@ifinfo +@node Top +@top @sc{gnu} C++ Renovation Project + +This file describes the goals of the @sc{gnu} C++ Renovation Project, +and its accomplishments to date (as of Phase 1.3). + +It also discusses the remaining divergences from @sc{gnu} C++, and how the +name encoding in @sc{gnu} C++ differs from the sample encoding in +@cite{The Annotated C++ Reference Manual}. +@c This is not a good place to introduce the acronym ARM because it's +@c info-only. + +@menu +* Introduction:: What is the GNU C++ Renovation Project? +* Changes:: Summary of changes since previous GNU C++ releases. +* Plans:: Plans for Reno-2. +* Templates:: The template implementation. +* ANSI:: GNU C++ conformance to ANSI C++. +* Encoding:: Name encoding in GNU C++. +@end menu + +@end ifinfo + +@node Introduction +@chapter Introduction + +As you may remember, @sc{gnu} C++ was the first native-code C++ +compiler available under Unix (December 1987). In November 1988, it was +judged superior to the AT&T compiler in a Unix World review. In 1990 it +won a Sun Observer ``Best-Of'' award. But now, with new requirements +coming out of the @sc{ansi} C++ committee and a growing backlog of bugs, it's +clear that @sc{gnu} C++ needs an overhaul. + +The C++ language has been under development since 1982. It has +evolved significantly since its original incarnation (C with Classes), +addressing many commercial needs and incorporating many lessons +learned as more and more people started using ``object-oriented'' +programming techniques. In 1989, the first X3J16 committee meeting +was held in Washington DC; in the interest of users, C++ was going to +be standardized. + +As C++ has become more popular, more demands have been placed on its +compilers. Some compilers are up to the demands, others are not. +@sc{gnu} C++ was used to prototype several features which have since +been incorporated into the standard, most notably exception handling. +While @sc{gnu} C++ has been an excellent experimental vehicle, it did +not have the resources that AT&T, Borland, or Microsoft have at their +disposal. + +We believe that @sc{gnu} C++ is an important compiler, providing users with +many of the features that have made @sc{gnu} C so popular: fast compilation, +good error messages, innovative features, and full sources that may be +freely redistributed. The purpose of this overhaul, dubbed the @var{@sc{gnu} +C++ Renovation Project}, is to take advantage of the functionality that +@sc{gnu} C++ offers today, to strengthen its base technology, and put it in a +position to remain---as other @sc{gnu} software currently is---the technical +leader in the field. + +This release represents the latest phase of work in strengthening the +compiler on a variety of points. It includes many months of +work concentrated on fixing many of the more egregious bugs that +presented themselves in the compiler recently. +@ignore +@c FIXME-- update? +Nearly 85% of all bugs reported in the period of February to September +of 1992 were fixed as part of the work in the first phase. +@end ignore +In the coming months, we hope to continue expanding and enhancing the +quality and dependability of the industry's only freely redistributable +C++ compiler. + +@node Changes +@chapter Changes in Behavior in @sc{gnu} C++ + +The @sc{gnu} C++ compiler continues to improve and change. A major goal +of our work has been to continue to bring the compiler into compliance +with the draft @sc{ansi} C++ standard, and with @cite{The Annotated C++ +Reference Manual} (the @sc{arm}). This section outlines most of the +user-noticeable changes that might be encountered during the normal +course of use. + +@menu +* Summary of Phase 1.3:: +* Major changes:: +* New features:: +* Enhancements and bug fixes:: +* Problems with debugging:: +@end menu + +@node Summary of Phase 1.3 +@section Summary of Changes in Phase 1.3 + +The bulk of this note discusses the cumulative effects of the @sc{gnu} C++ +Renovation Project to date. The work during its most recent phase (1.3) +had these major effects: + +@itemize @bullet +@item The standard compiler driver @code{g++} is now the faster compiled +version, rather than a shell script. + +@item Nested types work much better; notably, nesting is no longer +restricted to nine levels. + +@item Better @sc{arm} conformance on member access control. + +@item The compiler now always generates default assignment operators +(@samp{operator =}), copy constructors (@samp{X::X(X&)}), and default +constructors (@samp{X::X()}) whenever they are required. + +@item The new draft @sc{ansi} standard keyword @code{mutable} is supported. + +@item @samp{-fansi-overloading} is the default, to comply better with +the @sc{arm} (at some cost in compatibility to earlier versions of @sc{gnu} C++). + +@item More informative error messages. + +@item System include files are automatically treated as if they were +wrapped in @samp{extern "C" @{ @}}. + +@item The new option @samp{-falt-external-templates} provides alternate +template instantiation semantics. + +@item Operator declarations are now checked more strictly. + +@item You can now use template type arguments in the template parameter list. + +@item You can call the destructor for any type. + +@item The compiler source code is better organized. + +@item You can specify where to instantiate template definitions explicitly. +@end itemize + +Much of the work in Phase 1.3 went to elimination of known bugs, as well +as the major items above. + +During the span of Phase 1.3, there were also two changes associated +with the compiler that, while not specifically part of the C++ +Renovation project, may be of interest: + +@itemize @bullet +@item @code{gcov}, a code coverage tool for @sc{gnu cc}, is now available +from Cygnus Support. (@code{gcov} is free software, but the @sc{fsf} has not +yet accepted it.) @xref{Gcov,, @code{gcov}: a Test Coverage Program, +gcc.info, Using GNU CC}, for more information (in Cygnus releases of +that manual). + +@item @sc{gnu} C++ now supports @dfn{signatures}, a language extension to +provide more flexibility in abstract type definitions. @xref{C++ +Signatures,, Type Abstraction using Signatures, gcc.info, Using GNU CC}. +@end itemize + +@node Major changes +@section Major Changes + +This release includes four wholesale rewrites of certain areas of +compiler functionality: + +@enumerate 1 +@item Argument matching. @sc{gnu} C++ is more compliant with the rules +described in Chapter 13, ``Overloading'', of the @sc{arm}. This behavior is +the default, though you can specify it explicitly with +@samp{-fansi-overloading}. For compatibility with earlier releases of +@sc{gnu} C++, specify @samp{-fno-ansi-overloading}; this makes the compiler +behave as it used to with respect to argument matching and name overloading. + +@item Default constructors/destructors. Section 12.8 of the @sc{arm}, ``Copying +Class Objects'', and Section 12.1, ``Constructors'', state that a +compiler must declare such default functions if the user does not +specify them. @sc{gnu} C++ now declares, and generates when necessary, +the defaults for constructors and destructors you might omit. In +particular, assignment operators (@samp{operator =}) behave the same way +whether you define them, or whether the compiler generates them by +default; taking the address of the default @samp{operator =} is now +guaranteed to work. Default copy constructors (@samp{X::X(X&)}) now +function correctly, rather than calling the copy assignment operator for +the base class. Finally, constructors (@samp{X::X()}), as well as +assignment operators and copy constructors, are now available whenever +they are required. + +@c XXX This may be taken out eventually... +@item Binary incompatibility. There are no new binary incompatibilities +in Phase 1.3, but Phase 1.2 introduced two binary incompatibilities with +earlier releases. First, the functionality of @samp{operator +new} and @samp{operator delete} changed. Name encoding +(``mangling'') of virtual table names changed as well. Libraries +built with versions of the compiler earlier than Phase 1.2 must be +compiled with the new compiler. (This includes the Cygnus Q2 +progressive release and the FSF 2.4.5 release.) + +@item New @code{g++} driver. +A new binary @code{g++} compiler driver replaces the shell script. +The new driver executes faster. +@end enumerate + +@node New features +@section New features + +@itemize @bullet +@item +The compiler warns when a class contains only private constructors +or destructors, and has no friends. At the request of some of our +customers, we have added a new option, @samp{-Wctor-dtor-privacy} (on by +default), and its negation, @samp{-Wno-ctor-dtor-privacy}, to control +the emission of this warning. If, for example, you are working towards +making your code compile warning-free, you can use @w{@samp{-Wall +-Wno-ctor-dtor-privacy}} to find the most common warnings. + +@item +There is now a mechanism which controls exactly when templates are +expanded, so that you can reduce memory usage and program size and also +instantiate them exactly once. You can control this mechanism with the +option @samp{-fexternal-templates} and its corresponding negation +@samp{-fno-external-templates}. Without this feature, space consumed by +template instantiations can grow unacceptably in large-scale projects +with many different source files. The default is +@samp{-fno-external-templates}. + +You do not need to use the @samp{-fexternal-templates} option when +compiling a file that does not define and instantiate templates used in +other files, even if those files @emph{are} compiled with +@samp{-fexternal-templates}. The only side effect is an increase in +object size for each file that was compiled without +@samp{-fexternal-templates}. + +When your code is compiled with @samp{-fexternal-templates}, all +template instantiations are external; this requires that the templates +be under the control of @samp{#pragma interface} and @samp{#pragma +implementation}. All instantiations that will be needed should be in +the implementation file; you can do this with a @code{typedef} that +references the instantiation needed. Conversely, when you compile using +the option @samp{-fno-external-templates}, all template instantiations are +explicitly internal. + +@samp{-fexternal-templates} also allows you to finally separate class +template function definitions from their declarations, thus speeding up +compilation times for every file that includes the template declaration. +Now you can have tens or even hundreds of lines in template +declarations, and thousands or tens of thousands of lines in template +definitions, with the definitions only going through the compiler once +instead of once for each source file. It is important to note that you +must remember to externally instantiate @emph{all} templates that are +used from template declarations in interface files. If you forget to do +this, unresolved externals will occur. + +In the example below, the object file generated (@file{example.o}) will +contain the global instantiation for @samp{Stack<int>}. If other types +of @samp{Stack} are needed, they can be added to @file{example.cc} or +placed in a new file, in the same spirit as @file{example.cc}. + +@code{foo.h}: +@smallexample +@group +#pragma interface "foo.h" +template<class T> +class Stack @{ + static int statc; + static T statc2; + Stack() @{ @} + virtual ~Stack() @{ @} + int bar(); +@}; +@end group +@end smallexample + +@code{example.cc}: +@smallexample +@group +#pragma implementation "foo.h" +#include "foo.h" + +typedef Stack<int> t; +int Stack<int>::statc; +int Stack<int>::statc2; +int Stack<int>::bar() @{ @} +@end group +@end smallexample + +Note that using @samp{-fexternal-templates} does not reduce memory usage +from completely different instantiations (@samp{Stack<Name>} vs. +@samp{Stack<Net_Connection>}), but only collapses different occurrences +of @samp{Stack<Name>} so that only one @samp{Stack<Name>} is generated. + +@samp{-falt-external-templates} selects a slight variation in the +semantics described above (incidentally, you need not specify both +options; @samp{-falt-external-templates} implies +@samp{-fexternal-templates}). + +With @samp{-fexternal-templates}, the compiler emits a definition in the +implementation file that includes the header definition, @emph{even if} +instantiation is triggered from a @emph{different} implementation file +(e.g. with a template that uses another template). + +With @samp{-falt-external-templates}, the definition always goes in the +implementation file that triggers instantiation. + +For instance, with these two header files--- + +@example +@exdent @file{a.h}: +#pragma interface +template <class T> class A @{ @dots{} @}; + +@exdent @file{b.h}: +#pragma interface +class B @{ @dots{} @}; +void f (A<B>); +@end example + +Under @samp{-fexternal-templates}, the definition of @samp{A<B>} ends up +in the implementation file that includes @file{a.h}. Under +@samp{-falt-external-templates}, the same definition ends up in the +implementation file that includes @file{b.h}. + +@item +You can control explicitly where a template is instantiated, without +having to @emph{use} the template to get an instantiation. + +To instantiate a class template explicitly, write @samp{template +class @var{name}<paramvals>}, where @var{paramvals} is a list of values +for the template parameters. For example, you might write + +@example +template class A<int> +@end example + +Similarly, to instantiate a function template explicitly, write +@samp{template @var{fnsign}} where @var{fnsign} is the particular +function signature you need. For example, you might write + +@example +template void foo (int, int) +@end example + +This syntax for explicit template instantiation agrees with recent +extensions to the draft @sc{ansi} standard. + +@item +The compiler's actions on @sc{ansi}-related warnings and errors have +been further enhanced. The @samp{-pedantic-errors} option produces +error messages in a number of new situations: using @code{return} in a +non-@code{void} function (one returning a value); declaring a local +variable that shadows a parameter (e.g., the function takes an argument +@samp{a}, and has a local variable @samp{a}); and use of the @samp{asm} +keyword. Finally, the compiler by default now issues a warning when +converting from an @code{int} to an enumerated type. This is likely to +cause many new warnings in code that hadn't triggered them before. For +example, when you compile this code, + +@smallexample +@group +enum boolean @{ false, true @}; +void +f () +@{ + boolean x; + + x = 1; //@i{assigning an @code{int} to an @code{enum} now triggers a warning} +@} +@end group +@end smallexample + +@noindent +you should see the warning ``@code{anachronistic conversion from integer +type to enumeral type `boolean'}''. Instead of assigning the value 1, +assign the original enumerated value @samp{true}. +@end itemize + +@node Enhancements and bug fixes +@section Enhancements and bug fixes + +@itemize @bullet +@cindex nested types in template parameters +@item +You can now use nested types in a template parameter list, even if the nested +type is defined within the same class that attempts to use the template. +For example, given a template @code{list}, the following now works: + +@smallexample +struct glyph @{ + @dots{} + struct stroke @{ @dots{} @}; + list<stroke> l; + @dots{} +@} +@end smallexample + +@cindex function pointers vs template parameters +@item +Function pointers now work in template parameter lists. For +example, you might want to instantiate a parameterized @code{list} class +in terms of a pointer to a function like this: + +@smallexample +list<int (*)(int, void *)> fnlist; +@end smallexample + +@item +@c FIXME! Really no limit? Jason said "deeper than 9" now OK... +Nested types are now handled correctly. In particular, there is no +longer a limit to how deeply you can nest type definitions. + +@item +@sc{gnu} C++ now conforms to the specifications in Chapter 11 of the +@sc{arm}, ``Member Access Control''. + +@item +The @sc{ansi} C++ committee has introduced a new keyword @code{mutable}. +@sc{gnu} C++ supports it. Use @code{mutable} to specify that some +particular members of a @code{const} class are @emph{not} constant. For +example, you can use this to include a cache in a data structure that +otherwise represents a read-only database. + +@item +Error messages now explicitly specify the declaration, type, or +expression that contains an error. + +@item +To avoid copying and editing all system include files during @sc{gnu} +C++ installation, the compiler now automatically recognizes system +include files as C language definitions, as if they were wrapped in +@samp{extern "C" @{ @dots{} @}}. + +@item +The compiler checks operator declarations more strictly. For example, +you may no longer declare an @samp{operator +} with three arguments. + +@item +You can now use template type arguments in the same template +parameter list where the type argument is specified (as well as in the +template body). For example, you may write + +@example +template <class T, T t> class A @{ @dots{} @}; +@end example + +@item +Destructors are now available for all types, even built-in ones; for +example, you can call @samp{int::~int}. (Destructors for types like +@code{int} do not actually do anything, but their existence provides a +level of generality that permits smooth template expansion in more +cases.) + +@item +Enumerated types declared inside a class are now handled correctly. + +@item +An argument list for a function may not use an initializer list for its default +value. For example, @w{@samp{void foo ( T x = @{ 1, 2 @} )}} is not permitted. + +@item +A significant amount of work went into improving the ability of the +compiler to act accurately on multiple inheritance and virtual +functions. Virtual function dispatch has been enhanced as well. + +@item +The warning concerning a virtual inheritance environment with a +non-virtual destructor has been disabled, since it is not clear that +such a warning is warranted. + +@item +Until exception handling is fully implemented in the Reno-2 release, use +of the identifiers @samp{catch}, @samp{throw}, or @samp{try} results +in the warning: + +@smallexample +t.C:1: warning: `catch', `throw', and `try' + are all C++ reserved words +@end smallexample + +@item +When giving a warning or error concerning initialization of a member in a +class, the compiler gives the name of the member if it has one. + +@item +Detecting friendship between classes is more accurately checked. + +@item +The syntaxes of @w{@samp{#pragma implementation "file.h"}} and +@samp{#pragma interface} are now more strictly controlled. The compiler +notices (and warns) when any text follows @file{file.h} in the +implementation pragma, or follows the word @samp{interface}. Any such +text is otherwise ignored. + +@item +Trying to declare a template on a variable or type is now considered an +error, not an unimplemented feature. + +@item +When an error occurs involving a template, the compiler attempts to +tell you at which point of instantiation the error occurred, in +addition to noting the line in the template declaration which had the +actual error. + +@item +The symbol names for function templates in the resulting assembly file +are now encoded according to the arguments, rather than just being +emitted as, for example, two definitions of a function @samp{foo}. + +@item +Template member functions that are declared @code{static} no longer +receive a @code{this} pointer. + +@item +Case labels are no longer allowed to have commas to make up their +expressions. + +@item +Warnings concerning the shift count of a left or right shift now tell +you if it was a @samp{left} or @samp{right} shift. + +@item +The compiler now warns when a decimal constant is so large that it +becomes @code{unsigned}. + +@item +Union initializers which are raw constructors are now handled properly. + +@item +The compiler no longer gives incorrect errors when initializing a +union with an empty initializer list. + +@item +Anonymous unions are now correctly used when nested inside a class. + +@item +Anonymous unions declared as static class members are now handled +properly. + +@item +The compiler now notices when a field in a class is declared both as +a type and a non-type. + +@item +The compiler now warns when a user-defined function shadows a +built-in function, rather than emitting an error. + +@item +A conflict between two function declarations now produces an error +regardless of their language context. + +@item +Duplicate definitions of variables with @samp{extern "C"} linkage are no +longer considered in error. (Note in C++ linkage---the default---you may +not have more than one definition of a variable.) + +@item +Referencing a label that is not defined in any function is now an error. + +@item +The syntax for pointers to methods has been improved; there are still +some minor bugs, but a number of cases should now be accepted by the +compiler. + +@item +In error messages, arguments are now numbered starting at 1, instead of +0. Therefore, in the function @samp{void foo (int a, int b)}, the +argument @samp{a} is argument 1, and @samp{b} is argument 2. There is +no longer an argument 0. + +@item +The tag for an enumerator, rather than its value, used as a default +argument is now shown in all error messages. For example, @w{@samp{void +foo (enum x (= true))}} is shown instead of @w{@samp{void foo (enum x (= +1))}}. + +@item +The @samp{__asm__} keyword is now accepted by the C++ front-end. + +@item +Expressions of the form @samp{foo->~Class()} are now handled properly. + +@item +The compiler now gives better warnings for situations which result in +integer overflows (e.g., in storage sizes, enumerators, unary +expressions, etc). + +@item +@code{unsigned} bitfields are now promoted to @code{signed int} if the +field isn't as wide as an @code{int}. + +@item +Declaration and usage of prefix and postfix @samp{operator ++} and +@samp{operator --} are now handled correctly. For example, + +@smallexample +@group +class foo +@{ +public: + operator ++ (); + operator ++ (int); + operator -- (); + operator -- (int); +@}; + +void +f (foo *f) +@{ + f++; // @i{call @code{f->operator++(int)}} + ++f; // @i{call @code{f->operator++()}} + f--; // @i{call @code{f->operator++(int)}} + --f; // @i{call @code{f->operator++()}} +@} +@end group +@end smallexample + +@item +In accordance with @sc{arm} section 10.1.1, ambiguities and dominance are now +handled properly. The rules described in section 10.1.1 are now fully +implemented. + +@end itemize + +@node Problems with debugging +@section Problems with debugging + +Two problems remain with regard to debugging: + +@itemize @bullet +@item +Debugging of anonymous structures on the IBM RS/6000 host is incorrect. + +@item +Symbol table size is overly large due to redundant symbol information; +this can make @code{gdb} coredump under certain circumstances. This +problem is not host-specific. +@end itemize + +@node Plans +@chapter Plans for Reno-2 + +The overall goal for the second phase of the @sc{gnu} C++ Renovation +Project is to bring @sc{gnu} C++ to a new level of reliability, quality, +and competitiveness. As particular elements of this strategy, we intend +to: + +@enumerate 0 +@item +Fully implement @sc{ansi} exception handling. + +@item +With the exception handling, add Runtime Type Identification +(@sc{rtti}), if the @sc{ansi} committee adopts it into the standard. + +@item +Bring the compiler into closer compliance with the @sc{arm} and the draft +@sc{ansi} standard, and document what points in the @sc{arm} we do not yet comply, +or agree, with. + +@item +Add further support for the @sc{dwarf} debugging format. + +@item +Finish the work to make the compiler compliant with @sc{arm} Section 12.6.2, +initializing base classes in declaration order, rather than in the order +that you specify them in a @var{mem-initializer} list. + +@item +Perform a full coverage analysis on the compiler, and weed out unused +code, for a gain in performance and a reduction in the size of the compiler. + +@item +Further improve the multiple inheritance implementation in the +compiler to make it cleaner and more complete. +@end enumerate + +@noindent +As always, we encourage you to make suggestions and ask questions about +@sc{gnu} C++ as a whole, so we can be sure that the end of this project +will bring a compiler that everyone will find essential for C++ and will +meet the needs of the world's C++ community. + +@include templates.texi + +@include gpcompare.texi + +@contents + +@bye diff --git a/gnu/usr.bin/cc/doc/rtl.texi b/gnu/usr.bin/cc/doc/rtl.texi new file mode 100644 index 0000000..6da63f2 --- /dev/null +++ b/gnu/usr.bin/cc/doc/rtl.texi @@ -0,0 +1,2800 @@ +@c Copyright (C) 1988, 1989, 1992, 1994 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node RTL +@chapter RTL Representation +@cindex RTL representation +@cindex representation of RTL +@cindex Register Transfer Language (RTL) + +Most of the work of the compiler is done on an intermediate representation +called register transfer language. In this language, the instructions to be +output are described, pretty much one by one, in an algebraic form that +describes what the instruction does. + +RTL is inspired by Lisp lists. It has both an internal form, made up of +structures that point at other structures, and a textual form that is used +in the machine description and in printed debugging dumps. The textual +form uses nested parentheses to indicate the pointers in the internal form. + +@menu +* RTL Objects:: Expressions vs vectors vs strings vs integers. +* Accessors:: Macros to access expression operands or vector elts. +* Flags:: Other flags in an RTL expression. +* Machine Modes:: Describing the size and format of a datum. +* Constants:: Expressions with constant values. +* Regs and Memory:: Expressions representing register contents or memory. +* Arithmetic:: Expressions representing arithmetic on other expressions. +* Comparisons:: Expressions representing comparison of expressions. +* Bit Fields:: Expressions representing bitfields in memory or reg. +* Conversions:: Extending, truncating, floating or fixing. +* RTL Declarations:: Declaring volatility, constancy, etc. +* Side Effects:: Expressions for storing in registers, etc. +* Incdec:: Embedded side-effects for autoincrement addressing. +* Assembler:: Representing @code{asm} with operands. +* Insns:: Expression types for entire insns. +* Calls:: RTL representation of function call insns. +* Sharing:: Some expressions are unique; others *must* be copied. +* Reading RTL:: Reading textual RTL from a file. +@end menu + +@node RTL Objects, Accessors, RTL, RTL +@section RTL Object Types +@cindex RTL object types + +@cindex RTL integers +@cindex RTL strings +@cindex RTL vectors +@cindex RTL expression +@cindex RTX (See RTL) +RTL uses five kinds of objects: expressions, integers, wide integers, +strings and vectors. Expressions are the most important ones. An RTL +expression (``RTX'', for short) is a C structure, but it is usually +referred to with a pointer; a type that is given the typedef name +@code{rtx}. + +An integer is simply an @code{int}; their written form uses decimal digits. +A wide integer is an integral object whose type is @code{HOST_WIDE_INT} +(@pxref{Config}); their written form uses decimal digits. + +A string is a sequence of characters. In core it is represented as a +@code{char *} in usual C fashion, and it is written in C syntax as well. +However, strings in RTL may never be null. If you write an empty string in +a machine description, it is represented in core as a null pointer rather +than as a pointer to a null character. In certain contexts, these null +pointers instead of strings are valid. Within RTL code, strings are most +commonly found inside @code{symbol_ref} expressions, but they appear in +other contexts in the RTL expressions that make up machine descriptions. + +A vector contains an arbitrary number of pointers to expressions. The +number of elements in the vector is explicitly present in the vector. +The written form of a vector consists of square brackets +(@samp{[@dots{}]}) surrounding the elements, in sequence and with +whitespace separating them. Vectors of length zero are not created; +null pointers are used instead. + +@cindex expression codes +@cindex codes, RTL expression +@findex GET_CODE +@findex PUT_CODE +Expressions are classified by @dfn{expression codes} (also called RTX +codes). The expression code is a name defined in @file{rtl.def}, which is +also (in upper case) a C enumeration constant. The possible expression +codes and their meanings are machine-independent. The code of an RTX can +be extracted with the macro @code{GET_CODE (@var{x})} and altered with +@code{PUT_CODE (@var{x}, @var{newcode})}. + +The expression code determines how many operands the expression contains, +and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell +by looking at an operand what kind of object it is. Instead, you must know +from its context---from the expression code of the containing expression. +For example, in an expression of code @code{subreg}, the first operand is +to be regarded as an expression and the second operand as an integer. In +an expression of code @code{plus}, there are two operands, both of which +are to be regarded as expressions. In a @code{symbol_ref} expression, +there is one operand, which is to be regarded as a string. + +Expressions are written as parentheses containing the name of the +expression type, its flags and machine mode if any, and then the operands +of the expression (separated by spaces). + +Expression code names in the @samp{md} file are written in lower case, +but when they appear in C code they are written in upper case. In this +manual, they are shown as follows: @code{const_int}. + +@cindex (nil) +@cindex nil +In a few contexts a null pointer is valid where an expression is normally +wanted. The written form of this is @code{(nil)}. + +@node Accessors, Flags, RTL Objects, RTL +@section Access to Operands +@cindex accessors +@cindex access to operands +@cindex operand access + +@cindex RTL format +For each expression type @file{rtl.def} specifies the number of +contained objects and their kinds, with four possibilities: @samp{e} for +expression (actually a pointer to an expression), @samp{i} for integer, +@samp{w} for wide integer, @samp{s} for string, and @samp{E} for vector +of expressions. The sequence of letters for an expression code is +called its @dfn{format}. Thus, the format of @code{subreg} is +@samp{ei}.@refill + +@cindex RTL format characters +A few other format characters are used occasionally: + +@table @code +@item u +@samp{u} is equivalent to @samp{e} except that it is printed differently +in debugging dumps. It is used for pointers to insns. + +@item n +@samp{n} is equivalent to @samp{i} except that it is printed differently +in debugging dumps. It is used for the line number or code number of a +@code{note} insn. + +@item S +@samp{S} indicates a string which is optional. In the RTL objects in +core, @samp{S} is equivalent to @samp{s}, but when the object is read, +from an @samp{md} file, the string value of this operand may be omitted. +An omitted string is taken to be the null string. + +@item V +@samp{V} indicates a vector which is optional. In the RTL objects in +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 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 +special ways by small parts of the compiler. +@end table + +There are macros to get the number of operands, the format, and the +class of an expression code: + +@table @code +@findex GET_RTX_LENGTH +@item GET_RTX_LENGTH (@var{code}) +Number of operands of an RTX of code @var{code}. + +@findex GET_RTX_FORMAT +@item GET_RTX_FORMAT (@var{code}) +The format of an RTX of code @var{code}, as a C string. + +@findex GET_RTX_CLASS +@cindex classes of RTX codes +@item GET_RTX_CLASS (@var{code}) +A single character representing the type of RTX operation that code +@var{code} performs. + +The following classes are defined: + +@table @code +@item o +An RTX code that represents an actual object, such as @code{reg} or +@code{mem}. @code{subreg} is not in this class. + +@item < +An RTX code for a comparison. The codes in this class are +@code{NE}, @code{EQ}, @code{LE}, @code{LT}, @code{GE}, @code{GT}, +@code{LEU}, @code{LTU}, @code{GEU}, @code{GTU}.@refill + +@item 1 +An RTX code for a unary arithmetic operation, such as @code{neg}. + +@item c +An RTX code for a commutative binary operation, other than @code{NE} +and @code{EQ} (which have class @samp{<}). + +@item 2 +An RTX code for a noncommutative binary operation, such as @code{MINUS}. + +@item b +An RTX code for a bitfield operation, either @code{ZERO_EXTRACT} or +@code{SIGN_EXTRACT}. + +@item 3 +An RTX code for other three input operations, such as @code{IF_THEN_ELSE}. + +@item i +An RTX code for a machine insn (@code{INSN}, @code{JUMP_INSN}, and +@code{CALL_INSN}).@refill + +@item m +An RTX code for something that matches in insns, such as @code{MATCH_DUP}. + +@item x +All other RTX codes. +@end table +@end table + +@findex XEXP +@findex XINT +@findex XWINT +@findex XSTR +Operands of expressions are accessed using the macros @code{XEXP}, +@code{XINT}, @code{XWINT} and @code{XSTR}. Each of these macros takes +two arguments: an expression-pointer (RTX) and an operand number +(counting from zero). Thus,@refill + +@example +XEXP (@var{x}, 2) +@end example + +@noindent +accesses operand 2 of expression @var{x}, as an expression. + +@example +XINT (@var{x}, 2) +@end example + +@noindent +accesses the same operand as an integer. @code{XSTR}, used in the same +fashion, would access it as a string. + +Any operand can be accessed as an integer, as an expression or as a string. +You must choose the correct method of access for the kind of value actually +stored in the operand. You would do this based on the expression code of +the containing expression. That is also how you would know how many +operands there are. + +For example, if @var{x} is a @code{subreg} expression, you know that it has +two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)} +and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you +would get the address of the expression operand but cast as an integer; +that might occasionally be useful, but it would be cleaner to write +@code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also +compile without error, and would return the second, integer operand cast as +an expression pointer, which would probably result in a crash when +accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either, +but this will access memory past the end of the expression with +unpredictable results.@refill + +Access to operands which are vectors is more complicated. You can use the +macro @code{XVEC} to get the vector-pointer itself, or the macros +@code{XVECEXP} and @code{XVECLEN} to access the elements and length of a +vector. + +@table @code +@findex XVEC +@item XVEC (@var{exp}, @var{idx}) +Access the vector-pointer which is operand number @var{idx} in @var{exp}. + +@findex XVECLEN +@item XVECLEN (@var{exp}, @var{idx}) +Access the length (number of elements) in the vector which is +in operand number @var{idx} in @var{exp}. This value is an @code{int}. + +@findex XVECEXP +@item XVECEXP (@var{exp}, @var{idx}, @var{eltnum}) +Access element number @var{eltnum} in the vector which is +in operand number @var{idx} in @var{exp}. This value is an RTX. + +It is up to you to make sure that @var{eltnum} is not negative +and is less than @code{XVECLEN (@var{exp}, @var{idx})}. +@end table + +All the macros defined in this section expand into lvalues and therefore +can be used to assign the operands, lengths and vector elements as well as +to access them. + +@node Flags, Machine Modes, Accessors, RTL +@section Flags in an RTL Expression +@cindex flags in RTL expression + +RTL expressions contain several flags (one-bit bitfields) that are used +in certain types of expression. Most often they are accessed with the +following macros: + +@table @code +@findex MEM_VOLATILE_P +@cindex @code{mem} and @samp{/v} +@cindex @code{volatil}, in @code{mem} +@cindex @samp{/v} in RTL dump +@item MEM_VOLATILE_P (@var{x}) +In @code{mem} expressions, nonzero for volatile memory references. +Stored in the @code{volatil} field and printed as @samp{/v}. + +@findex MEM_IN_STRUCT_P +@cindex @code{mem} and @samp{/s} +@cindex @code{in_struct}, in @code{mem} +@cindex @samp{/s} in RTL dump +@item MEM_IN_STRUCT_P (@var{x}) +In @code{mem} expressions, nonzero for reference to an entire +structure, union or array, or to a component of one. Zero for +references to a scalar variable or through a pointer to a scalar. +Stored in the @code{in_struct} field and printed as @samp{/s}. + +@findex REG_LOOP_TEST_P +@cindex @code{reg} and @samp{/s} +@cindex @code{in_struct}, in @code{reg} +@item REG_LOOP_TEST_P +In @code{reg} expressions, nonzero if this register's entire life is +contained in the exit test code for some loop. Stored in the +@code{in_struct} field and printed as @samp{/s}. + +@findex REG_USERVAR_P +@cindex @code{reg} and @samp{/v} +@cindex @code{volatil}, in @code{reg} +@item REG_USERVAR_P (@var{x}) +In a @code{reg}, nonzero if it corresponds to a variable present in +the user's source code. Zero for temporaries generated internally by +the compiler. Stored in the @code{volatil} field and printed as +@samp{/v}. + +@cindex @samp{/i} in RTL dump +@findex REG_FUNCTION_VALUE_P +@cindex @code{reg} and @samp{/i} +@cindex @code{integrated}, in @code{reg} +@item REG_FUNCTION_VALUE_P (@var{x}) +Nonzero in a @code{reg} if it is the place in which this function's +value is going to be returned. (This happens only in a hard +register.) Stored in the @code{integrated} field and printed as +@samp{/i}. + +The same hard register may be used also for collecting the values of +functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero +in this kind of use. + +@findex SUBREG_PROMOTED_VAR_P +@cindex @code{subreg} and @samp{/s} +@cindex @code{in_struct}, in @code{subreg} +@item SUBREG_PROMOTED_VAR_P +Nonzero in a @code{subreg} if it was made when accessing an object that +was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine +description macro (@pxref{Storage Layout}). In this case, the mode of +the @code{subreg} is the declared mode of the object and the mode of +@code{SUBREG_REG} is the mode of the register that holds the object. +Promoted variables are always either sign- or zero-extended to the wider +mode on every assignment. Stored in the @code{in_struct} field and +printed as @samp{/s}. + +@findex SUBREG_PROMOTED_UNSIGNED_P +@cindex @code{subreg} and @samp{/u} +@cindex @code{unchanging}, in @code{subreg} +@item SUBREG_PROMOTED_UNSIGNED_P +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}. + +@findex RTX_UNCHANGING_P +@cindex @code{reg} and @samp{/u} +@cindex @code{mem} and @samp{/u} +@cindex @code{unchanging}, in @code{reg} and @code{mem} +@cindex @samp{/u} in RTL dump +@item RTX_UNCHANGING_P (@var{x}) +Nonzero in a @code{reg} or @code{mem} if the value is not changed. +(This flag is not set for memory references via pointers to constants. +Such pointers only guarantee that the object will not be changed +explicitly by the current function. The object might be changed by +other functions or by aliasing.) Stored in the +@code{unchanging} field and printed as @samp{/u}. + +@findex RTX_INTEGRATED_P +@cindex @code{integrated}, in @code{insn} +@item RTX_INTEGRATED_P (@var{insn}) +Nonzero in an insn if it resulted from an in-line function call. +Stored in the @code{integrated} field and printed as @samp{/i}. This +may be deleted; nothing currently depends on it. + +@findex SYMBOL_REF_USED +@cindex @code{used}, in @code{symbol_ref} +@item SYMBOL_REF_USED (@var{x}) +In a @code{symbol_ref}, indicates that @var{x} has been used. This is +normally only used to ensure that @var{x} is only declared external +once. Stored in the @code{used} field. + +@findex SYMBOL_REF_FLAG +@cindex @code{symbol_ref} and @samp{/v} +@cindex @code{volatil}, in @code{symbol_ref} +@item SYMBOL_REF_FLAG (@var{x}) +In a @code{symbol_ref}, this is used as a flag for machine-specific purposes. +Stored in the @code{volatil} field and printed as @samp{/v}. + +@findex LABEL_OUTSIDE_LOOP_P +@cindex @code{label_ref} and @samp{/s} +@cindex @code{in_struct}, in @code{label_ref} +@item LABEL_OUTSIDE_LOOP_P +In @code{label_ref} expressions, nonzero if this is a reference to a +label that is outside the innermost loop containing the reference to the +label. Stored in the @code{in_struct} field and printed as @samp{/s}. + +@findex INSN_DELETED_P +@cindex @code{volatil}, in @code{insn} +@item INSN_DELETED_P (@var{insn}) +In an insn, nonzero if the insn has been deleted. Stored in the +@code{volatil} field and printed as @samp{/v}. + +@findex INSN_ANNULLED_BRANCH_P +@cindex @code{insn} and @samp{/u} +@cindex @code{unchanging}, in @code{insn} +@item INSN_ANNULLED_BRANCH_P (@var{insn}) +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}. + +@findex INSN_FROM_TARGET_P +@cindex @code{insn} and @samp{/s} +@cindex @code{in_struct}, in @code{insn} +@cindex @samp{/s} in RTL dump +@item INSN_FROM_TARGET_P (@var{insn}) +In an @code{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 should only be executed if +the branch is taken. For annulled branches with this bit clear, the +insn should be executed only if the branch is not taken. Stored in the +@code{in_struct} field and printed as @samp{/s}. + +@findex CONSTANT_POOL_ADDRESS_P +@cindex @code{symbol_ref} and @samp{/u} +@cindex @code{unchanging}, in @code{symbol_ref} +@item CONSTANT_POOL_ADDRESS_P (@var{x}) +Nonzero in a @code{symbol_ref} if it refers to part of the current +function's ``constants pool''. These are addresses close to the +beginning of the function, and GNU CC assumes they can be addressed +directly (perhaps with the help of base registers). Stored in the +@code{unchanging} field and printed as @samp{/u}. + +@findex CONST_CALL_P +@cindex @code{call_insn} and @samp{/u} +@cindex @code{unchanging}, in @code{call_insn} +@item CONST_CALL_P (@var{x}) +In a @code{call_insn}, indicates that the insn represents a call to a const +function. Stored in the @code{unchanging} field and printed as @samp{/u}. + +@findex LABEL_PRESERVE_P +@cindex @code{code_label} and @samp{/i} +@cindex @code{in_struct}, in @code{code_label} +@item LABEL_PRESERVE_P (@var{x}) +In a @code{code_label}, indicates that the label can never be deleted. +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 SCHED_GROUP_P +@cindex @code{insn} and @samp{/i} +@cindex @code{in_struct}, in @code{insn} +@item SCHED_GROUP_P (@var{insn}) +During instruction scheduling, in an 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 a @code{call_insn} may +not be separated from the @code{call_insn}. Stored in the @code{in_struct} +field and printed as @samp{/s}. +@end table + +These are the fields which the above macros refer to: + +@table @code +@findex used +@item used +Normally, this flag is used only momentarily, at the end of RTL +generation for a function, to count the number of times an expression +appears in insns. Expressions that appear more than once are copied, +according to the rules for shared structure (@pxref{Sharing}). + +In a @code{symbol_ref}, it indicates that an external declaration for +the symbol has already been written. + +In a @code{reg}, it is used by the leaf register renumbering code to ensure +that each register is only renumbered once. + +@findex volatil +@item volatil +This flag is used in @code{mem}, @code{symbol_ref} and @code{reg} +expressions and in insns. In RTL dump files, it is printed as +@samp{/v}. + +@cindex volatile memory references +In a @code{mem} expression, it is 1 if the memory reference is volatile. +Volatile memory references may not be deleted, reordered or combined. + +In a @code{symbol_ref} expression, it is used for machine-specific +purposes. + +In a @code{reg} expression, it is 1 if the value is a user-level variable. +0 indicates an internal compiler temporary. + +In an insn, 1 means the insn has been deleted. + +@findex in_struct +@item in_struct +In @code{mem} expressions, it is 1 if the memory datum referred to is +all or part of a structure or array; 0 if it is (or might be) a scalar +variable. A reference through a C pointer has 0 because the pointer +might point to a scalar variable. This information allows the compiler +to determine something about possible cases of aliasing. + +In an insn in the delay slot of a branch, 1 means that this insn is from +the target of the branch. + +During instruction scheduling, in an insn, 1 means that this insn must be +scheduled as part of a group together with the previous insn. + +In @code{reg} expressions, it is 1 if the register has its entire life +contained within the test expression of some loop. + +In @code{subreg} expressions, 1 means that the @code{subreg} is accessing +an object that has had its mode promoted from a wider mode. + +In @code{label_ref} expressions, 1 means that the referenced label is +outside the innermost loop containing the insn in which the @code{label_ref} +was found. + +In @code{code_label} expressions, it is 1 if the label may never be deleted. +This is used for labels which are the target of non-local gotos. + +In an RTL dump, this flag is represented as @samp{/s}. + +@findex unchanging +@item unchanging +In @code{reg} and @code{mem} expressions, 1 means +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 insn, 1 means that this is an annulling branch. + +In a @code{symbol_ref} expression, 1 means that this symbol addresses +something in the per-function constants pool. + +In a @code{call_insn}, 1 means that this instruction is a call to a +const function. + +In an RTL dump, this flag is represented as @samp{/u}. + +@findex integrated +@item integrated +In some kinds of expressions, including insns, this flag means the +rtl was produced by procedure integration. + +In a @code{reg} expression, this flag indicates the register +containing the value to be returned by the current function. On +machines that pass parameters in registers, the same register number +may be used for parameters as well, but this flag is not set on such +uses. +@end table + +@node Machine Modes, Constants, Flags, RTL +@section Machine Modes +@cindex machine modes + +@findex enum machine_mode +A machine mode describes a size of data object and the representation used +for it. In the C code, machine modes are represented by an enumeration +type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL +expression has room for a machine mode and so do certain kinds of tree +expressions (declarations and types, to be precise). + +In debugging dumps and machine descriptions, the machine mode of an RTL +expression is written after the expression code with a colon to separate +them. The letters @samp{mode} which appear at the end of each machine mode +name are omitted. For example, @code{(reg:SI 38)} is a @code{reg} +expression with machine mode @code{SImode}. If the mode is +@code{VOIDmode}, it is not written at all. + +Here is a table of machine modes. The term ``byte'' below refers to an +object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}). + +@table @code +@findex QImode +@item QImode +``Quarter-Integer'' mode represents a single byte treated as an integer. + +@findex HImode +@item HImode +``Half-Integer'' mode represents a two-byte integer. + +@findex PSImode +@item PSImode +``Partial Single Integer'' mode represents an integer which occupies +four bytes but which doesn't really use all four. On some machines, +this is the right mode to use for pointers. + +@findex SImode +@item SImode +``Single Integer'' mode represents a four-byte integer. + +@findex PDImode +@item PDImode +``Partial Double Integer'' mode represents an integer which occupies +eight bytes but which doesn't really use all eight. On some machines, +this is the right mode to use for certain pointers. + +@findex DImode +@item DImode +``Double Integer'' mode represents an eight-byte integer. + +@findex TImode +@item TImode +``Tetra Integer'' (?) mode represents a sixteen-byte integer. + +@findex SFmode +@item SFmode +``Single Floating'' mode represents a single-precision (four byte) floating +point number. + +@findex DFmode +@item DFmode +``Double Floating'' mode represents a double-precision (eight byte) floating +point number. + +@findex XFmode +@item XFmode +``Extended Floating'' mode represents a triple-precision (twelve byte) +floating point number. This mode is used for IEEE extended floating +point. + +@findex TFmode +@item TFmode +``Tetra Floating'' mode represents a quadruple-precision (sixteen byte) +floating point number. + +@findex CCmode +@item CCmode +``Condition Code'' mode represents the value of a condition code, which +is a machine-specific set of bits used to represent the result of a +comparison operation. Other machine-specific modes may also be used for +the condition code. These modes are not used on machines that use +@code{cc0} (see @pxref{Condition Code}). + +@findex BLKmode +@item BLKmode +``Block'' mode represents values that are aggregates to which none of +the other modes apply. In RTL, only memory references can have this mode, +and only if they appear in string-move or vector instructions. On machines +which have no such instructions, @code{BLKmode} will not appear in RTL. + +@findex VOIDmode +@item VOIDmode +Void mode means the absence of a mode or an unspecified mode. +For example, RTL expressions of code @code{const_int} have mode +@code{VOIDmode} because they can be taken to have whatever mode the context +requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by +the absence of any mode. + +@findex SCmode +@findex DCmode +@findex XCmode +@findex TCmode +@item SCmode, DCmode, XCmode, TCmode +These modes stand for a complex number represented as a pair of floating +point values. The floating point values are in @code{SFmode}, +@code{DFmode}, @code{XFmode}, and @code{TFmode}, respectively. + +@findex CQImode +@findex CHImode +@findex CSImode +@findex CDImode +@findex CTImode +@findex COImode +@item CQImode, CHImode, CSImode, CDImode, CTImode, COImode +These modes stand for a complex number represented as a pair of integer +values. The integer values are in @code{QImode}, @code{HImode}, +@code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode}, +respectively. +@end table + +The machine description defines @code{Pmode} as a C macro which expands +into the machine mode used for addresses. Normally this is the mode +whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines. + +The only modes which a machine description @i{must} support are +@code{QImode}, and the modes corresponding to @code{BITS_PER_WORD}, +@code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}. +The compiler will attempt to use @code{DImode} for 8-byte structures and +unions, but this can be prevented by overriding the definition of +@code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler +use @code{TImode} for 16-byte structures and unions. Likewise, you can +arrange for the C type @code{short int} to avoid using @code{HImode}. + +@cindex mode classes +Very few explicit references to machine modes remain in the compiler and +these few references will soon be removed. Instead, the machine modes +are divided into mode classes. These are represented by the enumeration +type @code{enum mode_class} defined in @file{machmode.h}. The possible +mode classes are: + +@table @code +@findex MODE_INT +@item MODE_INT +Integer modes. By default these are @code{QImode}, @code{HImode}, +@code{SImode}, @code{DImode}, and @code{TImode}. + +@findex MODE_PARTIAL_INT +@item MODE_PARTIAL_INT +The ``partial integer'' modes, @code{PSImode} and @code{PDImode}. + +@findex MODE_FLOAT +@item MODE_FLOAT +floating point modes. By default these are @code{SFmode}, @code{DFmode}, +@code{XFmode} and @code{TFmode}. + +@findex MODE_COMPLEX_INT +@item MODE_COMPLEX_INT +Complex integer modes. (These are not currently implemented). + +@findex MODE_COMPLEX_FLOAT +@item MODE_COMPLEX_FLOAT +Complex floating point modes. By default these are @code{SCmode}, +@code{DCmode}, @code{XCmode}, and @code{TCmode}. + +@findex MODE_FUNCTION +@item MODE_FUNCTION +Algol or Pascal function variables including a static chain. +(These are not currently implemented). + +@findex MODE_CC +@item MODE_CC +Modes representing condition code values. These are @code{CCmode} plus +any modes listed in the @code{EXTRA_CC_MODES} macro. @xref{Jump Patterns}, +also see @ref{Condition Code}. + +@findex MODE_RANDOM +@item MODE_RANDOM +This is a catchall mode class for modes which don't fit into the above +classes. Currently @code{VOIDmode} and @code{BLKmode} are in +@code{MODE_RANDOM}. +@end table + +Here are some C macros that relate to machine modes: + +@table @code +@findex GET_MODE +@item GET_MODE (@var{x}) +Returns the machine mode of the RTX @var{x}. + +@findex PUT_MODE +@item PUT_MODE (@var{x}, @var{newmode}) +Alters the machine mode of the RTX @var{x} to be @var{newmode}. + +@findex NUM_MACHINE_MODES +@item NUM_MACHINE_MODES +Stands for the number of machine modes available on the target +machine. This is one greater than the largest numeric value of any +machine mode. + +@findex GET_MODE_NAME +@item GET_MODE_NAME (@var{m}) +Returns the name of mode @var{m} as a string. + +@findex GET_MODE_CLASS +@item GET_MODE_CLASS (@var{m}) +Returns the mode class of mode @var{m}. + +@findex GET_MODE_WIDER_MODE +@item GET_MODE_WIDER_MODE (@var{m}) +Returns the next wider natural mode. For example, the expression +@code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}. + +@findex GET_MODE_SIZE +@item GET_MODE_SIZE (@var{m}) +Returns the size in bytes of a datum of mode @var{m}. + +@findex GET_MODE_BITSIZE +@item GET_MODE_BITSIZE (@var{m}) +Returns the size in bits of a datum of mode @var{m}. + +@findex GET_MODE_MASK +@item GET_MODE_MASK (@var{m}) +Returns a bitmask containing 1 for all bits in a word that fit within +mode @var{m}. This macro can only be used for modes whose bitsize is +less than or equal to @code{HOST_BITS_PER_INT}. + +@findex GET_MODE_ALIGNMENT +@item GET_MODE_ALIGNMENT (@var{m)}) +Return the required alignment, in bits, for an object of mode @var{m}. + +@findex GET_MODE_UNIT_SIZE +@item GET_MODE_UNIT_SIZE (@var{m}) +Returns the size in bytes of the subunits of a datum of mode @var{m}. +This is the same as @code{GET_MODE_SIZE} except in the case of complex +modes. For them, the unit size is the size of the real or imaginary +part. + +@findex GET_MODE_NUNITS +@item GET_MODE_NUNITS (@var{m}) +Returns the number of units contained in a mode, i.e., +@code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}. + +@findex GET_CLASS_NARROWEST_MODE +@item GET_CLASS_NARROWEST_MODE (@var{c}) +Returns the narrowest mode in mode class @var{c}. +@end table + +@findex byte_mode +@findex word_mode +The global variables @code{byte_mode} and @code{word_mode} contain modes +whose classes are @code{MODE_INT} and whose bitsizes are either +@code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit +machines, these are @code{QImode} and @code{SImode}, respectively. + +@node Constants, Regs and Memory, Machine Modes, RTL +@section Constant Expression Types +@cindex RTL constants +@cindex RTL constant expression types + +The simplest RTL expressions are those that represent constant values. + +@table @code +@findex const_int +@item (const_int @var{i}) +This type of expression represents the integer value @var{i}. @var{i} +is customarily accessed with the macro @code{INTVAL} as in +@code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}. + +@findex const0_rtx +@findex const1_rtx +@findex const2_rtx +@findex constm1_rtx +There is only one expression object for the integer value zero; it is +the value of the variable @code{const0_rtx}. Likewise, the only +expression for integer value one is found in @code{const1_rtx}, the only +expression for integer value two is found in @code{const2_rtx}, and the +only expression for integer value negative one is found in +@code{constm1_rtx}. Any attempt to create an expression of code +@code{const_int} and value zero, one, two or negative one will return +@code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or +@code{constm1_rtx} as appropriate.@refill + +@findex const_true_rtx +Similarly, there is only one object for the integer whose value is +@code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If +@code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and +@code{const1_rtx} will point to the same object. If +@code{STORE_FLAG_VALUE} is -1, @code{const_true_rtx} and +@code{constm1_rtx} will point to the same object.@refill + +@findex const_double +@item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{}) +Represents either a floating-point constant of mode @var{m} or an +integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT} +bits but small enough to fit within twice that number of bits (GNU CC +does not provide a mechanism to represent even larger constants). In +the latter case, @var{m} will be @code{VOIDmode}. + +@findex CONST_DOUBLE_MEM +@findex CONST_DOUBLE_CHAIN +@var{addr} is used to contain the @code{mem} expression that corresponds +to the location in memory that at which the constant can be found. If +it has not been allocated a memory location, but is on the chain of all +@code{const_double} expressions in this compilation (maintained using an +undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not +on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is +customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the +chain field via @code{CONST_DOUBLE_CHAIN}.@refill + +@findex CONST_DOUBLE_LOW +If @var{m} is @code{VOIDmode}, the bits of the value are stored in +@var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro +@code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}. + +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 +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 +@code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}). + +@findex CONST0_RTX +@findex CONST1_RTX +@findex CONST2_RTX +The macro @code{CONST0_RTX (@var{mode})} refers to an expression with +value 0 in mode @var{mode}. If mode @var{mode} is of mode class +@code{MODE_INT}, it returns @code{const0_rtx}. Otherwise, it returns a +@code{CONST_DOUBLE} expression in mode @var{mode}. Similarly, the macro +@code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in +mode @var{mode} and similarly for @code{CONST2_RTX}. + +@findex const_string +@item (const_string @var{str}) +Represents a constant string with value @var{str}. Currently this is +used only for insn attributes (@pxref{Insn Attributes}) since constant +strings in C are placed in memory. + +@findex symbol_ref +@item (symbol_ref:@var{mode} @var{symbol}) +Represents the value of an assembler label for data. @var{symbol} is +a string that describes the name of the assembler label. If it starts +with a @samp{*}, the label is the rest of @var{symbol} not including +the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed +with @samp{_}. + +The @code{symbol_ref} contains a mode, which is usually @code{Pmode}. +Usually that is the only mode for which a symbol is directly valid. + +@findex label_ref +@item (label_ref @var{label}) +Represents the value of an assembler label for code. It contains one +operand, an expression, which must be a @code{code_label} that appears +in the instruction sequence to identify the place where the label +should go. + +The reason for using a distinct expression type for code label +references is so that jump optimization can distinguish them. + +@item (const:@var{m} @var{exp}) +Represents a constant that is the result of an assembly-time +arithmetic computation. The operand, @var{exp}, is an expression that +contains only constants (@code{const_int}, @code{symbol_ref} and +@code{label_ref} expressions) combined with @code{plus} and +@code{minus}. However, not all combinations are valid, since the +assembler cannot do arbitrary arithmetic on relocatable symbols. + +@var{m} should be @code{Pmode}. + +@findex high +@item (high:@var{m} @var{exp}) +Represents the high-order bits of @var{exp}, usually a +@code{symbol_ref}. The number of bits is machine-dependent and is +normally the number of bits specified in an instruction that initializes +the high order bits of a register. It is used with @code{lo_sum} to +represent the typical two-instruction sequence used in RISC machines to +reference a global memory location. + +@var{m} should be @code{Pmode}. +@end table + +@node Regs and Memory, Arithmetic, Constants, RTL +@section Registers and Memory +@cindex RTL register expressions +@cindex RTL memory expressions + +Here are the RTL expression types for describing access to machine +registers and to main memory. + +@table @code +@findex reg +@cindex hard registers +@cindex pseudo registers +@item (reg:@var{m} @var{n}) +For small values of the integer @var{n} (those that are less than +@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine +register number @var{n}: a @dfn{hard register}. For larger values of +@var{n}, it stands for a temporary value or @dfn{pseudo register}. +The compiler's strategy is to generate code assuming an unlimited +number of such pseudo registers, and later convert them into hard +registers or into memory references. + +@var{m} is the machine mode of the reference. It is necessary because +machines can generally refer to each register in more than one mode. +For example, a register may contain a full word but there may be +instructions to refer to it as a half word or as a single byte, as +well as instructions to refer to it as a floating point number of +various precisions. + +Even for a register that the machine can access in only one mode, +the mode must always be specified. + +The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine +description, since the number of hard registers on the machine is an +invariant characteristic of the machine. Note, however, that not +all of the machine registers must be general registers. All the +machine registers that can be used for storage of data are given +hard register numbers, even those that can be used only in certain +instructions or can hold only certain types of data. + +A hard register may be accessed in various modes throughout one +function, but each pseudo register is given a natural mode +and is accessed only in that mode. When it is necessary to describe +an access to a pseudo register using a nonnatural mode, a @code{subreg} +expression is used. + +A @code{reg} expression with a machine mode that specifies more than +one word of data may actually stand for several consecutive registers. +If in addition the register number specifies a hardware register, then +it actually represents several consecutive hardware registers starting +with the specified one. + +Each pseudo register number used in a function's RTL code is +represented by a unique @code{reg} expression. + +@findex FIRST_VIRTUAL_REGISTER +@findex LAST_VIRTUAL_REGISTER +Some pseudo register numbers, those within the range of +@code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only +appear during the RTL generation phase and are eliminated before the +optimization phases. These represent locations in the stack frame that +cannot be determined until RTL generation for the function has been +completed. The following virtual register numbers are defined: + +@table @code +@findex VIRTUAL_INCOMING_ARGS_REGNUM +@item VIRTUAL_INCOMING_ARGS_REGNUM +This points to the first word of the incoming arguments passed on the +stack. Normally these arguments are placed there by the caller, but the +callee may have pushed some arguments that were previously passed in +registers. + +@cindex @code{FIRST_PARM_OFFSET} and virtual registers +@cindex @code{ARG_POINTER_REGNUM} and virtual registers +When RTL generation is complete, this virtual register is replaced +by the sum of the register given by @code{ARG_POINTER_REGNUM} and the +value of @code{FIRST_PARM_OFFSET}. + +@findex VIRTUAL_STACK_VARS_REGNUM +@cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers +@item VIRTUAL_STACK_VARS_REGNUM +If @code{FRAME_GROWS_DOWNWARD} is defined, this points to immediately +above the first variable on the stack. Otherwise, it points to the +first variable on the stack. + +@cindex @code{STARTING_FRAME_OFFSET} and virtual registers +@cindex @code{FRAME_POINTER_REGNUM} and virtual registers +@code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the +register given by @code{FRAME_POINTER_REGNUM} and the value +@code{STARTING_FRAME_OFFSET}. + +@findex VIRTUAL_STACK_DYNAMIC_REGNUM +@item VIRTUAL_STACK_DYNAMIC_REGNUM +This points to the location of dynamically allocated memory on the stack +immediately after the stack pointer has been adjusted by the amount of +memory desired. + +@cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers +@cindex @code{STACK_POINTER_REGNUM} and virtual registers +This virtual register is replaced by the sum of the register given by +@code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}. + +@findex VIRTUAL_OUTGOING_ARGS_REGNUM +@item VIRTUAL_OUTGOING_ARGS_REGNUM +This points to the location in the stack at which outgoing arguments +should be written when the stack is pre-pushed (arguments pushed using +push insns should always use @code{STACK_POINTER_REGNUM}). + +@cindex @code{STACK_POINTER_OFFSET} and virtual registers +This virtual register is replaced by the sum of the register given by +@code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}. +@end table + +@findex subreg +@item (subreg:@var{m} @var{reg} @var{wordnum}) +@code{subreg} expressions are used to refer to a register in a machine +mode other than its natural one, or to refer to one register of +a multi-word @code{reg} that actually refers to several registers. + +Each pseudo-register has a natural mode. If it is necessary to +operate on it in a different mode---for example, to perform a fullword +move instruction on a pseudo-register that contains a single +byte---the pseudo-register must be enclosed in a @code{subreg}. In +such a case, @var{wordnum} is zero. + +Usually @var{m} is at least as narrow as the mode of @var{reg}, in which +case it is restricting consideration to only the bits of @var{reg} that +are in @var{m}. + +Sometimes @var{m} is wider than the mode of @var{reg}. These +@code{subreg} expressions are often called @dfn{paradoxical}. They are +used in cases where we want to refer to an object in a wider mode but do +not care what value the additional bits have. The reload pass ensures +that paradoxical references are only made to hard registers. + +The other use of @code{subreg} is to extract the individual registers of +a multi-register value. Machine modes such as @code{DImode} and +@code{TImode} can indicate values longer than a word, values which +usually require two or more consecutive registers. To access one of the +registers, use a @code{subreg} with mode @code{SImode} and a +@var{wordnum} that says which register. + +Storing in a non-paradoxical @code{subreg} has undefined results for +bits belonging to the same word as the @code{subreg}. This laxity makes +it easier to generate efficient code for such instructions. To +represent an instruction that preserves all the bits outside of those in +the @code{subreg}, use @code{strict_low_part} around the @code{subreg}. + +@cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg} +The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says +that word number zero is the most significant part; otherwise, it is +the least significant part. + +@cindex combiner pass +@cindex reload pass +@cindex @code{subreg}, special reload handling +Between the combiner pass and the reload pass, it is possible to have a +paradoxical @code{subreg} which contains a @code{mem} instead of a +@code{reg} as its first operand. After the reload pass, it is also +possible to have a non-paradoxical @code{subreg} which contains a +@code{mem}; this usually occurs when the @code{mem} is a stack slot +which replaced a pseudo register. + +Note that it is not valid to access a @code{DFmode} value in @code{SFmode} +using a @code{subreg}. On some machines the most significant part of a +@code{DFmode} value does not have the same format as a single-precision +floating value. + +It is also not valid to access a single word of a multi-word value in a +hard register when less registers can hold the value than would be +expected from its size. For example, some 32-bit machines have +floating-point registers that can hold an entire @code{DFmode} value. +If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)} +would be invalid because there is no way to convert that reference to +a single machine register. The reload pass prevents @code{subreg} +expressions such as these from being formed. + +@findex SUBREG_REG +@findex SUBREG_WORD +The first operand of a @code{subreg} expression is customarily accessed +with the @code{SUBREG_REG} macro and the second operand is customarily +accessed with the @code{SUBREG_WORD} macro. + +@findex scratch +@cindex scratch operands +@item (scratch:@var{m}) +This represents a scratch register that will be required for the +execution of a single instruction and not used subsequently. It is +converted into a @code{reg} by either the local register allocator or +the reload pass. + +@code{scratch} is usually present inside a @code{clobber} operation +(@pxref{Side Effects}). + +@findex cc0 +@cindex condition code register +@item (cc0) +This refers to the machine's condition code register. It has no +operands and may not have a machine mode. There are two ways to use it: + +@itemize @bullet +@item +To stand for a complete set of condition code flags. This is best on +most machines, where each comparison sets the entire series of flags. + +With this technique, @code{(cc0)} may be validly used in only two +contexts: as the destination of an assignment (in test and compare +instructions) and in comparison operators comparing against zero +(@code{const_int} with value zero; that is to say, @code{const0_rtx}). + +@item +To stand for a single flag that is the result of a single condition. +This is useful on machines that have only a single flag bit, and in +which comparison instructions must specify the condition to test. + +With this technique, @code{(cc0)} may be validly used in only two +contexts: as the destination of an assignment (in test and compare +instructions) where the source is a comparison operator, and as the +first operand of @code{if_then_else} (in a conditional branch). +@end itemize + +@findex cc0_rtx +There is only one expression object of code @code{cc0}; it is the +value of the variable @code{cc0_rtx}. Any attempt to create an +expression of code @code{cc0} will return @code{cc0_rtx}. + +Instructions can set the condition code implicitly. On many machines, +nearly all instructions set the condition code based on the value that +they compute or store. It is not necessary to record these actions +explicitly in the RTL because the machine description includes a +prescription for recognizing the instructions that do so (by means of +the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only +instructions whose sole purpose is to set the condition code, and +instructions that use the condition code, need mention @code{(cc0)}. + +On some machines, the condition code register is given a register number +and a @code{reg} is used instead of @code{(cc0)}. This is usually the +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 +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 +that both performs the arithmetic and sets the condition code register +(which would not be @code{(cc0)} in this case). For examples, search +for @samp{addcc} and @samp{andcc} in @file{sparc.md}. + +@findex pc +@item (pc) +@cindex program counter +This represents the machine's program counter. It has no operands and +may not have a machine mode. @code{(pc)} may be validly used only in +certain specific contexts in jump instructions. + +@findex pc_rtx +There is only one expression object of code @code{pc}; it is the value +of the variable @code{pc_rtx}. Any attempt to create an expression of +code @code{pc} will return @code{pc_rtx}. + +All instructions that do not jump alter the program counter implicitly +by incrementing it, but there is no need to mention this in the RTL. + +@findex mem +@item (mem:@var{m} @var{addr}) +This RTX represents a reference to main memory at an address +represented by the expression @var{addr}. @var{m} specifies how large +a unit of memory is accessed. +@end table + +@node Arithmetic, Comparisons, Regs and Memory, RTL +@section RTL Expressions for Arithmetic +@cindex arithmetic, in RTL +@cindex math, in RTL +@cindex RTL expressions for arithmetic + +Unless otherwise specified, all the operands of arithmetic expressions +must be valid for mode @var{m}. An operand is valid for mode @var{m} +if it has mode @var{m}, or if it is a @code{const_int} or +@code{const_double} and @var{m} is a mode of class @code{MODE_INT}. + +For commutative binary operations, constants should be placed in the +second operand. + +@table @code +@findex plus +@cindex RTL addition +@cindex RTL sum +@item (plus:@var{m} @var{x} @var{y}) +Represents the sum of the values represented by @var{x} and @var{y} +carried out in machine mode @var{m}. + +@findex lo_sum +@item (lo_sum:@var{m} @var{x} @var{y}) +Like @code{plus}, except that it represents that sum of @var{x} and the +low-order bits of @var{y}. The number of low order bits is +machine-dependent but is normally the number of bits in a @code{Pmode} +item minus the number of bits set by the @code{high} code +(@pxref{Constants}). + +@var{m} should be @code{Pmode}. + +@findex minus +@cindex RTL subtraction +@cindex RTL difference +@item (minus:@var{m} @var{x} @var{y}) +Like @code{plus} but represents subtraction. + +@findex compare +@cindex RTL comparison +@item (compare:@var{m} @var{x} @var{y}) +Represents the result of subtracting @var{y} from @var{x} for purposes +of comparison. The result is computed without overflow, as if with +infinite precision. + +Of course, machines can't really subtract with infinite precision. +However, they can pretend to do so when only the sign of the +result will be used, which is the case when the result is stored +in the condition code. And that is the only way this kind of expression +may validly be used: as a value to be stored in the condition codes. + +The mode @var{m} is not related to the modes of @var{x} and @var{y}, +but instead is the mode of the condition code value. If @code{(cc0)} +is used, it is @code{VOIDmode}. Otherwise it is some mode in class +@code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}. + +Normally, @var{x} and @var{y} must have the same mode. Otherwise, +@code{compare} is valid only if the mode of @var{x} is in class +@code{MODE_INT} and @var{y} is a @code{const_int} or +@code{const_double} with mode @code{VOIDmode}. The mode of @var{x} +determines what mode the comparison is to be done in; thus it must not +be @code{VOIDmode}. + +If one of the operands is a constant, it should be placed in the +second operand and the comparison code adjusted as appropriate. + +A @code{compare} specifying two @code{VOIDmode} constants is not valid +since there is no way to know in what mode the comparison is to be +performed; the comparison must either be folded during the compilation +or the first operand must be loaded into a register while its mode is +still known. + +@findex neg +@item (neg:@var{m} @var{x}) +Represents the negation (subtraction from zero) of the value represented +by @var{x}, carried out in mode @var{m}. + +@findex mult +@cindex multiplication +@cindex product +@item (mult:@var{m} @var{x} @var{y}) +Represents the signed product of the values represented by @var{x} and +@var{y} carried out in machine mode @var{m}. + +Some machines support a multiplication that generates a product wider +than the operands. Write the pattern for this as + +@example +(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y})) +@end example + +where @var{m} is wider than the modes of @var{x} and @var{y}, which need +not be the same. + +Write patterns for unsigned widening multiplication similarly using +@code{zero_extend}. + +@findex div +@cindex division +@cindex signed division +@cindex quotient +@item (div:@var{m} @var{x} @var{y}) +Represents the quotient in signed division of @var{x} by @var{y}, +carried out in machine mode @var{m}. If @var{m} is a floating point +mode, it represents the exact quotient; otherwise, the integerized +quotient. + +Some machines have division instructions in which the operands and +quotient widths are not all the same; you should represent +such instructions using @code{truncate} and @code{sign_extend} as in, + +@example +(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y}))) +@end example + +@findex udiv +@cindex unsigned division +@cindex division +@item (udiv:@var{m} @var{x} @var{y}) +Like @code{div} but represents unsigned division. + +@findex mod +@findex umod +@cindex remainder +@cindex division +@item (mod:@var{m} @var{x} @var{y}) +@itemx (umod:@var{m} @var{x} @var{y}) +Like @code{div} and @code{udiv} but represent the remainder instead of +the quotient. + +@findex smin +@findex smax +@cindex signed minimum +@cindex signed maximum +@item (smin:@var{m} @var{x} @var{y}) +@itemx (smax:@var{m} @var{x} @var{y}) +Represents the smaller (for @code{smin}) or larger (for @code{smax}) of +@var{x} and @var{y}, interpreted as signed integers in mode @var{m}. + +@findex umin +@findex umax +@cindex unsigned minimum and maximum +@item (umin:@var{m} @var{x} @var{y}) +@itemx (umax:@var{m} @var{x} @var{y}) +Like @code{smin} and @code{smax}, but the values are interpreted as unsigned +integers. + +@findex not +@cindex complement, bitwise +@cindex bitwise complement +@item (not:@var{m} @var{x}) +Represents the bitwise complement of the value represented by @var{x}, +carried out in mode @var{m}, which must be a fixed-point machine mode. + +@findex and +@cindex logical-and, bitwise +@cindex bitwise logical-and +@item (and:@var{m} @var{x} @var{y}) +Represents the bitwise logical-and of the values represented by +@var{x} and @var{y}, carried out in machine mode @var{m}, which must be +a fixed-point machine mode. + +@findex ior +@cindex inclusive-or, bitwise +@cindex bitwise inclusive-or +@item (ior:@var{m} @var{x} @var{y}) +Represents the bitwise inclusive-or of the values represented by @var{x} +and @var{y}, carried out in machine mode @var{m}, which must be a +fixed-point mode. + +@findex xor +@cindex exclusive-or, bitwise +@cindex bitwise exclusive-or +@item (xor:@var{m} @var{x} @var{y}) +Represents the bitwise exclusive-or of the values represented by @var{x} +and @var{y}, carried out in machine mode @var{m}, which must be a +fixed-point mode. + +@findex ashift +@cindex left shift +@cindex shift +@cindex arithmetic shift +@item (ashift:@var{m} @var{x} @var{c}) +Represents the result of arithmetically shifting @var{x} left by @var{c} +places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c} +be a fixed-point mode or be a constant with mode @code{VOIDmode}; which +mode is determined by the mode called for in the machine description +entry for the left-shift instruction. For example, on the Vax, the mode +of @var{c} is @code{QImode} regardless of @var{m}. + +@findex lshiftrt +@cindex right shift +@findex ashiftrt +@item (lshiftrt:@var{m} @var{x} @var{c}) +@itemx (ashiftrt:@var{m} @var{x} @var{c}) +Like @code{ashift} but for right shift. Unlike the case for left shift, +these two operations are distinct. + +@findex rotate +@cindex rotate +@cindex left rotate +@findex rotatert +@cindex right rotate +@item (rotate:@var{m} @var{x} @var{c}) +@itemx (rotatert:@var{m} @var{x} @var{c}) +Similar but represent left and right rotate. If @var{c} is a constant, +use @code{rotate}. + +@findex abs +@cindex absolute value +@item (abs:@var{m} @var{x}) +Represents the absolute value of @var{x}, computed in mode @var{m}. + +@findex sqrt +@cindex square root +@item (sqrt:@var{m} @var{x}) +Represents the square root of @var{x}, computed in mode @var{m}. +Most often @var{m} will be a floating point mode. + +@findex ffs +@item (ffs:@var{m} @var{x}) +Represents one plus the index of the least significant 1-bit in +@var{x}, represented as an integer of mode @var{m}. (The value is +zero if @var{x} is zero.) The mode of @var{x} need not be @var{m}; +depending on the target machine, various mode combinations may be +valid. +@end table + +@node Comparisons, Bit Fields, Arithmetic, RTL +@section Comparison Operations +@cindex RTL comparison operations + +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. + +@cindex condition codes +There are two ways that comparison operations may be used. The +comparison operators may be used to compare the condition codes +@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such +a construct actually refers to the result of the preceding instruction +in which the condition codes were set. The instructing setting the +condition code must be adjacent to the instruction using the condition +code; only @code{note} insns may separate them. + +Alternatively, a comparison operation may directly compare two data +objects. The mode of the comparison is determined by the operands; they +must both be valid for a common machine mode. A comparison with both +operands constant would be invalid as the machine mode could not be +deduced from it, but such a comparison should never exist in RTL due to +constant folding. + +In the example above, if @code{(cc0)} were last set to +@code{(compare @var{x} @var{y})}, the comparison operation is +identical to @code{(eq @var{x} @var{y})}. Usually only one style +of comparisons is supported on a particular machine, but the combine +pass will try to merge the operations to produce the @code{eq} shown +in case it exists in the context of the particular insn involved. + +Inequality comparisons come in two flavors, signed and unsigned. Thus, +there are distinct expression codes @code{gt} and @code{gtu} for signed and +unsigned greater-than. These can produce different results for the same +pair of integer values: for example, 1 is signed greater-than -1 but not +unsigned greater-than, because -1 when regarded as unsigned is actually +@code{0xffffffff} which is greater than 1. + +The signed comparisons are also used for floating point values. Floating +point comparisons are distinguished by the machine modes of the operands. + +@table @code +@findex eq +@cindex equal +@item (eq:@var{m} @var{x} @var{y}) +1 if the values represented by @var{x} and @var{y} are equal, +otherwise 0. + +@findex ne +@cindex not equal +@item (ne:@var{m} @var{x} @var{y}) +1 if the values represented by @var{x} and @var{y} are not equal, +otherwise 0. + +@findex gt +@cindex greater than +@item (gt:@var{m} @var{x} @var{y}) +1 if the @var{x} is greater than @var{y}. If they are fixed-point, +the comparison is done in a signed sense. + +@findex gtu +@cindex greater than +@cindex unsigned greater than +@item (gtu:@var{m} @var{x} @var{y}) +Like @code{gt} but does unsigned comparison, on fixed-point numbers only. + +@findex lt +@cindex less than +@findex ltu +@cindex unsigned less than +@item (lt:@var{m} @var{x} @var{y}) +@itemx (ltu:@var{m} @var{x} @var{y}) +Like @code{gt} and @code{gtu} but test for ``less than''. + +@findex ge +@cindex greater than +@findex geu +@cindex unsigned greater than +@item (ge:@var{m} @var{x} @var{y}) +@itemx (geu:@var{m} @var{x} @var{y}) +Like @code{gt} and @code{gtu} but test for ``greater than or equal''. + +@findex le +@cindex less than or equal +@findex leu +@cindex unsigned less than +@item (le:@var{m} @var{x} @var{y}) +@itemx (leu:@var{m} @var{x} @var{y}) +Like @code{gt} and @code{gtu} but test for ``less than or equal''. + +@findex if_then_else +@item (if_then_else @var{cond} @var{then} @var{else}) +This is not a comparison operation but is listed here because it is +always used in conjunction with a comparison operation. To be +precise, @var{cond} is a comparison expression. This expression +represents a choice, according to @var{cond}, between the value +represented by @var{then} and the one represented by @var{else}. + +On most machines, @code{if_then_else} expressions are valid only +to express conditional jumps. + +@findex cond +@item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default}) +Similar to @code{if_then_else}, but more general. Each of @var{test1}, +@var{test2}, @dots{} is performed in turn. The result of this expression is +the @var{value} corresponding to the first non-zero test, or @var{default} if +none of the tests are non-zero expressions. + +This is currently not valid for instruction patterns and is supported only +for insn attributes. @xref{Insn Attributes}. +@end table + +@node Bit Fields, Conversions, Comparisons, RTL +@section Bit Fields +@cindex bit fields + +Special expression codes exist to represent bitfield instructions. +These types of expressions are lvalues in RTL; they may appear +on the left side of an assignment, indicating insertion of a value +into the specified bit field. + +@table @code +@findex sign_extract +@cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract} +@item (sign_extract:@var{m} @var{loc} @var{size} @var{pos}) +This represents a reference to a sign-extended bit field contained or +starting in @var{loc} (a memory or register reference). The bit field +is @var{size} bits wide and starts at bit @var{pos}. The compilation +option @code{BITS_BIG_ENDIAN} says which end of the memory unit +@var{pos} counts from. + +If @var{loc} is in memory, its mode must be a single-byte integer mode. +If @var{loc} is in a register, the mode to use is specified by the +operand of the @code{insv} or @code{extv} pattern +(@pxref{Standard Names}) and is usually a full-word integer mode. + +The mode of @var{pos} is machine-specific and is also specified +in the @code{insv} or @code{extv} pattern. + +The mode @var{m} is the same as the mode that would be used for +@var{loc} if it were a register. + +@findex zero_extract +@item (zero_extract:@var{m} @var{loc} @var{size} @var{pos}) +Like @code{sign_extract} but refers to an unsigned or zero-extended +bit field. The same sequence of bits are extracted, but they +are filled to an entire word with zeros instead of by sign-extension. +@end table + +@node Conversions, RTL Declarations, Bit Fields, RTL +@section Conversions +@cindex conversions +@cindex machine mode conversions + +All conversions between machine modes must be represented by +explicit conversion operations. For example, an expression +which is the sum of a byte and a full word cannot be written as +@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus} +operation requires two operands of the same machine mode. +Therefore, the byte-sized operand is enclosed in a conversion +operation, as in + +@example +(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80)) +@end example + +The conversion operation is not a mere placeholder, because there +may be more than one way of converting from a given starting mode +to the desired final mode. The conversion operation code says how +to do it. + +For all conversion operations, @var{x} must not be @code{VOIDmode} +because the mode in which to do the conversion would not be known. +The conversion must either be done at compile-time or @var{x} +must be placed into a register. + +@table @code +@findex sign_extend +@item (sign_extend:@var{m} @var{x}) +Represents the result of sign-extending the value @var{x} +to machine mode @var{m}. @var{m} must be a fixed-point mode +and @var{x} a fixed-point value of a mode narrower than @var{m}. + +@findex zero_extend +@item (zero_extend:@var{m} @var{x}) +Represents the result of zero-extending the value @var{x} +to machine mode @var{m}. @var{m} must be a fixed-point mode +and @var{x} a fixed-point value of a mode narrower than @var{m}. + +@findex float_extend +@item (float_extend:@var{m} @var{x}) +Represents the result of extending the value @var{x} +to machine mode @var{m}. @var{m} must be a floating point mode +and @var{x} a floating point value of a mode narrower than @var{m}. + +@findex truncate +@item (truncate:@var{m} @var{x}) +Represents the result of truncating the value @var{x} +to machine mode @var{m}. @var{m} must be a fixed-point mode +and @var{x} a fixed-point value of a mode wider than @var{m}. + +@findex float_truncate +@item (float_truncate:@var{m} @var{x}) +Represents the result of truncating the value @var{x} +to machine mode @var{m}. @var{m} must be a floating point mode +and @var{x} a floating point value of a mode wider than @var{m}. + +@findex float +@item (float:@var{m} @var{x}) +Represents the result of converting fixed point value @var{x}, +regarded as signed, to floating point mode @var{m}. + +@findex unsigned_float +@item (unsigned_float:@var{m} @var{x}) +Represents the result of converting fixed point value @var{x}, +regarded as unsigned, to floating point mode @var{m}. + +@findex fix +@item (fix:@var{m} @var{x}) +When @var{m} is a fixed point mode, represents the result of +converting floating point value @var{x} to mode @var{m}, regarded as +signed. How rounding is done is not specified, so this operation may +be used validly in compiling C code only for integer-valued operands. + +@findex unsigned_fix +@item (unsigned_fix:@var{m} @var{x}) +Represents the result of converting floating point value @var{x} to +fixed point mode @var{m}, regarded as unsigned. How rounding is done +is not specified. + +@findex fix +@item (fix:@var{m} @var{x}) +When @var{m} is a floating point mode, represents the result of +converting floating point value @var{x} (valid for mode @var{m}) to an +integer, still represented in floating point mode @var{m}, by rounding +towards zero. +@end table + +@node RTL Declarations, Side Effects, Conversions, RTL +@section Declarations +@cindex RTL declarations +@cindex declarations, RTL + +Declaration expression codes do not represent arithmetic operations +but rather state assertions about their operands. + +@table @code +@findex strict_low_part +@cindex @code{subreg}, in @code{strict_low_part} +@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0)) +This expression code is used in only one context: as the destination operand of a +@code{set} expression. In addition, the operand of this expression +must be a non-paradoxical @code{subreg} expression. + +The presence of @code{strict_low_part} says that the part of the +register which is meaningful in mode @var{n}, but is not part of +mode @var{m}, is not to be altered. Normally, an assignment to such +a subreg is allowed to have undefined effects on the rest of the +register when @var{m} is less than a word. +@end table + +@node Side Effects, Incdec, RTL Declarations, RTL +@section Side Effect Expressions +@cindex RTL side effect expressions + +The expression codes described so far represent values, not actions. +But machine instructions never produce values; they are meaningful +only for their side effects on the state of the machine. Special +expression codes are used to represent side effects. + +The body of an instruction is always one of these side effect codes; +the codes described above, which represent values, appear only as +the operands of these. + +@table @code +@findex set +@item (set @var{lval} @var{x}) +Represents the action of storing the value of @var{x} into the place +represented by @var{lval}. @var{lval} must be an expression +representing a place that can be stored in: @code{reg} (or +@code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or +@code{cc0}.@refill + +If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a +machine mode; then @var{x} must be valid for that mode.@refill + +If @var{lval} is a @code{reg} whose machine mode is less than the full +width of the register, then it means that the part of the register +specified by the machine mode is given the specified value and the +rest of the register receives an undefined value. Likewise, if +@var{lval} is a @code{subreg} whose machine mode is narrower than +the mode of the register, the rest of the register can be changed in +an undefined way. + +If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the +part of the register specified by the machine mode of the +@code{subreg} is given the value @var{x} and the rest of the register +is not changed.@refill + +If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may +be either a @code{compare} expression or a value that may have any mode. +The latter case represents a ``test'' instruction. The expression +@code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to +@code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}. +Use the former expression to save space during the compilation. + +@cindex jump instructions and @code{set} +@cindex @code{if_then_else} usage +If @var{lval} is @code{(pc)}, we have a jump instruction, and the +possibilities for @var{x} are very limited. It may be a +@code{label_ref} expression (unconditional jump). It may be an +@code{if_then_else} (conditional jump), in which case either the +second or the third operand must be @code{(pc)} (for the case which +does not jump) and the other of the two must be a @code{label_ref} +(for the case which does jump). @var{x} may also be a @code{mem} or +@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a +@code{mem}; these unusual patterns are used to represent jumps through +branch tables.@refill + +If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of +@var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be +valid for the mode of @var{lval}. + +@findex SET_DEST +@findex SET_SRC +@var{lval} is customarily accessed with the @code{SET_DEST} macro and +@var{x} with the @code{SET_SRC} macro. + +@findex return +@item (return) +As the sole expression in a pattern, represents a return from the +current function, on machines where this can be done with one +instruction, such as Vaxes. On machines where a multi-instruction +``epilogue'' must be executed in order to return from the function, +returning is done by jumping to a label which precedes the epilogue, and +the @code{return} expression code is never used. + +Inside an @code{if_then_else} expression, represents the value to be +placed in @code{pc} to return to the caller. + +Note that an insn pattern of @code{(return)} is logically equivalent to +@code{(set (pc) (return))}, but the latter form is never used. + +@findex call +@item (call @var{function} @var{nargs}) +Represents a function call. @var{function} is a @code{mem} expression +whose address is the address of the function to be called. +@var{nargs} is an expression which can be used for two purposes: on +some machines it represents the number of bytes of stack argument; on +others, it represents the number of argument registers. + +Each machine has a standard machine mode which @var{function} must +have. The machine description defines macro @code{FUNCTION_MODE} to +expand into the requisite mode name. The purpose of this mode is to +specify what kind of addressing is allowed, on machines where the +allowed kinds of addressing depend on the machine mode being +addressed. + +@findex clobber +@item (clobber @var{x}) +Represents the storing or possible storing of an unpredictable, +undescribed value into @var{x}, which must be a @code{reg}, +@code{scratch} or @code{mem} expression. + +One place this is used is in string instructions that store standard +values into particular hard registers. It may not be worth the +trouble to describe the values that are stored, but it is essential to +inform the compiler that the registers will be altered, lest it +attempt to keep data in them across the string instruction. + +If @var{x} is @code{(mem:BLK (const_int 0))}, it means that all memory +locations must be presumed clobbered. + +Note that the machine description classifies certain hard registers as +``call-clobbered''. All function call instructions are assumed by +default to clobber these registers, so there is no need to use +@code{clobber} expressions to indicate this fact. Also, each function +call is assumed to have the potential to alter any memory location, +unless the function is declared @code{const}. + +If the last group of expressions in a @code{parallel} are each a +@code{clobber} expression whose arguments are @code{reg} or +@code{match_scratch} (@pxref{RTL Template}) expressions, the combiner +phase can add the appropriate @code{clobber} expressions to an insn it +has constructed when doing so will cause a pattern to be matched. + +This feature can be used, for example, on a machine that whose multiply +and add instructions don't use an MQ register but which has an +add-accumulate instruction that does clobber the MQ register. Similarly, +a combined instruction might require a temporary register while the +constituent instructions might not. + +When a @code{clobber} expression for a register appears inside a +@code{parallel} with other side effects, the register allocator +guarantees that the register is unoccupied both before and after that +insn. However, the reload phase may allocate a register used for one of +the inputs unless the @samp{&} constraint is specified for the selected +alternative (@pxref{Modifiers}). You can clobber either a specific hard +register, a pseudo register, or a @code{scratch} expression; in the +latter two cases, GNU CC will allocate a hard register that is available +there for use as a temporary. + +For instructions that require a temporary register, you should use +@code{scratch} instead of a pseudo-register because this will allow the +combiner phase to add the @code{clobber} when required. You do this by +coding (@code{clobber} (@code{match_scratch} @dots{})). If you do +clobber a pseudo register, use one which appears nowhere else---generate +a new one each time. Otherwise, you may confuse CSE. + +There is one other known use for clobbering a pseudo register in a +@code{parallel}: when one of the input operands of the insn is also +clobbered by the insn. In this case, using the same pseudo register in +the clobber and elsewhere in the insn produces the expected results. + +@findex use +@item (use @var{x}) +Represents the use of the value of @var{x}. It indicates that the +value in @var{x} at this point in the program is needed, even though +it may not be apparent why this is so. Therefore, the compiler will +not attempt to delete previous instructions whose only effect is to +store a value in @var{x}. @var{x} must be a @code{reg} expression. + +During the delayed branch scheduling phase, @var{x} may be an insn. +This indicates that @var{x} previously was located at this place in the +code and its data dependencies need to be taken into account. These +@code{use} insns will be deleted before the delayed branch scheduling +phase exits. + +@findex parallel +@item (parallel [@var{x0} @var{x1} @dots{}]) +Represents several side effects performed in parallel. The square +brackets stand for a vector; the operand of @code{parallel} is a +vector of expressions. @var{x0}, @var{x1} and so on are individual +side effect expressions---expressions of code @code{set}, @code{call}, +@code{return}, @code{clobber} or @code{use}.@refill + +``In parallel'' means that first all the values used in the individual +side-effects are computed, and second all the actual side-effects are +performed. For example, + +@example +(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1))) + (set (mem:SI (reg:SI 1)) (reg:SI 1))]) +@end example + +@noindent +says unambiguously that the values of hard register 1 and the memory +location addressed by it are interchanged. In both places where +@code{(reg:SI 1)} appears as a memory address it refers to the value +in register 1 @emph{before} the execution of the insn. + +It follows that it is @emph{incorrect} to use @code{parallel} and +expect the result of one @code{set} to be available for the next one. +For example, people sometimes attempt to represent a jump-if-zero +instruction this way: + +@example +(parallel [(set (cc0) (reg:SI 34)) + (set (pc) (if_then_else + (eq (cc0) (const_int 0)) + (label_ref @dots{}) + (pc)))]) +@end example + +@noindent +But this is incorrect, because it says that the jump condition depends +on the condition code value @emph{before} this instruction, not on the +new value that is set by this instruction. + +@cindex peephole optimization, RTL representation +Peephole optimization, which takes place together with final assembly +code output, can produce insns whose patterns consist of a @code{parallel} +whose elements are the operands needed to output the resulting +assembler code---often @code{reg}, @code{mem} or constant expressions. +This would not be well-formed RTL at any other stage in compilation, +but it is ok then because no further optimization remains to be done. +However, the definition of the macro @code{NOTICE_UPDATE_CC}, if +any, must deal with such insns if you define any peephole optimizations. + +@findex sequence +@item (sequence [@var{insns} @dots{}]) +Represents a sequence of insns. Each of the @var{insns} that appears +in the vector is suitable for appearing in the chain of insns, so it +must be an @code{insn}, @code{jump_insn}, @code{call_insn}, +@code{code_label}, @code{barrier} or @code{note}. + +A @code{sequence} RTX is never placed in an actual insn during RTL +generation. It represents the sequence of insns that result from a +@code{define_expand} @emph{before} those insns are passed to +@code{emit_insn} to insert them in the chain of insns. When actually +inserted, the individual sub-insns are separated out and the +@code{sequence} is forgotten. + +After delay-slot scheduling is completed, an insn and all the insns that +reside in its delay slots are grouped together into a @code{sequence}. +The insn requiring the delay slot is the first insn in the vector; +subsequent insns are to be placed in the delay slot. + +@code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to +indicate that a branch insn should be used that will conditionally annul +the effect of the insns in the delay slots. In such a case, +@code{INSN_FROM_TARGET_P} indicates that the insn is from the target of +the branch and should be executed only if the branch is taken; otherwise +the insn should be executed only if the branch is not taken. +@xref{Delay Slots}. +@end table + +These expression codes appear in place of a side effect, as the body of +an insn, though strictly speaking they do not always describe side +effects as such: + +@table @code +@findex asm_input +@item (asm_input @var{s}) +Represents literal assembler code as described by the string @var{s}. + +@findex unspec +@findex unspec_volatile +@item (unspec [@var{operands} @dots{}] @var{index}) +@itemx (unspec_volatile [@var{operands} @dots{}] @var{index}) +Represents a machine-specific operation on @var{operands}. @var{index} +selects between multiple machine-specific operations. +@code{unspec_volatile} is used for volatile operations and operations +that may trap; @code{unspec} is used for other operations. + +These codes may appear inside a @code{pattern} of an +insn, inside a @code{parallel}, or inside an expression. + +@findex addr_vec +@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}]) +Represents a table of jump addresses. The vector elements @var{lr0}, +etc., are @code{label_ref} expressions. The mode @var{m} specifies +how much space is given to each address; normally @var{m} would be +@code{Pmode}. + +@findex addr_diff_vec +@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}]) +Represents a table of jump addresses expressed as offsets from +@var{base}. The vector elements @var{lr0}, etc., are @code{label_ref} +expressions and so is @var{base}. The mode @var{m} specifies how much +space is given to each address-difference.@refill +@end table + +@node Incdec, Assembler, Side Effects, RTL +@section Embedded Side-Effects on Addresses +@cindex RTL preincrement +@cindex RTL postincrement +@cindex RTL predecrement +@cindex RTL postdecrement + +Four special side-effect expression codes appear as memory addresses. + +@table @code +@findex pre_dec +@item (pre_dec:@var{m} @var{x}) +Represents the side effect of decrementing @var{x} by a standard +amount and represents also the value that @var{x} has after being +decremented. @var{x} must be a @code{reg} or @code{mem}, but most +machines allow only a @code{reg}. @var{m} must be the machine mode +for pointers on the machine in use. The amount @var{x} is decremented +by is the length in bytes of the machine mode of the containing memory +reference of which this expression serves as the address. Here is an +example of its use:@refill + +@example +(mem:DF (pre_dec:SI (reg:SI 39))) +@end example + +@noindent +This says to decrement pseudo register 39 by the length of a @code{DFmode} +value and use the result to address a @code{DFmode} value. + +@findex pre_inc +@item (pre_inc:@var{m} @var{x}) +Similar, but specifies incrementing @var{x} instead of decrementing it. + +@findex post_dec +@item (post_dec:@var{m} @var{x}) +Represents the same side effect as @code{pre_dec} but a different +value. The value represented here is the value @var{x} has @i{before} +being decremented. + +@findex post_inc +@item (post_inc:@var{m} @var{x}) +Similar, but specifies incrementing @var{x} instead of decrementing it. +@end table + +These embedded side effect expressions must be used with care. Instruction +patterns may not use them. Until the @samp{flow} pass of the compiler, +they may occur only to represent pushes onto the stack. The @samp{flow} +pass finds cases where registers are incremented or decremented in one +instruction and used as an address shortly before or after; these cases are +then transformed to use pre- or post-increment or -decrement. + +If a register used as the operand of these expressions is used in +another address in an insn, the original value of the register is used. +Uses of the register outside of an address are not permitted within the +same insn as a use in an embedded side effect expression because such +insns behave differently on different machines and hence must be treated +as ambiguous and disallowed. + +An instruction that can be represented with an embedded side effect +could also be represented using @code{parallel} containing an additional +@code{set} to describe how the address register is altered. This is not +done because machines that allow these operations at all typically +allow them wherever a memory address is called for. Describing them as +additional parallel stores would require doubling the number of entries +in the machine description. + +@node Assembler, Insns, Incdec, RTL +@section Assembler Instructions as Expressions +@cindex assembler instructions in RTL + +@cindex @code{asm_operands}, usage +The RTX code @code{asm_operands} represents a value produced by a +user-specified assembler instruction. It is used to represent +an @code{asm} statement with arguments. An @code{asm} statement with +a single output operand, like this: + +@smallexample +asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z)); +@end smallexample + +@noindent +is represented using a single @code{asm_operands} RTX which represents +the value that is stored in @code{outputvar}: + +@smallexample +(set @var{rtx-for-outputvar} + (asm_operands "foo %1,%2,%0" "a" 0 + [@var{rtx-for-addition-result} @var{rtx-for-*z}] + [(asm_input:@var{m1} "g") + (asm_input:@var{m2} "di")])) +@end smallexample + +@noindent +Here the operands of the @code{asm_operands} RTX are the assembler +template string, the output-operand's constraint, the index-number of the +output operand among the output operands specified, a vector of input +operand RTX's, and a vector of input-operand modes and constraints. The +mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of +@code{*z}. + +When an @code{asm} statement has multiple output values, its insn has +several such @code{set} RTX's inside of a @code{parallel}. Each @code{set} +contains a @code{asm_operands}; all of these share the same assembler +template and vectors, but each contains the constraint for the respective +output operand. They are also distinguished by the output-operand index +number, which is 0, 1, @dots{} for successive output operands. + +@node Insns, Calls, Assembler, RTL +@section Insns +@cindex insns + +The RTL representation of the code for a function is a doubly-linked +chain of objects called @dfn{insns}. Insns are expressions with +special codes that are used for no other purpose. Some insns are +actual instructions; others represent dispatch tables for @code{switch} +statements; others represent labels to jump to or various sorts of +declarative information. + +In addition to its own specific data, each insn must have a unique +id-number that distinguishes it from all other insns in the current +function (after delayed branch scheduling, copies of an insn with the +same id-number may be present in multiple places in a function, but +these copies will always be identical and will only appear inside a +@code{sequence}), and chain pointers to the preceding and following +insns. These three fields occupy the same position in every insn, +independent of the expression code of the insn. They could be accessed +with @code{XEXP} and @code{XINT}, but instead three special macros are +always used: + +@table @code +@findex INSN_UID +@item INSN_UID (@var{i}) +Accesses the unique id of insn @var{i}. + +@findex PREV_INSN +@item PREV_INSN (@var{i}) +Accesses the chain pointer to the insn preceding @var{i}. +If @var{i} is the first insn, this is a null pointer. + +@findex NEXT_INSN +@item NEXT_INSN (@var{i}) +Accesses the chain pointer to the insn following @var{i}. +If @var{i} is the last insn, this is a null pointer. +@end table + +@findex get_insns +@findex get_last_insn +The first insn in the chain is obtained by calling @code{get_insns}; the +last insn is the result of calling @code{get_last_insn}. Within the +chain delimited by these insns, the @code{NEXT_INSN} and +@code{PREV_INSN} pointers must always correspond: if @var{insn} is not +the first insn, + +@example +NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn} +@end example + +@noindent +is always true and if @var{insn} is not the last insn, + +@example +PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn} +@end example + +@noindent +is always true. + +After delay slot scheduling, some of the insns in the chain might be +@code{sequence} expressions, which contain a vector of insns. The value +of @code{NEXT_INSN} in all but the last of these insns is the next insn +in the vector; the value of @code{NEXT_INSN} of the last insn in the vector +is the same as the value of @code{NEXT_INSN} for the @code{sequence} in +which it is contained. Similar rules apply for @code{PREV_INSN}. + +This means that the above invariants are not necessarily true for insns +inside @code{sequence} expressions. Specifically, if @var{insn} is the +first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))} +is the insn containing the @code{sequence} expression, as is the value +of @code{PREV_INSN (NEXT_INSN (@var{insn}))} is @var{insn} is the last +insn in the @code{sequence} expression. You can use these expressions +to find the containing @code{sequence} expression.@refill + +Every insn has one of the following six expression codes: + +@table @code +@findex insn +@item insn +The expression code @code{insn} is used for instructions that do not jump +and do not do function calls. @code{sequence} expressions are always +contained in insns with code @code{insn} even if one of those insns +should jump or do function calls. + +Insns with code @code{insn} have four additional fields beyond the three +mandatory ones listed above. These four are described in a table below. + +@findex jump_insn +@item jump_insn +The expression code @code{jump_insn} is used for instructions that may +jump (or, more generally, may contain @code{label_ref} expressions). If +there is an instruction to return from the current function, it is +recorded as a @code{jump_insn}. + +@findex JUMP_LABEL +@code{jump_insn} insns have the same extra fields as @code{insn} insns, +accessed in the same way and in addition contain a field +@code{JUMP_LABEL} which is defined once jump optimization has completed. + +For simple conditional and unconditional jumps, this field contains the +@code{code_label} to which this insn will (possibly conditionally) +branch. In a more complex jump, @code{JUMP_LABEL} records one of the +labels that the insn refers to; the only way to find the others +is to scan the entire body of the insn. + +Return insns count as jumps, but since they do not refer to any labels, +they have zero in the @code{JUMP_LABEL} field. + +@findex call_insn +@item call_insn +The expression code @code{call_insn} is used for instructions that may do +function calls. It is important to distinguish these instructions because +they imply that certain registers and memory locations may be altered +unpredictably. + +@findex CALL_INSN_FUNCTION_USAGE +@code{call_insn} insns have the same extra fields as @code{insn} insns, +accessed in the same way and in addition contain a field +@code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of +@code{expr_list} expressions) containing @code{use} and @code{clobber} +expressions that denote hard registers used or clobbered by the called +function. A register specified in a @code{clobber} in this list is +modified @emph{after} the execution of the @code{call_insn}, while a +register in a @code{clobber} in the body of the @code{call_insn} is +clobbered before the insn completes execution. @code{clobber} +expressions in this list augment registers specified in +@code{CALL_USED_REGISTERS} (@pxref{Register Basics}). + +@findex code_label +@findex CODE_LABEL_NUMBER +@item code_label +A @code{code_label} insn represents a label that a jump insn can jump +to. It contains two special fields of data in addition to the three +standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label +number}, a number that identifies this label uniquely among all the +labels in the compilation (not just in the current function). +Ultimately, the label is represented in the assembler output as an +assembler label, usually of the form @samp{L@var{n}} where @var{n} is +the label number. + +When a @code{code_label} appears in an RTL expression, it normally +appears within a @code{label_ref} which represents the address of +the label, as a number. + +@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 +referenced in the current function. + +@findex barrier +@item barrier +Barriers are placed in the instruction stream when control cannot flow +past them. They are placed after unconditional jump instructions to +indicate that the jumps are unconditional and after calls to +@code{volatile} functions, which do not return (e.g., @code{exit}). +They contain no information beyond the three standard fields. + +@findex note +@findex NOTE_LINE_NUMBER +@findex NOTE_SOURCE_FILE +@item note +@code{note} insns are used to represent additional debugging and +declarative information. They contain two nonstandard fields, an +integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a +string accessed with @code{NOTE_SOURCE_FILE}. + +If @code{NOTE_LINE_NUMBER} is positive, the note represents the +position of a source line and @code{NOTE_SOURCE_FILE} is the source file name +that the line came from. These notes control generation of line +number data in the assembler output. + +Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a +code with one of the following values (and @code{NOTE_SOURCE_FILE} +must contain a null pointer): + +@table @code +@findex NOTE_INSN_DELETED +@item NOTE_INSN_DELETED +Such a note is completely ignorable. Some passes of the compiler +delete insns by altering them into notes of this kind. + +@findex NOTE_INSN_BLOCK_BEG +@findex NOTE_INSN_BLOCK_END +@item NOTE_INSN_BLOCK_BEG +@itemx NOTE_INSN_BLOCK_END +These types of notes indicate the position of the beginning and end +of a level of scoping of variable names. They control the output +of debugging information. + +@findex NOTE_INSN_LOOP_BEG +@findex NOTE_INSN_LOOP_END +@item NOTE_INSN_LOOP_BEG +@itemx NOTE_INSN_LOOP_END +These types of notes indicate the position of the beginning and end +of a @code{while} or @code{for} loop. They enable the loop optimizer +to find loops quickly. + +@findex NOTE_INSN_LOOP_CONT +@item NOTE_INSN_LOOP_CONT +Appears at the place in a loop that @code{continue} statements jump to. + +@findex NOTE_INSN_LOOP_VTOP +@item NOTE_INSN_LOOP_VTOP +This note indicates the place in a loop where the exit test begins for +those loops in which the exit test has been duplicated. This position +becomes another virtual start of the loop when considering loop +invariants. + +@findex NOTE_INSN_FUNCTION_END +@item NOTE_INSN_FUNCTION_END +Appears near the end of the function body, just before the label that +@code{return} statements jump to (on machine where a single instruction +does not suffice for returning). This note may be deleted by jump +optimization. + +@findex NOTE_INSN_SETJMP +@item NOTE_INSN_SETJMP +Appears following each call to @code{setjmp} or a related function. +@end table + +These codes are printed symbolically when they appear in debugging dumps. +@end table + +@cindex @code{HImode}, in @code{insn} +@cindex @code{QImode}, in @code{insn} +The machine mode of an insn is normally @code{VOIDmode}, but some +phases use the mode for various purposes; for example, the reload pass +sets it to @code{HImode} if the insn needs reloading but not register +elimination and @code{QImode} if both are required. The common +subexpression elimination pass sets the mode of an insn to @code{QImode} +when it is the first insn in a block that has already been processed. + +Here is a table of the extra fields of @code{insn}, @code{jump_insn} +and @code{call_insn} insns: + +@table @code +@findex PATTERN +@item PATTERN (@var{i}) +An expression for the side effect performed by this insn. This must be +one of the following codes: @code{set}, @code{call}, @code{use}, +@code{clobber}, @code{return}, @code{asm_input}, @code{asm_output}, +@code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec}, +@code{unspec_volatile}, @code{parallel}, or @code{sequence}. If it is a @code{parallel}, +each element of the @code{parallel} must be one these codes, except that +@code{parallel} expressions cannot be nested and @code{addr_vec} and +@code{addr_diff_vec} are not permitted inside a @code{parallel} expression. + +@findex INSN_CODE +@item INSN_CODE (@var{i}) +An integer that says which pattern in the machine description matches +this insn, or -1 if the matching has not yet been attempted. + +Such matching is never attempted and this field remains -1 on an insn +whose pattern consists of a single @code{use}, @code{clobber}, +@code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression. + +@findex asm_noperands +Matching is also never attempted on insns that result from an @code{asm} +statement. These contain at least one @code{asm_operands} expression. +The function @code{asm_noperands} returns a non-negative value for +such insns. + +In the debugging output, this field is printed as a number followed by +a symbolic representation that locates the pattern in the @file{md} +file as some small positive or negative offset from a named pattern. + +@findex LOG_LINKS +@item LOG_LINKS (@var{i}) +A list (chain of @code{insn_list} expressions) giving information about +dependencies between instructions within a basic block. Neither a jump +nor a label may come between the related insns. + +@findex REG_NOTES +@item REG_NOTES (@var{i}) +A list (chain of @code{expr_list} and @code{insn_list} expressions) +giving miscellaneous information about the insn. It is often information +pertaining to the registers used in this insn. +@end table + +The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list} +expressions. Each of these has two operands: the first is an insn, +and the second is another @code{insn_list} expression (the next one in +the chain). The last @code{insn_list} in the chain has a null pointer +as second operand. The significant thing about the chain is which +insns appear in it (as first operands of @code{insn_list} +expressions). Their order is not significant. + +This list is originally set up by the flow analysis pass; it is a null +pointer until then. Flow only adds links for those data dependencies +which can be used for instruction combination. For each insn, the flow +analysis pass adds a link to insns which store into registers values +that are used for the first time in this insn. The instruction +scheduling pass adds extra links so that every dependence will be +represented. Links represent data dependencies, antidependencies and +output dependencies; the machine mode of the link distinguishes these +three types: antidependencies have mode @code{REG_DEP_ANTI}, output +dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have +mode @code{VOIDmode}. + +The @code{REG_NOTES} field of an insn is a chain similar to the +@code{LOG_LINKS} field but it includes @code{expr_list} expressions in +addition to @code{insn_list} expressions. There are several kinds +of register notes, which are distinguished by the machine mode, which +in a register note is really understood as being an @code{enum reg_note}. +The first operand @var{op} of the note is data whose meaning depends on +the kind of note. + +@findex REG_NOTE_KIND +@findex PUT_REG_NOTE_KIND +The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of +register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND +(@var{x}, @var{newkind})} sets the register note type of @var{x} to be +@var{newkind}. + +Register notes are of three classes: They may say something about an +input to an insn, they may say something about an output of an insn, or +they may create a linkage between two insns. There are also a set +of values that are only used in @code{LOG_LINKS}. + +These register notes annotate inputs to an insn: + +@table @code +@findex REG_DEAD +@item REG_DEAD +The value in @var{op} dies in this insn; that is to say, altering the +value immediately after this insn would not affect the future behavior +of the program. + +This does not necessarily mean that the register @var{op} has no useful +value after this insn since it may also be an output of the insn. In +such a case, however, a @code{REG_DEAD} note would be redundant and is +usually not present until after the reload pass, but no code relies on +this fact. + +@findex REG_INC +@item REG_INC +The register @var{op} is incremented (or decremented; at this level +there is no distinction) by an embedded side effect inside this insn. +This means it appears in a @code{post_inc}, @code{pre_inc}, +@code{post_dec} or @code{pre_dec} expression. + +@findex REG_NONNEG +@item REG_NONNEG +The register @var{op} is known to have a nonnegative value when this +insn is reached. This is used so that decrement and branch until zero +instructions, such as the m68k dbra, can be matched. + +The @code{REG_NONNEG} note is added to insns only if the machine +description has a @samp{decrement_and_branch_until_zero} pattern. + +@findex REG_NO_CONFLICT +@item REG_NO_CONFLICT +This insn does not cause a conflict between @var{op} and the item +being set by this insn even though it might appear that it does. +In other words, if the destination register and @var{op} could +otherwise be assigned the same register, this insn does not +prevent that assignment. + +Insns with this note are usually part of a block that begins with a +@code{clobber} insn specifying a multi-word pseudo register (which will +be the output of the block), a group of insns that each set one word of +the value and have the @code{REG_NO_CONFLICT} note attached, and a final +insn that copies the output to itself with an attached @code{REG_EQUAL} +note giving the expression being computed. This block is encapsulated +with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and +last insns, respectively. + +@findex REG_LABEL +@item REG_LABEL +This insn uses @var{op}, a @code{code_label}, but is not a +@code{jump_insn}. The presence of this note allows jump optimization to +be aware that @var{op} is, in fact, being used. +@end table + +The following notes describe attributes of outputs of an insn: + +@table @code +@findex REG_EQUIV +@findex REG_EQUAL +@item REG_EQUIV +@itemx REG_EQUAL +This note is only valid on an insn that sets only one register and +indicates that that register will be equal to @var{op} at run time; the +scope of this equivalence differs between the two types of notes. The +value which the insn explicitly copies into the register may look +different from @var{op}, but they will be equal at run time. If the +output of the single @code{set} is a @code{strict_low_part} expression, +the note refers to the register that is contained in @code{SUBREG_REG} +of the @code{subreg} expression. + +For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout +the entire function, and could validly be replaced in all its +occurrences by @var{op}. (``Validly'' here refers to the data flow of +the program; simple replacement may make some insns invalid.) For +example, when a constant is loaded into a register that is never +assigned any other value, this kind of note is used. + +When a parameter is copied into a pseudo-register at entry to a function, +a note of this kind records that the register is equivalent to the stack +slot where the parameter was passed. Although in this case the register +may be set by other insns, it is still valid to replace the register +by the stack slot throughout the function. + +In the case of @code{REG_EQUAL}, the register that is set by this insn +will be equal to @var{op} at run time at the end of this insn but not +necessarily elsewhere in the function. In this case, @var{op} +is typically an arithmetic expression. For example, when a sequence of +insns such as a library call is used to perform an arithmetic operation, +this kind of note is attached to the insn that produces or copies the +final value. + +These two notes are used in different ways by the compiler passes. +@code{REG_EQUAL} is used by passes prior to register allocation (such as +common subexpression elimination and loop optimization) to tell them how +to think of that value. @code{REG_EQUIV} notes are used by register +allocation to indicate that there is an available substitute expression +(either a constant or a @code{mem} expression for the location of a +parameter on the stack) that may be used in place of a register if +insufficient registers are available. + +Except for stack homes for parameters, which are indicated by a +@code{REG_EQUIV} note and are not useful to the early optimization +passes and pseudo registers that are equivalent to a memory location +throughout there entire life, which is not detected until later in +the compilation, all equivalences are initially indicated by an attached +@code{REG_EQUAL} note. In the early stages of register allocation, a +@code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if +@var{op} is a constant and the insn represents the only set of its +destination register. + +Thus, compiler passes prior to register allocation need only check for +@code{REG_EQUAL} notes and passes subsequent to register allocation +need only check for @code{REG_EQUIV} notes. + +@findex REG_UNUSED +@item REG_UNUSED +The register @var{op} being set by this insn will not be used in a +subsequent insn. This differs from a @code{REG_DEAD} note, which +indicates that the value in an input will not be used subsequently. +These two notes are independent; both may be present for the same +register. + +@findex REG_WAS_0 +@item REG_WAS_0 +The single output of this insn contained zero before this insn. +@var{op} is the insn that set it to zero. You can rely on this note if +it is present and @var{op} has not been deleted or turned into a @code{note}; +its absence implies nothing. +@end table + +These notes describe linkages between insns. They occur in pairs: one +insn has one of a pair of notes that points to a second insn, which has +the inverse note pointing back to the first insn. + +@table @code +@findex REG_RETVAL +@item REG_RETVAL +This insn copies the value of a multi-insn sequence (for example, a +library call), and @var{op} is the first insn of the sequence (for a +library call, the first insn that was generated to set up the arguments +for the library call). + +Loop optimization uses this note to treat such a sequence as a single +operation for code motion purposes and flow analysis uses this note to +delete such sequences whose results are dead. + +A @code{REG_EQUAL} note will also usually be attached to this insn to +provide the expression being computed by the sequence. + +@findex REG_LIBCALL +@item REG_LIBCALL +This is the inverse of @code{REG_RETVAL}: it is placed on the first +insn of a multi-insn sequence, and it points to the last one. + +@findex REG_CC_SETTER +@findex REG_CC_USER +@item REG_CC_SETTER +@itemx REG_CC_USER +On machines that use @code{cc0}, the insns which set and use @code{cc0} +set and use @code{cc0} are adjacent. However, when branch delay slot +filling is done, this may no longer be true. In this case a +@code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to +point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will +be placed on the insn using @code{cc0} to point to the insn setting +@code{cc0}.@refill +@end table + +These values are only used in the @code{LOG_LINKS} field, and indicate +the type of dependency that each link represents. Links which indicate +a data dependence (a read after write dependence) do not use any code, +they simply have mode @code{VOIDmode}, and are printed without any +descriptive text. + +@table @code +@findex REG_DEP_ANTI +@item REG_DEP_ANTI +This indicates an anti dependence (a write after read dependence). + +@findex REG_DEP_OUTPUT +@item REG_DEP_OUTPUT +This indicates an output dependence (a write after write dependence). +@end table + +For convenience, the machine mode in an @code{insn_list} or +@code{expr_list} is printed using these symbolic codes in debugging dumps. + +@findex insn_list +@findex expr_list +The only difference between the expression codes @code{insn_list} and +@code{expr_list} is that the first operand of an @code{insn_list} is +assumed to be an insn and is printed in debugging dumps as the insn's +unique id; the first operand of an @code{expr_list} is printed in the +ordinary way as an expression. + +@node Calls, Sharing, Insns, RTL +@section RTL Representation of Function-Call Insns +@cindex calling functions in RTL +@cindex RTL function-call insns +@cindex function-call insns + +Insns that call subroutines have the RTL expression code @code{call_insn}. +These insns must satisfy special rules, and their bodies must use a special +RTL expression code, @code{call}. + +@cindex @code{call} usage +A @code{call} expression has two operands, as follows: + +@example +(call (mem:@var{fm} @var{addr}) @var{nbytes}) +@end example + +@noindent +Here @var{nbytes} is an operand that represents the number of bytes of +argument data being passed to the subroutine, @var{fm} is a machine mode +(which must equal as the definition of the @code{FUNCTION_MODE} macro in +the machine description) and @var{addr} represents the address of the +subroutine. + +For a subroutine that returns no value, the @code{call} expression as +shown above is the entire body of the insn, except that the insn might +also contain @code{use} or @code{clobber} expressions. + +@cindex @code{BLKmode}, and function return values +For a subroutine that returns a value whose mode is not @code{BLKmode}, +the value is returned in a hard register. If this register's number is +@var{r}, then the body of the call insn looks like this: + +@example +(set (reg:@var{m} @var{r}) + (call (mem:@var{fm} @var{addr}) @var{nbytes})) +@end example + +@noindent +This RTL expression makes it clear (to the optimizer passes) that the +appropriate register receives a useful value in this insn. + +When a subroutine returns a @code{BLKmode} value, it is handled by +passing to the subroutine the address of a place to store the value. +So the call insn itself does not ``return'' any value, and it has the +same RTL form as a call that returns nothing. + +On some machines, the call instruction itself clobbers some register, +for example to contain the return address. @code{call_insn} insns +on these machines should have a body which is a @code{parallel} +that contains both the @code{call} expression and @code{clobber} +expressions that indicate which registers are destroyed. Similarly, +if the call instruction requires some register other than the stack +pointer that is not explicitly mentioned it its RTL, a @code{use} +subexpression should mention that register. + +Functions that are called are assumed to modify all registers listed in +the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register +Basics}) and, with the exception of @code{const} functions and library +calls, to modify all of memory. + +Insns containing just @code{use} expressions directly precede the +@code{call_insn} insn to indicate which registers contain inputs to the +function. Similarly, if registers other than those in +@code{CALL_USED_REGISTERS} are clobbered by the called function, insns +containing a single @code{clobber} follow immediately after the call to +indicate which registers. + +@node Sharing +@section Structure Sharing Assumptions +@cindex sharing of RTL components +@cindex RTL structure sharing assumptions + +The compiler assumes that certain kinds of RTL expressions are unique; +there do not exist two distinct objects representing the same value. +In other cases, it makes an opposite assumption: that no RTL expression +object of a certain kind appears in more than one place in the +containing structure. + +These assumptions refer to a single function; except for the RTL +objects that describe global variables and external functions, +and a few standard objects such as small integer constants, +no RTL objects are common to two functions. + +@itemize @bullet +@cindex @code{reg}, RTL sharing +@item +Each pseudo-register has only a single @code{reg} object to represent it, +and therefore only a single machine mode. + +@cindex symbolic label +@cindex @code{symbol_ref}, RTL sharing +@item +For any symbolic label, there is only one @code{symbol_ref} object +referring to it. + +@cindex @code{const_int}, RTL sharing +@item +There is only one @code{const_int} expression with value 0, only +one with value 1, and only one with value @minus{}1. +Some other integer values are also stored uniquely. + +@cindex @code{pc}, RTL sharing +@item +There is only one @code{pc} expression. + +@cindex @code{cc0}, RTL sharing +@item +There is only one @code{cc0} expression. + +@cindex @code{const_double}, RTL sharing +@item +There is only one @code{const_double} expression with value 0 for +each floating point mode. Likewise for values 1 and 2. + +@cindex @code{label_ref}, RTL sharing +@cindex @code{scratch}, RTL sharing +@item +No @code{label_ref} or @code{scratch} appears in more than one place in +the RTL structure; in other words, it is safe to do a tree-walk of all +the insns in the function and assume that each time a @code{label_ref} +or @code{scratch} is seen it is distinct from all others that are seen. + +@cindex @code{mem}, RTL sharing +@item +Only one @code{mem} object is normally created for each static +variable or stack slot, so these objects are frequently shared in all +the places they appear. However, separate but equal objects for these +variables are occasionally made. + +@cindex @code{asm_operands}, RTL sharing +@item +When a single @code{asm} statement has multiple output operands, a +distinct @code{asm_operands} expression is made for each output operand. +However, these all share the vector which contains the sequence of input +operands. This sharing is used later on to test whether two +@code{asm_operands} expressions come from the same statement, so all +optimizations must carefully preserve the sharing if they copy the +vector at all. + +@item +No RTL object appears in more than one place in the RTL structure +except as described above. Many passes of the compiler rely on this +by assuming that they can modify RTL objects in place without unwanted +side-effects on other insns. + +@findex unshare_all_rtl +@item +During initial RTL generation, shared structure is freely introduced. +After all the RTL for a function has been generated, all shared +structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c}, +after which the above rules are guaranteed to be followed. + +@findex copy_rtx_if_shared +@item +During the combiner pass, shared structure within an insn can exist +temporarily. However, the shared structure is copied before the +combiner is finished with the insn. This is done by calling +@code{copy_rtx_if_shared}, which is a subroutine of +@code{unshare_all_rtl}. +@end itemize + +@node Reading RTL +@section Reading RTL + +To read an RTL object from a file, call @code{read_rtx}. It takes one +argument, a stdio stream, and returns a single RTL object. + +Reading RTL from a file is very slow. This is no currently not a +problem because reading RTL occurs only as part of building the +compiler. + +People frequently have the idea of using RTL stored as text in a file as +an interface between a language front end and the bulk of GNU CC. This +idea is not feasible. + +GNU CC was designed to use RTL internally only. Correct RTL for a given +program is very dependent on the particular target machine. And the RTL +does not contain all the information about the program. + +The proper way to interface GNU CC to a new language front end is with +the ``tree'' data structure. There is no manual for this data +structure, but it is described in the files @file{tree.h} and +@file{tree.def}. diff --git a/gnu/usr.bin/cc/doc/templates.texi b/gnu/usr.bin/cc/doc/templates.texi new file mode 100644 index 0000000..2a6db07 --- /dev/null +++ b/gnu/usr.bin/cc/doc/templates.texi @@ -0,0 +1,235 @@ +@node Templates +@chapter The Template Implementation + +@cindex templates +@cindex function templates +@cindex class templates +@cindex parameterized types +@cindex types, parameterized +The C++ template@footnote{Class templates are also known as +@dfn{parameterized types}.} facility, which effectively allows use of +variables for types in declarations, is one of the newest features of +the language. + +@sc{gnu} C++ is one of the first compilers to implement many +of the template facilities currently defined by the @sc{ansi} committee. + +Nevertheless, the template implementation is not yet complete. This +chapter maps the current limitations of the @sc{gnu} C++ template +implementation. + +@menu +* Template limitations:: Limitations for function and class templates +* Function templates:: Limitations for function templates +* Class templates:: Limitations for class templates +* Template debugging:: Debugging information for templates +@end menu + +@node Template limitations +@section Limitations for function and class templates + +@cindex template limitations +@cindex template bugs +@cindex bugs, templates +These limitations apply to any use of templates (function templates or +class templates) with @sc{gnu} C++: + +@table @emph +@item Template definitions must be visible +When you compile code with templates, the template definitions must come +first (before the compiler needs to expand them), and template +definitions you use must be visible in the current scope. +@c FIXME! Is this a defined property of templates, rather than a +@c temporary limitation? +@c ANSWER: It's a limitation, but it's hard to say why it's a limitation +@c to someone. We need an infinite link-cycle, in one camp, to +@c accomplish things so you don't need the template definitions around. + +@cindex static data in template classes +@cindex template classes, static data in +@item Individual initializers needed for static data +Templates for static data in template classes do not work. @xref{Class +templates,,Limitations for class templates}. +@end table + +@node Function templates +@section Limitations for function templates + +@cindex function template limitations +Function templates are implemented for the most part. The compiler can +correctly determine template parameter values, and will delay +instantiation of a function that uses templates until the requisite type +information is available. + +@noindent +The following limitations remain: + +@itemize @bullet +@cindex template vs declaration, functions +@cindex declaration vs template, functions +@cindex function declaration vs template +@item +Narrowed specification: function declarations should not prevent +template expansion. When you declare a function, @sc{gnu} C++ +interprets the declaration as an indication that you will provide a +definition for that function. Therefore, @sc{gnu} C++ does not use a +template expansion if there is also an applicable declaration. @sc{gnu} +C++ only expands the template when there is no such declaration. + +The specification in Bjarne Stroustrup's @cite{The C++ Programming +Language, Second Edition} is narrower, and the @sc{gnu} C++ +implementation is now clearly incorrect. With this new specification, a +declaration that corresponds to an instantiation of a function template +only affects whether conversions are needed to use that version of the +function. It should no longer prevent expansion of the template +definition. + +For example, this code fragment must be treated differently: + +@smallexample +template <class X> X min (X& x1, X& x2) @{ @dots{} @} +int min (int, int); +@dots{} +int i; short s; +min (i, s); // @r{should call} min(int,int) + // @r{derived from template} +@dots{} +@end smallexample + +@item +The compiler does not yet understand function signatures where types are +nested within template parameters. For example, a function like the +following produces a syntax error on the closing @samp{)} of the +definition of the function @code{f}: + +@smallexample +template <class T> class A @{ public: T x; class Y @{@}; @}; +template <class X> int f (A<X>::Y y) @{ @dots{} @} +@end smallexample + +@cindex @code{inline} and function templates +@cindex function templates and @code{inline} +@item +If you declare an @code{inline} function using templates, the compiler +can only inline the code @emph{after} the first time you use +that function with whatever particular type signature the template +was instantiated. + +Removing this limitation is akin to supporting nested function +definitions in @sc{gnu} C++; the limitation will probably remain until the +more general problem of nested functions is solved. + +@item +All the @emph{method} templates (templates for member functions) for a +class must be visible to the compiler when the class template is +instantiated. +@end itemize + +@node Class templates +@section Limitations for class templates + +@cindex class template limitations +@ignore +FIXME!! Include a comprehensible version of this if someone can explain it. + (Queried Brendan and Raeburn w/full orig context, 26may1993---pesch) + - [RHP: I don't understand what the following fragment refers to. If it's + the "BIG BUG" section in the original, why does it say "overriding class + declarations" here when the more detailed text refers to *function* + declarations? Here's the fragment I don't understand:] + there are problems with user-supplied overriding class declarations (see + below). +@end ignore + +@itemize @bullet +@ignore +@cindex static data, not working in templates +@item +Templates for static data in template classes do not work. +Currently, you must initialize each case of such data +individually. +@c FIXME!! Brendan to see if still true. +@c ANSWER: This section presumes that it's incorrect to have to +@c initialize for each type you instantiate with. It's not, it's the +@c right way to do it. +@end ignore + +Unfortunately, individual initializations of this sort are likely to be +considered errors eventually; since they're needed now, you might want to +flag places where you use them with comments to mark the need for a +future transition. + +@cindex nested type results vs templates +@item +Member functions in template classes may not have results of nested +type; @sc{gnu} C++ signals a syntax error on the attempt. The following +example illustrates this problem with an @code{enum} type @code{alph}: + +@smallexample +template <class T> class list @{ + @dots{} + enum alph @{a,b,c@}; + alph bar(); + @dots{} +@}; + +template <class T> +list<int>::alph list<int>::bar() // @i{Syntax error here} +@{ +@dots{} +@} +@end smallexample + +@cindex preprocessor conditionals in templates +@cindex conditionals (preprocessor) in templates +@item +A parsing bug makes it difficult to use preprocessor conditionals within +templates. For example, in this code: + +@smallexample +template <class T> +class list @{ + @dots{} +#ifdef SYSWRONG + T x; +#endif + @dots{} +@} +@end smallexample + +The preprocessor output leaves sourcefile line number information (lines +like @samp{# 6 "foo.cc"} when it expands the @code{#ifdef} block. These +lines confuse the compiler while parsing templates, giving a syntax +error. + +If you cannot avoid preprocessor conditionals in templates, you can +suppress the line number information using the @samp{-P} preprocessor +option (but this will make debugging more difficult), by compiling the +affected modules like this: + +@smallexample +g++ -P foo.cc -o foo +@end smallexample + +@cindex parsing errors, templates +@item +Parsing errors are reported when templates are first +@emph{instantiated}---not on the template definition itself. In +particular, if you do not instantiate a template definition at all, the +compiler never reports any parsing errors that may be in the template +definition. +@end itemize + +@node Template debugging +@section Debugging information for templates + +@cindex templates and debugging information +@cindex debugging information and templates +Debugging information for templates works for some object code formats, +but not others. It works for stabs@footnote{Except that insufficient +debugging information for methods of template classes is generated in +stabs.} (used primarily in @sc{a.out} object code, but also in the Solaris 2 +version of @sc{elf}), and the @sc{mips} version of @sc{coff} debugging +format. + +@sc{dwarf} support is currently minimal, and requires further +development. diff --git a/gnu/usr.bin/cc/doc/tm.texi b/gnu/usr.bin/cc/doc/tm.texi new file mode 100644 index 0000000..3824d2f --- /dev/null +++ b/gnu/usr.bin/cc/doc/tm.texi @@ -0,0 +1,6337 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Target Macros +@chapter Target Description Macros +@cindex machine description macros +@cindex target description macros +@cindex macros, target description +@cindex @file{tm.h} macros + +In addition to the file @file{@var{machine}.md}, a machine description +includes a C header file conventionally given the name +@file{@var{machine}.h}. This header file defines numerous macros +that convey the information about the target machine that does not fit +into the scheme of the @file{.md} file. The file @file{tm.h} should be +a link to @file{@var{machine}.h}. The header file @file{config.h} +includes @file{tm.h} and most compiler source files include +@file{config.h}. + +@menu +* Driver:: Controlling how the driver runs the compilation passes. +* Run-time Target:: Defining @samp{-m} options like @samp{-m68000} and @samp{-m68020}. +* Storage Layout:: Defining sizes and alignments of data. +* Type Layout:: Defining sizes and properties of basic user data types. +* Registers:: Naming and describing the hardware registers. +* Register Classes:: Defining the classes of hardware registers. +* Stack and Calling:: Defining which way the stack grows and by how much. +* Varargs:: Defining the varargs macros. +* Trampolines:: Code set up at run time to enter a nested function. +* Library Calls:: Controlling how library routines are implicitly called. +* Addressing Modes:: Defining addressing modes valid for memory operands. +* Condition Code:: Defining how insns update the condition code. +* Costs:: Defining relative costs of different operations. +* Sections:: Dividing storage into text, data, and other sections. +* 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. +* Misc:: Everything else. +@end menu + +@node Driver +@section Controlling the Compilation Driver, @file{gcc} +@cindex driver +@cindex controlling the compilation driver + +@c prevent bad page break with this line +You can control the compilation driver. + +@table @code +@findex SWITCH_TAKES_ARG +@item SWITCH_TAKES_ARG (@var{char}) +A C expression which determines whether the option @samp{-@var{char}} +takes arguments. The value should be the number of arguments that +option takes--zero, for many options. + +By default, this macro is defined to handle the standard options +properly. You need not define it unless you wish to add additional +options which take arguments. + +@findex WORD_SWITCH_TAKES_ARG +@item WORD_SWITCH_TAKES_ARG (@var{name}) +A C expression which determines whether the option @samp{-@var{name}} +takes arguments. The value should be the number of arguments that +option takes--zero, for many options. This macro rather than +@code{SWITCH_TAKES_ARG} is used for multi-character option names. + +By default, this macro is defined as +@code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options +properly. You need not define @code{WORD_SWITCH_TAKES_ARG} unless you +wish to add additional options which take arguments. Any redefinition +should call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for +additional options. + +@findex SWITCHES_NEED_SPACES +@item SWITCHES_NEED_SPACES +A string-valued C expression which is nonempty if the linker needs a +space between the @samp{-L} or @samp{-o} option and its argument. + +If this macro is not defined, the default value is 0. + +@findex CPP_SPEC +@item CPP_SPEC +A C string constant that tells the GNU CC driver program options to +pass to CPP. It can also specify how to translate options you +give to GNU CC into options for GNU CC to pass to the CPP. + +Do not define this macro if it does not need to do anything. + +@findex NO_BUILTIN_SIZE_TYPE +@item NO_BUILTIN_SIZE_TYPE +If this macro is defined, the preprocessor will not define the builtin 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 builtin 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 SIGNED_CHAR_SPEC +@item SIGNED_CHAR_SPEC +A C string constant that tells the GNU CC driver program options to +pass to CPP. By default, this macro is defined to pass the option +@samp{-D__CHAR_UNSIGNED__} to CPP if @code{char} will be treated as +@code{unsigned char} by @code{cc1}. + +Do not define this macro unless you need to override the default +definition. + +@findex CC1_SPEC +@item CC1_SPEC +A C string constant that tells the GNU CC driver program options to +pass to @code{cc1}. It can also specify how to translate options you +give to GNU CC into options for GNU CC to pass to the @code{cc1}. + +Do not define this macro if it does not need to do anything. + +@findex CC1PLUS_SPEC +@item CC1PLUS_SPEC +A C string constant that tells the GNU CC driver program options to +pass to @code{cc1plus}. It can also specify how to translate options you +give to GNU CC into options for GNU CC to pass to the @code{cc1plus}. + +Do not define this macro if it does not need to do anything. + +@findex ASM_SPEC +@item ASM_SPEC +A C string constant that tells the GNU CC driver program options to +pass to the assembler. It can also specify how to translate options +you give to GNU CC into options for GNU CC to pass to the assembler. +See the file @file{sun3.h} for an example of this. + +Do not define this macro if it does not need to do anything. + +@findex ASM_FINAL_SPEC +@item ASM_FINAL_SPEC +A C string constant that tells the GNU CC driver program how to +run any programs which cleanup after the normal assembler. +Normally, this is not needed. See the file @file{mips.h} for +an example of this. + +Do not define this macro if it does not need to do anything. + +@findex LINK_SPEC +@item LINK_SPEC +A C string constant that tells the GNU CC driver program options to +pass to the linker. It can also specify how to translate options you +give to GNU CC into options for GNU CC to pass to the linker. + +Do not define this macro if it does not need to do anything. + +@findex LIB_SPEC +@item LIB_SPEC +Another C string constant used much like @code{LINK_SPEC}. The difference +between the two is that @code{LIB_SPEC} is used at the end of the +command given to the linker. + +If this macro is not defined, a default is provided that +loads the standard C library from the usual place. See @file{gcc.c}. + +@findex STARTFILE_SPEC +@item STARTFILE_SPEC +Another C string constant used much like @code{LINK_SPEC}. The +difference between the two is that @code{STARTFILE_SPEC} is used at +the very beginning of the command given to the linker. + +If this macro is not defined, a default is provided that loads the +standard C startup file from the usual place. See @file{gcc.c}. + +@findex ENDFILE_SPEC +@item ENDFILE_SPEC +Another C string constant used much like @code{LINK_SPEC}. The +difference between the two is that @code{ENDFILE_SPEC} is used at +the very end of the command given to the linker. + +Do not define this macro if it does not need to do anything. + +@findex LINK_LIBGCC_SPECIAL +@item LINK_LIBGCC_SPECIAL +Define this macro meaning that @code{gcc} should find the library +@file{libgcc.a} by hand, rather than passing the argument @samp{-lgcc} +to tell the linker to do the search; also, @code{gcc} should not +generate @samp{-L} options to pass to the linker (as it normally does). + +@findex LINK_LIBGCC_SPECIAL_1 +@item LINK_LIBGCC_SPECIAL_1 +Define this macro meaning that @code{gcc} should find the +library @file{libgcc.a} by hand, rather than passing the argument +@samp{-lgcc} to tell the linker to do the search. + +@findex RELATIVE_PREFIX_NOT_LINKDIR +@item RELATIVE_PREFIX_NOT_LINKDIR +Define this macro to tell @code{gcc} that it should only translate +a @samp{-B} prefix into a @samp{-L} linker option if the prefix +indicates an absolute file name. + +@findex STANDARD_EXEC_PREFIX +@item STANDARD_EXEC_PREFIX +Define this macro as a C string constant if you wish to override the +standard choice of @file{/usr/local/lib/gcc-lib/} as the default prefix to +try when searching for the executable files of the compiler. + +@findex MD_EXEC_PREFIX +@item MD_EXEC_PREFIX +If defined, this macro is an additional prefix to try after +@code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched +when the @samp{-b} option is used, or the compiler is built as a cross +compiler. + +@findex STANDARD_STARTFILE_PREFIX +@item STANDARD_STARTFILE_PREFIX +Define this macro as a C string constant if you wish to override the +standard choice of @file{/usr/local/lib/} as the default prefix to +try when searching for startup files such as @file{crt0.o}. + +@findex MD_STARTFILE_PREFIX +@item MD_STARTFILE_PREFIX +If defined, this macro supplies an additional prefix to try after the +standard prefixes. @code{MD_EXEC_PREFIX} is not searched when the +@samp{-b} option is used, or when the compiler is built as a cross +compiler. + +@findex MD_STARTFILE_PREFIX_1 +@item MD_STARTFILE_PREFIX_1 +If defined, this macro supplies yet another prefix to try after the +standard prefixes. It is not searched when the @samp{-b} option is +used, or when the compiler is built as a cross compiler. + +@findex LOCAL_INCLUDE_DIR +@item LOCAL_INCLUDE_DIR +Define this macro as a C string constant if you wish to override the +standard choice of @file{/usr/local/include} as the default prefix to +try when searching for local header files. @code{LOCAL_INCLUDE_DIR} +comes before @code{SYSTEM_INCLUDE_DIR} in the search order. + +Cross compilers do not use this macro and do not search either +@file{/usr/local/include} or its replacement. + +@findex SYSTEM_INCLUDE_DIR +@item SYSTEM_INCLUDE_DIR +Define this macro as a C string constant if you wish to specify a +system-specific directory to search for header files before the standard +directory. @code{SYSTEM_INCLUDE_DIR} comes before +@code{STANDARD_INCLUDE_DIR} in the search order. + +Cross compilers do not use this macro and do not search the directory +specified. + +@findex STANDARD_INCLUDE_DIR +@item STANDARD_INCLUDE_DIR +Define this macro as a C string constant if you wish to override the +standard choice of @file{/usr/include} as the default prefix to +try when searching for header files. + +Cross compilers do not use this macro and do not search either +@file{/usr/include} or its replacement. + +@findex INCLUDE_DEFAULTS +@item INCLUDE_DEFAULTS +Define this macro if you wish to override the entire default search path +for include files. The default search path includes +@code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR}, +@code{SYSTEM_INCLUDE_DIR}, @code{GPLUSPLUS_INCLUDE_DIR}, and +@code{STANDARD_INCLUDE_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR} +and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile}, +and specify private search areas for GCC. The directory +@code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs. + +The definition should be an initializer for an array of structures. +Each array element should have two elements: the directory name (a +string constant) and a flag for C++-only directories. Mark the end of +the array with a null element. For example, here is the definition used +for VMS: + +@example +#define INCLUDE_DEFAULTS \ +@{ \ + @{ "GNU_GXX_INCLUDE:", 1@}, \ + @{ "GNU_CC_INCLUDE:", 0@}, \ + @{ "SYS$SYSROOT:[SYSLIB.]", 0@}, \ + @{ ".", 0@}, \ + @{ 0, 0@} \ +@} +@end example +@end table + +Here is the order of prefixes tried for exec files: + +@enumerate +@item +Any prefixes specified by the user with @samp{-B}. + +@item +The environment variable @code{GCC_EXEC_PREFIX}, if any. + +@item +The directories specified by the environment variable @code{COMPILER_PATH}. + +@item +The macro @code{STANDARD_EXEC_PREFIX}. + +@item +@file{/usr/lib/gcc/}. + +@item +The macro @code{MD_EXEC_PREFIX}, if any. +@end enumerate + +Here is the order of prefixes tried for startfiles: + +@enumerate +@item +Any prefixes specified by the user with @samp{-B}. + +@item +The environment variable @code{GCC_EXEC_PREFIX}, if any. + +@item +The directories specified by the environment variable @code{LIBRARY_PATH}. + +@item +The macro @code{STANDARD_EXEC_PREFIX}. + +@item +@file{/usr/lib/gcc/}. + +@item +The macro @code{MD_EXEC_PREFIX}, if any. + +@item +The macro @code{MD_STARTFILE_PREFIX}, if any. + +@item +The macro @code{STANDARD_STARTFILE_PREFIX}. + +@item +@file{/lib/}. + +@item +@file{/usr/lib/}. +@end enumerate + +@node Run-time Target +@section Run-time Target Specification +@cindex run-time target specification +@cindex predefined macros +@cindex target specifications + +@c prevent bad page break with this line +Here are run-time target specifications. + +@table @code +@findex CPP_PREDEFINES +@item CPP_PREDEFINES +Define this to be a string constant containing @samp{-D} options to +define the predefined macros that identify this machine and system. +These macros will be predefined unless the @samp{-ansi} option is +specified. + +In addition, a parallel set of macros are predefined, whose names are +made by appending @samp{__} at the beginning and at the end. These +@samp{__} macros are permitted by the ANSI standard, so they are +predefined regardless of whether @samp{-ansi} is specified. + +For example, on the Sun, one can use the following value: + +@smallexample +"-Dmc68000 -Dsun -Dunix" +@end smallexample + +The result is to define the macros @code{__mc68000__}, @code{__sun__} +and @code{__unix__} unconditionally, and the macros @code{mc68000}, +@code{sun} and @code{unix} provided @samp{-ansi} is not specified. + +@findex STDC_VALUE +@item STDC_VALUE +Define the value to be assigned to the built-in macro @code{__STDC__}. +The default is the value @samp{1}. + +@findex extern int target_flags +@item extern int target_flags; +This declaration should be present. + +@cindex optional hardware or system features +@cindex features, optional, in system conventions +@item TARGET_@dots{} +This series of macros is to allow compiler command arguments to +enable or disable the use of optional features of the target machine. +For example, one machine description serves both the 68000 and +the 68020; a command argument tells the compiler whether it should +use 68020-only instructions or not. This command argument works +by means of a macro @code{TARGET_68020} that tests a bit in +@code{target_flags}. + +Define a macro @code{TARGET_@var{featurename}} for each such option. +Its definition should test a bit in @code{target_flags}; for example: + +@smallexample +#define TARGET_68020 (target_flags & 1) +@end smallexample + +One place where these macros are used is in the condition-expressions +of instruction patterns. Note how @code{TARGET_68020} appears +frequently in the 68000 machine description file, @file{m68k.md}. +Another place they are used is in the definitions of the other +macros in the @file{@var{machine}.h} file. + +@findex TARGET_SWITCHES +@item TARGET_SWITCHES +This macro defines names of command options to set and clear +bits in @code{target_flags}. Its definition is an initializer +with a subgrouping for each command option. + +Each subgrouping contains a string constant, that defines the option +name, and a number, which contains the bits to set in +@code{target_flags}. A negative number says to clear bits instead; +the negative of the number is which bits to clear. The actual option +name is made by appending @samp{-m} to the specified name. + +One of the subgroupings should have a null string. The number in +this grouping is the default value for @code{target_flags}. Any +target options act starting with that value. + +Here is an example which defines @samp{-m68000} and @samp{-m68020} +with opposite meanings, and picks the latter as the default: + +@smallexample +#define TARGET_SWITCHES \ + @{ @{ "68020", 1@}, \ + @{ "68000", -1@}, \ + @{ "", 1@}@} +@end smallexample + +@findex TARGET_OPTIONS +@item TARGET_OPTIONS +This macro is similar to @code{TARGET_SWITCHES} but defines names of command +options that have values. Its definition is an initializer with a +subgrouping for each command option. + +Each subgrouping contains a string constant, that defines the fixed part +of the option name, and the address of a variable. The variable, type +@code{char *}, is set to the variable part of the given option if the fixed +part matches. The actual option name is made by appending @samp{-m} to the +specified name. + +Here is an example which defines @samp{-mshort-data-@var{number}}. If the +given option is @samp{-mshort-data-512}, the variable @code{m88k_short_data} +will be set to the string @code{"512"}. + +@smallexample +extern char *m88k_short_data; +#define TARGET_OPTIONS \ + @{ @{ "short-data-", &m88k_short_data @} @} +@end smallexample + +@findex TARGET_VERSION +@item TARGET_VERSION +This macro is a C statement to print on @code{stderr} a string +describing the particular machine description choice. Every machine +description should define @code{TARGET_VERSION}. For example: + +@smallexample +#ifdef MOTOROLA +#define TARGET_VERSION \ + fprintf (stderr, " (68k, Motorola syntax)"); +#else +#define TARGET_VERSION \ + fprintf (stderr, " (68k, MIT syntax)"); +#endif +@end smallexample + +@findex OVERRIDE_OPTIONS +@item OVERRIDE_OPTIONS +Sometimes certain combinations of command options do not make sense on +a particular target machine. You can define a macro +@code{OVERRIDE_OPTIONS} to take account of this. This macro, if +defined, is executed once just after all the command options have been +parsed. + +Don't use this macro to turn on various extra optimizations for +@samp{-O}. That is what @code{OPTIMIZATION_OPTIONS} is for. + +@findex OPTIMIZATION_OPTIONS +@item OPTIMIZATION_OPTIONS (@var{level}) +Some machines may desire to change what optimizations are performed for +various optimization levels. This macro, if defined, is executed once +just after the optimization level is determined and before the remainder +of the command options have been parsed. Values set in this macro are +used as the default values for the other command line options. + +@var{level} is the optimization level specified; 2 if @samp{-O2} is +specified, 1 if @samp{-O} is specified, and 0 if neither is specified. + +You should not use this macro to change options that are not +machine-specific. These should uniformly selected by the same +optimization level on all supported machines. Use this macro to enable +machbine-specific optimizations. + +@strong{Do not examine @code{write_symbols} in +this macro!} The debugging options are not supposed to alter the +generated code. + +@findex CAN_DEBUG_WITHOUT_FP +@item CAN_DEBUG_WITHOUT_FP +Define this macro if debugging can be performed even without a frame +pointer. If this macro is defined, GNU CC will turn on the +@samp{-fomit-frame-pointer} option whenever @samp{-O} is specified. +@end table + +@node Storage Layout +@section Storage Layout +@cindex storage layout + +Note that the definitions of the macros in this table which are sizes or +alignments measured in bits do not need to be constant. They can be C +expressions that refer to static variables, such as the @code{target_flags}. +@xref{Run-time Target}. + +@table @code +@findex BITS_BIG_ENDIAN +@item BITS_BIG_ENDIAN +Define this macro to be the value 1 if the most significant bit in a +byte has the lowest number; otherwise define it to be the value zero. +This means that bit-field instructions count from the most significant +bit. If the machine has no bit-field instructions, then this must still +be defined, but it doesn't matter which value it is defined to. + +This macro does not affect the way structure fields are packed into +bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}. + +@findex BYTES_BIG_ENDIAN +@item BYTES_BIG_ENDIAN +Define this macro to be 1 if the most significant byte in a word has the +lowest number. + +@findex WORDS_BIG_ENDIAN +@item WORDS_BIG_ENDIAN +Define this macro to be 1 if, in a multiword object, the most +significant word has the lowest number. This applies to both memory +locations and registers; GNU CC fundamentally assumes that the order of +words in memory is the same as the order in registers. + +@findex FLOAT_WORDS_BIG_ENDIAN +@item FLOAT_WORDS_BIG_ENDIAN +Define this macro to be 1 if @code{DFmode}, @code{XFmode} or +@code{TFmode} floating point numbers are stored in memory with the word +containing the sign bit at the lowest address; otherwise define it to be +0. + +You need not define this macro if the ordering is the same as for +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. + +@findex BITS_PER_WORD +@item BITS_PER_WORD +Number of bits in a word; normally 32. + +@findex MAX_BITS_PER_WORD +@item MAX_BITS_PER_WORD +Maximum number of bits in a word. If this is undefined, the default is +@code{BITS_PER_WORD}. Otherwise, it is the constant value that is the +largest value that @code{BITS_PER_WORD} can have at run-time. + +@findex UNITS_PER_WORD +@item UNITS_PER_WORD +Number of storage units in a word; normally 4. + +@findex MAX_UNITS_PER_WORD +@item MAX_UNITS_PER_WORD +Maximum number of units in a word. If this is undefined, the default is +@code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the +largest value that @code{UNITS_PER_WORD} can have at run-time. + +@findex POINTER_SIZE +@item POINTER_SIZE +Width of a pointer, in bits. + +@findex PROMOTE_MODE +@item PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type}) +A macro to update @var{m} and @var{unsignedp} when an object whose type +is @var{type} and which has the specified mode and signedness is to be +stored in a register. This macro is only called when @var{type} is a +scalar type. + +On most RISC machines, which only have operations that operate on a full +register, define this macro to set @var{m} to @code{word_mode} if +@var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most +cases, only integer modes should be widened because wider-precision +floating-point operations are usually more expensive than their narrower +counterparts. + +For most machines, the macro definition does not change @var{unsignedp}. +However, some machines, have instructions that preferentially handle +either signed or unsigned quantities of certain modes. For example, on +the DEC Alpha, 32-bit loads from memory and 32-bit add instructions +sign-extend the result to 64 bits. On such machines, set +@var{unsignedp} according to which kind of extension is more efficient. + +Do not define this macro if it would never modify @var{m}. + +@findex PROMOTE_FUNCTION_ARGS +@item PROMOTE_FUNCTION_ARGS +Define this macro if the promotion described by @code{PROMOTE_MODE} +should also be done for outgoing function arguments. + +@findex PROMOTE_FUNCTION_RETURN +@item PROMOTE_FUNCTION_RETURN +Define this macro if the promotion described by @code{PROMOTE_MODE} +should also be done for the return value of functions. + +If this macro is defined, @code{FUNCTION_VALUE} must perform the same +promotions done by @code{PROMOTE_MODE}. + +@findex PROMOTE_FOR_CALL_ONLY +@item PROMOTE_FOR_CALL_ONLY +Define this macro if the promotion described by @code{PROMOTE_MODE} +should @emph{only} be performed for outgoing function arguments or +function return values, as specified by @code{PROMOTE_FUNCTION_ARGS} +and @code{PROMOTE_FUNCTION_RETURN}, respectively. + +@findex PARM_BOUNDARY +@item PARM_BOUNDARY +Normal alignment required for function parameters on the stack, in +bits. All stack parameters receive at least this much alignment +regardless of data type. On most machines, this is the same as the +size of an integer. + +@findex STACK_BOUNDARY +@item STACK_BOUNDARY +Define this macro if you wish to preserve a certain alignment for +the stack pointer. The definition is a C expression +for the desired alignment (measured in bits). + +@cindex @code{PUSH_ROUNDING}, interaction with @code{STACK_BOUNDARY} +If @code{PUSH_ROUNDING} is not defined, the stack will always be aligned +to the specified boundary. If @code{PUSH_ROUNDING} is defined and specifies a +less strict alignment than @code{STACK_BOUNDARY}, the stack may be +momentarily unaligned while pushing arguments. + +@findex FUNCTION_BOUNDARY +@item FUNCTION_BOUNDARY +Alignment required for a function entry point, in bits. + +@findex BIGGEST_ALIGNMENT +@item BIGGEST_ALIGNMENT +Biggest alignment that any data type can require on this machine, in bits. + +@findex BIGGEST_FIELD_ALIGNMENT +@item BIGGEST_FIELD_ALIGNMENT +Biggest alignment that any structure field can require on this machine, +in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for +structure fields only. + +@findex MAX_OFILE_ALIGNMENT +@item MAX_OFILE_ALIGNMENT +Biggest alignment supported by the object file format of this machine. +Use this macro to limit the alignment which can be specified using the +@code{__attribute__ ((aligned (@var{n})))} construct. If not defined, +the default value is @code{BIGGEST_ALIGNMENT}. + +@findex DATA_ALIGNMENT +@item DATA_ALIGNMENT (@var{type}, @var{basic-align}) +If defined, a C expression to compute the alignment for a static +variable. @var{type} is the data type, and @var{basic-align} is the +alignment that the object would ordinarily have. The value of this +macro is used instead of that alignment to align the object. + +If this macro is not defined, then @var{basic-align} is used. + +@findex strcpy +One use of this macro is to increase alignment of medium-size data to +make it all fit in fewer cache lines. Another is to cause character +arrays to be word-aligned so that @code{strcpy} calls that copy +constants to character arrays can be done inline. + +@findex CONSTANT_ALIGNMENT +@item CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align}) +If defined, a C expression to compute the alignment given to a constant +that is being placed in memory. @var{constant} is the constant and +@var{basic-align} is the alignment that the object would ordinarily +have. The value of this macro is used instead of that alignment to +align the object. + +If this macro is not defined, then @var{basic-align} is used. + +The typical use of this macro is to increase alignment for string +constants to be word aligned so that @code{strcpy} calls that copy +constants can be done inline. + +@findex EMPTY_FIELD_BOUNDARY +@item EMPTY_FIELD_BOUNDARY +Alignment in bits to be given to a structure bit field that follows an +empty field such as @code{int : 0;}. + +Note that @code{PCC_BITFIELD_TYPE_MATTERS} also affects the alignment +that results from an empty field. + +@findex STRUCTURE_SIZE_BOUNDARY +@item STRUCTURE_SIZE_BOUNDARY +Number of bits which any structure or union's size must be a multiple of. +Each structure or union's size is rounded up to a multiple of this. + +If you do not define this macro, the default is the same as +@code{BITS_PER_UNIT}. + +@findex STRICT_ALIGNMENT +@item STRICT_ALIGNMENT +Define this macro to be the value 1 if instructions will fail to work +if given data not on the nominal alignment. If instructions will merely +go slower in that case, define this macro as 0. + +@findex PCC_BITFIELD_TYPE_MATTERS +@item PCC_BITFIELD_TYPE_MATTERS +Define this if you wish to imitate the way many other C compilers handle +alignment of bitfields and the structures that contain them. + +The behavior is that the type written for a bitfield (@code{int}, +@code{short}, or other integer type) imposes an alignment for the +entire structure, as if the structure really did contain an ordinary +field of that type. In addition, the bitfield is placed within the +structure so that it would fit within such a field, not crossing a +boundary for it. + +Thus, on most machines, a bitfield whose type is written as @code{int} +would not cross a four-byte boundary, and would force four-byte +alignment for the whole structure. (The alignment used may not be four +bytes; it is controlled by the other alignment parameters.) + +If the macro is defined, its definition should be a C expression; +a nonzero value for the expression enables this behavior. + +Note that if this macro is not defined, or its value is zero, some +bitfields may cross more than one alignment boundary. The compiler can +support such references if there are @samp{insv}, @samp{extv}, and +@samp{extzv} insns that can directly reference memory. + +The other known way of making bitfields work is to define +@code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}. +Then every structure can be accessed with fullwords. + +Unless the machine has bitfield instructions or you define +@code{STRUCTURE_SIZE_BOUNDARY} that way, you must define +@code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value. + +If your aim is to make GNU CC use the same conventions for laying out +bitfields as are used by another compiler, here is how to investigate +what the other compiler does. Compile and run this program: + +@example +struct foo1 +@{ + char x; + char :0; + char y; +@}; + +struct foo2 +@{ + char x; + int :0; + char y; +@}; + +main () +@{ + printf ("Size of foo1 is %d\n", + sizeof (struct foo1)); + printf ("Size of foo2 is %d\n", + sizeof (struct foo2)); + exit (0); +@} +@end example + +If this prints 2 and 5, then the compiler's behavior is what you would +get from @code{PCC_BITFIELD_TYPE_MATTERS}. + +@findex BITFIELD_NBYTES_LIMITED +@item BITFIELD_NBYTES_LIMITED +Like PCC_BITFIELD_TYPE_MATTERS except that its effect is limited to +aligning a bitfield within the structure. + +@findex ROUND_TYPE_SIZE +@item ROUND_TYPE_SIZE (@var{struct}, @var{size}, @var{align}) +Define this macro as an expression for the overall size of a structure +(given by @var{struct} as a tree node) when the size computed from the +fields is @var{size} and the alignment is @var{align}. + +The default is to round @var{size} up to a multiple of @var{align}. + +@findex ROUND_TYPE_ALIGN +@item ROUND_TYPE_ALIGN (@var{struct}, @var{computed}, @var{specified}) +Define this macro as an expression for the alignment of a structure +(given by @var{struct} as a tree node) if the alignment computed in the +usual way is @var{computed} and the alignment explicitly specified was +@var{specified}. + +The default is to use @var{specified} if it is larger; otherwise, use +the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT} + +@findex MAX_FIXED_MODE_SIZE +@item MAX_FIXED_MODE_SIZE +An integer expression for the size in bits of the largest integer +machine mode that should actually be used. All integer machine modes of +this size or smaller can be used for structures and unions with the +appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE +(DImode)} is assumed. + +@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. +There are three defined values: + +@table @code +@findex IEEE_FLOAT_FORMAT +@item IEEE_FLOAT_FORMAT +This code indicates IEEE floating point. It is the default; there is no +need to define this macro when the format is IEEE. + +@findex VAX_FLOAT_FORMAT +@item VAX_FLOAT_FORMAT +This code indicates the peculiar format used on the Vax. + +@findex UNKNOWN_FLOAT_FORMAT +@item UNKNOWN_FLOAT_FORMAT +This code indicates any other format. +@end table + +The value of this macro is compared with @code{HOST_FLOAT_FORMAT} +(@pxref{Config}) to determine whether the target machine has the same +format as the host machine. 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} for the target +machine and @code{HOST_FLOAT_WORDS_BIG_ENDIAN} for the host. +@end table + +@node Type Layout +@section Layout of Source Language Data Types + +These macros define the sizes and other characteristics of the standard +basic data types used in programs being compiled. Unlike the macros in +the previous section, these apply to specific features of C and related +languages, rather than to fundamental aspects of storage layout. + +@table @code +@findex INT_TYPE_SIZE +@item INT_TYPE_SIZE +A C expression for the size in bits of the type @code{int} on the +target machine. If you don't define this, the default is one word. + +@findex MAX_INT_TYPE_SIZE +@item MAX_INT_TYPE_SIZE +Maximum number for the size in bits of the type @code{int} on the target +machine. If this is undefined, the default is @code{INT_TYPE_SIZE}. +Otherwise, it is the constant value that is the largest value that +@code{INT_TYPE_SIZE} can have at run-time. This is used in @code{cpp}. + +@findex SHORT_TYPE_SIZE +@item SHORT_TYPE_SIZE +A C expression for the size in bits of the type @code{short} on the +target machine. If you don't define this, the default is half a word. +(If this would be less than one storage unit, it is rounded up to one +unit.) + +@findex LONG_TYPE_SIZE +@item LONG_TYPE_SIZE +A C expression for the size in bits of the type @code{long} on the +target machine. If you don't define this, the default is one word. + +@findex MAX_LONG_TYPE_SIZE +@item MAX_LONG_TYPE_SIZE +Maximum number for the size in bits of the type @code{long} on the +target machine. If this is undefined, the default is +@code{LONG_TYPE_SIZE}. Otherwise, it is the constant value that is the +largest value that @code{LONG_TYPE_SIZE} can have at run-time. This is +used in @code{cpp}. + +@findex LONG_LONG_TYPE_SIZE +@item LONG_LONG_TYPE_SIZE +A C expression for the size in bits of the type @code{long long} on the +target machine. If you don't define this, the default is two +words. + +@findex CHAR_TYPE_SIZE +@item CHAR_TYPE_SIZE +A C expression for the size in bits of the type @code{char} on the +target machine. If you don't define this, the default is one quarter +of a word. (If this would be less than one storage unit, it is rounded up +to one unit.) + +@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 FLOAT_TYPE_SIZE +@item FLOAT_TYPE_SIZE +A C expression for the size in bits of the type @code{float} on the +target machine. If you don't define this, the default is one word. + +@findex DOUBLE_TYPE_SIZE +@item DOUBLE_TYPE_SIZE +A C expression for the size in bits of the type @code{double} on the +target machine. If you don't define this, the default is two +words. + +@findex LONG_DOUBLE_TYPE_SIZE +@item LONG_DOUBLE_TYPE_SIZE +A C expression for the size in bits of the type @code{long double} on +the target machine. If you don't define this, the default is two +words. + +@findex DEFAULT_SIGNED_CHAR +@item DEFAULT_SIGNED_CHAR +An expression whose value is 1 or 0, according to whether the type +@code{char} should be signed or unsigned by default. The user can +always override this default with the options @samp{-fsigned-char} +and @samp{-funsigned-char}. + +@findex DEFAULT_SHORT_ENUMS +@item DEFAULT_SHORT_ENUMS +A C expression to determine whether to give an @code{enum} type +only as many bytes as it takes to represent the range of possible values +of that type. A nonzero value means to do that; a zero value means all +@code{enum} types should be allocated like @code{int}. + +If you don't define the macro, the default is 0. + +@findex SIZE_TYPE +@item SIZE_TYPE +A C expression for a string describing the name of the data type to use +for size values. The typedef name @code{size_t} is defined using the +contents of the string. + +The string can contain more than one keyword. If so, separate them with +spaces, and write first any length keyword, then @code{unsigned} if +appropriate, and finally @code{int}. The string must exactly match one +of the data type names defined in the function +@code{init_decl_processing} in the file @file{c-decl.c}. You may not +omit @code{int} or change the order---that would cause the compiler to +crash on startup. + +If you don't define this macro, the default is @code{"long unsigned +int"}. + +@findex PTRDIFF_TYPE +@item PTRDIFF_TYPE +A C expression for a string describing the name of the data type to use +for the result of subtracting two pointers. The typedef name +@code{ptrdiff_t} is defined using the contents of the string. See +@code{SIZE_TYPE} above for more information. + +If you don't define this macro, the default is @code{"long int"}. + +@findex WCHAR_TYPE +@item WCHAR_TYPE +A C expression for a string describing the name of the data type to use +for wide characters. The typedef name @code{wchar_t} is defined using +the contents of the string. See @code{SIZE_TYPE} above for more +information. + +If you don't define this macro, the default is @code{"int"}. + +@findex WCHAR_TYPE_SIZE +@item WCHAR_TYPE_SIZE +A C expression for the size in bits of the data type for wide +characters. This is used in @code{cpp}, which cannot make use of +@code{WCHAR_TYPE}. + +@findex MAX_WCHAR_TYPE_SIZE +@item MAX_WCHAR_TYPE_SIZE +Maximum number for the size in bits of the data type for wide +characters. If this is undefined, the default is +@code{WCHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the +largest value that @code{WCHAR_TYPE_SIZE} can have at run-time. This is +used in @code{cpp}. + +@findex OBJC_INT_SELECTORS +@item OBJC_INT_SELECTORS +Define this macro if the type of Objective C selectors should be +@code{int}. + +If this macro is not defined, then selectors should have the type +@code{struct objc_selector *}. + +@findex OBJC_SELECTORS_WITHOUT_LABELS +@item OBJC_SELECTORS_WITHOUT_LABELS +Define this macro if the compiler can group all the selectors together +into a vector and use just one label at the beginning of the vector. +Otherwise, the compiler must give each selector its own assembler +label. + +On certain machines, it is important to have a separate label for each +selector because this enables the linker to eliminate duplicate selectors. + +@findex TARGET_BELL +@item TARGET_BELL +A C constant expression for the integer value for escape sequence +@samp{\a}. + +@findex TARGET_TAB +@findex TARGET_BS +@findex TARGET_NEWLINE +@item TARGET_BS +@itemx TARGET_TAB +@itemx TARGET_NEWLINE +C constant expressions for the integer values for escape sequences +@samp{\b}, @samp{\t} and @samp{\n}. + +@findex TARGET_VT +@findex TARGET_FF +@findex TARGET_CR +@item TARGET_VT +@itemx TARGET_FF +@itemx TARGET_CR +C constant expressions for the integer values for escape sequences +@samp{\v}, @samp{\f} and @samp{\r}. +@end table + +@node Registers +@section Register Usage +@cindex register usage + +This section explains how to describe what registers the target machine +has, and how (in general) they can be used. + +The description of which registers a specific instruction can use is +done with register classes; see @ref{Register Classes}. For information +on using registers to access a stack frame, see @ref{Frame Registers}. +For passing values in registers, see @ref{Register Arguments}. +For returning values in registers, see @ref{Scalar Return}. + +@menu +* Register Basics:: Number and kinds of registers. +* Allocation Order:: Order in which registers are allocated. +* Values in Registers:: What kinds of values each reg can hold. +* Leaf Functions:: Renumbering registers for leaf functions. +* Stack Registers:: Handling a register stack such as 80387. +* Obsolete Register Macros:: Macros formerly used for the 80387. +@end menu + +@node Register Basics +@subsection Basic Characteristics of Registers + +@c prevent bad page break with this line +Registers have various characteristics. + +@table @code +@findex FIRST_PSEUDO_REGISTER +@item FIRST_PSEUDO_REGISTER +Number of hardware registers known to the compiler. They receive +numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first +pseudo register's number really is assigned the number +@code{FIRST_PSEUDO_REGISTER}. + +@item FIXED_REGISTERS +@findex FIXED_REGISTERS +@cindex fixed register +An initializer that says which registers are used for fixed purposes +all throughout the compiled code and are therefore not available for +general allocation. These would include the stack pointer, the frame +pointer (except on machines where that can be used as a general +register when no frame pointer is needed), the program counter on +machines where that is considered one of the addressable registers, +and any other numbered register with a standard use. + +This information is expressed as a sequence of numbers, separated by +commas and surrounded by braces. The @var{n}th number is 1 if +register @var{n} is fixed, 0 otherwise. + +The table initialized from this macro, and the table initialized by +the following one, may be overridden at run time either automatically, +by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by +the user with the command options @samp{-ffixed-@var{reg}}, +@samp{-fcall-used-@var{reg}} and @samp{-fcall-saved-@var{reg}}. + +@findex CALL_USED_REGISTERS +@item CALL_USED_REGISTERS +@cindex call-used register +@cindex call-clobbered register +@cindex call-saved register +Like @code{FIXED_REGISTERS} but has 1 for each register that is +clobbered (in general) by function calls as well as for fixed +registers. This macro therefore identifies the registers that are not +available for general allocation of values that must live across +function calls. + +If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler +automatically saves it on function entry and restores it on function +exit, if the register is used within the function. + +@findex CONDITIONAL_REGISTER_USAGE +@findex fixed_regs +@findex call_used_regs +@item CONDITIONAL_REGISTER_USAGE +Zero or more C statements that may conditionally modify two variables +@code{fixed_regs} and @code{call_used_regs} (both of type @code{char +[]}) after they have been initialized from the two preceding macros. + +This is necessary in case the fixed or call-clobbered registers depend +on target flags. + +You need not define this macro if it has no work to do. + +@cindex disabling certain registers +@cindex controlling register usage +If the usage of an entire class of registers depends on the target +flags, you may indicate this to GCC by using this macro to modify +@code{fixed_regs} and @code{call_used_regs} to 1 for each of the +registers in the classes which should not be used by GCC. Also define +the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it +is called with a letter for a class that shouldn't be used. + +(However, if this class is not included in @code{GENERAL_REGS} and all +of the insn patterns whose constraints permit this class are +controlled by target switches, then GCC will automatically avoid using +these registers when the target switches are opposed to them.) + +@findex NON_SAVING_SETJMP +@item NON_SAVING_SETJMP +If this macro is defined and has a nonzero value, it means that +@code{setjmp} and related functions fail to save the registers, or that +@code{longjmp} fails to restore them. To compensate, the compiler +avoids putting variables in registers in functions that use +@code{setjmp}. + +@findex INCOMING_REGNO +@item INCOMING_REGNO (@var{out}) +Define this macro if the target machine has register windows. This C +expression returns the register number as seen by the called function +corresponding to the register number @var{out} as seen by the calling +function. Return @var{out} if register number @var{out} is not an +outbound register. + +@findex OUTGOING_REGNO +@item OUTGOING_REGNO (@var{in}) +Define this macro if the target machine has register windows. This C +expression returns the register number as seen by the calling function +corresponding to the register number @var{in} as seen by the called +function. Return @var{in} if register number @var{in} is not an inbound +register. + +@ignore +@findex PC_REGNUM +@item PC_REGNUM +If the program counter has a register number, define this as that +register number. Otherwise, do not define it. +@end ignore +@end table + +@node Allocation Order +@subsection Order of Allocation of Registers +@cindex order of register allocation +@cindex register allocation order + +@c prevent bad page break with this line +Registers are allocated in order. + +@table @code +@findex REG_ALLOC_ORDER +@item REG_ALLOC_ORDER +If defined, an initializer for a vector of integers, containing the +numbers of hard registers in the order in which GNU CC should prefer +to use them (from most preferred to least). + +If this macro is not defined, registers are used lowest numbered first +(all else being equal). + +One use of this macro is on machines where the highest numbered +registers must always be saved and the save-multiple-registers +instruction supports only sequences of consecutive registers. On such +machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists +the highest numbered allocatable register first. + +@findex ORDER_REGS_FOR_LOCAL_ALLOC +@item ORDER_REGS_FOR_LOCAL_ALLOC +A C statement (sans semicolon) to choose the order in which to allocate +hard registers for pseudo-registers local to a basic block. + +Store the desired register order in the array @code{reg_alloc_order}. +Element 0 should be the register to allocate first; element 1, the next +register; and so on. + +The macro body should not assume anything about the contents of +@code{reg_alloc_order} before execution of the macro. + +On most machines, it is not necessary to define this macro. +@end table + +@node Values in Registers +@subsection How Values Fit in Registers + +This section discusses the macros that describe which kinds of values +(specifically, which machine modes) each register can hold, and how many +consecutive registers are needed for a given mode. + +@table @code +@findex HARD_REGNO_NREGS +@item HARD_REGNO_NREGS (@var{regno}, @var{mode}) +A C expression for the number of consecutive hard registers, starting +at register number @var{regno}, required to hold a value of mode +@var{mode}. + +On a machine where all registers are exactly one word, a suitable +definition of this macro is + +@smallexample +#define HARD_REGNO_NREGS(REGNO, MODE) \ + ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \ + / UNITS_PER_WORD)) +@end smallexample + +@findex HARD_REGNO_MODE_OK +@item HARD_REGNO_MODE_OK (@var{regno}, @var{mode}) +A C expression that is nonzero if it is permissible to store a value +of mode @var{mode} in hard register number @var{regno} (or in several +registers starting with that one). For a machine where all registers +are equivalent, a suitable definition is + +@smallexample +#define HARD_REGNO_MODE_OK(REGNO, MODE) 1 +@end smallexample + +It is not necessary for this macro to check for the numbers of fixed +registers, because the allocation mechanism considers them to be always +occupied. + +@cindex register pairs +On some machines, double-precision values must be kept in even/odd +register pairs. The way to implement that is to define this macro +to reject odd register numbers for such modes. + +@ignore +@c I think this is not true now +GNU CC assumes that it can always move values between registers and +(suitably addressed) memory locations. If it is impossible to move a +value of a certain mode between memory and certain registers, then +@code{HARD_REGNO_MODE_OK} must not allow this mode in those registers. +@end ignore + +The minimum requirement for a mode to be OK in a register is that the +@samp{mov@var{mode}} instruction pattern support moves between the +register and any other hard register for which the mode is OK; and that +moving a value into the register and back out not alter it. + +Since the same instruction used to move @code{SImode} will work for all +narrower integer modes, it is not necessary on any machine for +@code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided +you define patterns @samp{movhi}, etc., to take advantage of this. This +is useful because of the interaction between @code{HARD_REGNO_MODE_OK} +and @code{MODES_TIEABLE_P}; it is very desirable for all integer modes +to be tieable. + +Many machines have special registers for floating point arithmetic. +Often people assume that floating point machine modes are allowed only +in floating point registers. This is not true. Any registers that +can hold integers can safely @emph{hold} a floating point machine +mode, whether or not floating arithmetic can be done on it in those +registers. Integer move instructions can be used to move the values. + +On some machines, though, the converse is true: fixed-point machine +modes may not go in floating registers. This is true if the floating +registers normalize any value stored in them, because storing a +non-floating value there would garble it. In this case, +@code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in +floating registers. But if the floating registers do not automatically +normalize, if you can store any bit pattern in one and retrieve it +unchanged without a trap, then any machine mode may go in a floating +register, so you can define this macro to say so. + +The primary significance of special floating registers is rather that +they are the registers acceptable in floating point arithmetic +instructions. However, this is of no concern to +@code{HARD_REGNO_MODE_OK}. You handle it by writing the proper +constraints for those instructions. + +On some machines, the floating registers are especially slow to access, +so that it is better to store a value in a stack frame than in such a +register if floating point arithmetic is not being done. As long as the +floating registers are not in class @code{GENERAL_REGS}, they will not +be used unless some pattern's constraint asks for one. + +@findex MODES_TIEABLE_P +@item MODES_TIEABLE_P (@var{mode1}, @var{mode2}) +A C expression that is nonzero if it is desirable to choose register +allocation so as to avoid move instructions between a value of mode +@var{mode1} and a value of mode @var{mode2}. + +If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and +@code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different +for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, +@var{mode2})} must be zero. +@end table + +@node Leaf Functions +@subsection Handling Leaf Functions + +@cindex leaf functions +@cindex functions, leaf +On some machines, a leaf function (i.e., one which makes no calls) can run +more efficiently if it does not make its own register window. Often this +means it is required to receive its arguments in the registers where they +are passed by the caller, instead of the registers where they would +normally arrive. + +The special treatment for leaf functions generally applies only when +other conditions are met; for example, often they may use only those +registers for its own variables and temporaries. We use the term ``leaf +function'' to mean a function that is suitable for this special +handling, so that functions with no calls are not necessarily ``leaf +functions''. + +GNU CC assigns register numbers before it knows whether the function is +suitable for leaf function treatment. So it needs to renumber the +registers in order to output a leaf function. The following macros +accomplish this. + +@table @code +@findex LEAF_REGISTERS +@item LEAF_REGISTERS +A C initializer for a vector, indexed by hard register number, which +contains 1 for a register that is allowable in a candidate for leaf +function treatment. + +If leaf function treatment involves renumbering the registers, then the +registers marked here should be the ones before renumbering---those that +GNU CC would ordinarily allocate. The registers which will actually be +used in the assembler code, after renumbering, should not be marked with 1 +in this vector. + +Define this macro only if the target machine offers a way to optimize +the treatment of leaf functions. + +@findex LEAF_REG_REMAP +@item LEAF_REG_REMAP (@var{regno}) +A C expression whose value is the register number to which @var{regno} +should be renumbered, when a function is treated as a leaf function. + +If @var{regno} is a register number which should not appear in a leaf +function before renumbering, then the expression should yield -1, which +will cause the compiler to abort. + +Define this macro only if the target machine offers a way to optimize the +treatment of leaf functions, and registers need to be renumbered to do +this. +@end table + +@findex leaf_function +Normally, @code{FUNCTION_PROLOGUE} and @code{FUNCTION_EPILOGUE} must +treat leaf functions specially. It can test the C variable +@code{leaf_function} which is nonzero for leaf functions. (The variable +@code{leaf_function} is defined only if @code{LEAF_REGISTERS} is +defined.) +@c changed this to fix overfull. ALSO: why the "it" at the beginning +@c of the next paragraph?! --mew 2feb93 + +@node Stack Registers +@subsection Registers That Form a Stack + +There are special features to handle computers where some of the +``registers'' form a stack, as in the 80387 coprocessor for the 80386. +Stack registers are normally written by pushing onto the stack, and are +numbered relative to the top of the stack. + +Currently, GNU CC can only handle one group of stack-like registers, and +they must be consecutively numbered. + +@table @code +@findex STACK_REGS +@item STACK_REGS +Define this if the machine has any stack-like registers. + +@findex FIRST_STACK_REG +@item FIRST_STACK_REG +The number of the first stack-like register. This one is the top +of the stack. + +@findex LAST_STACK_REG +@item LAST_STACK_REG +The number of the last stack-like register. This one is the bottom of +the stack. +@end table + +@node Obsolete Register Macros +@subsection Obsolete Macros for Controlling Register Usage + +These features do not work very well. They exist because they used to +be required to generate correct code for the 80387 coprocessor of the +80386. They are no longer used by that machine description and may be +removed in a later version of the compiler. Don't use them! + +@table @code +@findex OVERLAPPING_REGNO_P +@item OVERLAPPING_REGNO_P (@var{regno}) +If defined, this is a C expression whose value is nonzero if hard +register number @var{regno} is an overlapping register. This means a +hard register which overlaps a hard register with a different number. +(Such overlap is undesirable, but occasionally it allows a machine to +be supported which otherwise could not be.) This macro must return +nonzero for @emph{all} the registers which overlap each other. GNU CC +can use an overlapping register only in certain limited ways. It can +be used for allocation within a basic block, and may be spilled for +reloading; that is all. + +If this macro is not defined, it means that none of the hard registers +overlap each other. This is the usual situation. + +@findex INSN_CLOBBERS_REGNO_P +@item INSN_CLOBBERS_REGNO_P (@var{insn}, @var{regno}) +If defined, this is a C expression whose value should be nonzero if +the insn @var{insn} has the effect of mysteriously clobbering the +contents of hard register number @var{regno}. By ``mysterious'' we +mean that the insn's RTL expression doesn't describe such an effect. + +If this macro is not defined, it means that no insn clobbers registers +mysteriously. This is the usual situation; all else being equal, +it is best for the RTL expression to show all the activity. + +@cindex death notes +@findex PRESERVE_DEATH_INFO_REGNO_P +@item PRESERVE_DEATH_INFO_REGNO_P (@var{regno}) +If defined, this is a C expression whose value is nonzero if accurate +@code{REG_DEAD} notes are needed for hard register number @var{regno} +at the time of outputting the assembler code. When this is so, a few +optimizations that take place after register allocation and could +invalidate the death notes are not done when this register is +involved. + +You would arrange to preserve death info for a register when some of the +code in the machine description which is executed to write the assembler +code looks at the death notes. This is necessary only when the actual +hardware feature which GNU CC thinks of as a register is not actually a +register of the usual sort. (It might, for example, be a hardware +stack.) + +If this macro is not defined, it means that no death notes need to be +preserved. This is the usual situation. +@end table + +@node Register Classes +@section Register Classes +@cindex register class definitions +@cindex class definitions, register + +On many machines, the numbered registers are not all equivalent. +For example, certain registers may not be allowed for indexed addressing; +certain registers may not be allowed in some instructions. These machine +restrictions are described to the compiler using @dfn{register classes}. + +You define a number of register classes, giving each one a name and saying +which of the registers belong to it. Then you can specify register classes +that are allowed as operands to particular instruction patterns. + +@findex ALL_REGS +@findex NO_REGS +In general, each register will belong to several classes. In fact, one +class must be named @code{ALL_REGS} and contain all the registers. Another +class must be named @code{NO_REGS} and contain no registers. Often the +union of two classes will be another class; however, this is not required. + +@findex GENERAL_REGS +One of the classes must be named @code{GENERAL_REGS}. There is nothing +terribly special about the name, but the operand constraint letters +@samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is +the same as @code{ALL_REGS}, just define it as a macro which expands +to @code{ALL_REGS}. + +Order the classes so that if class @var{x} is contained in class @var{y} +then @var{x} has a lower class number than @var{y}. + +The way classes other than @code{GENERAL_REGS} are specified in operand +constraints is through machine-dependent operand constraint letters. +You can define such letters to correspond to various classes, then use +them in operand constraints. + +You should define a class for the union of two classes whenever some +instruction allows both classes. For example, if an instruction allows +either a floating point (coprocessor) register or a general register for a +certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS} +which includes both of them. Otherwise you will get suboptimal code. + +You must also specify certain redundant information about the register +classes: for each class, which classes contain it and which ones are +contained in it; for each pair of classes, the largest class contained +in their union. + +When a value occupying several consecutive registers is expected in a +certain class, all the registers used must belong to that class. +Therefore, register classes cannot be used to enforce a requirement for +a register pair to start with an even-numbered register. The way to +specify this requirement is with @code{HARD_REGNO_MODE_OK}. + +Register classes used for input-operands of bitwise-and or shift +instructions have a special requirement: each such class must have, for +each fixed-point machine mode, a subclass whose registers can transfer that +mode to or from memory. For example, on some machines, the operations for +single-byte values (@code{QImode}) are limited to certain registers. When +this is so, each register class that is used in a bitwise-and or shift +instruction must have a subclass consisting of registers from which +single-byte values can be loaded or stored. This is so that +@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. + +@table @code +@findex enum reg_class +@item enum reg_class +An enumeral type that must be defined with all the register class names +as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS} +must be the last register class, followed by one more enumeral value, +@code{LIM_REG_CLASSES}, which is not a register class but rather +tells how many classes there are. + +Each register class has a number, which is the value of casting +the class name to type @code{int}. The number serves as an index +in many of the tables described below. + +@findex N_REG_CLASSES +@item N_REG_CLASSES +The number of distinct register classes, defined as follows: + +@example +#define N_REG_CLASSES (int) LIM_REG_CLASSES +@end example + +@findex REG_CLASS_NAMES +@item REG_CLASS_NAMES +An initializer containing the names of the register classes as C string +constants. These names are used in writing some of the debugging dumps. + +@findex REG_CLASS_CONTENTS +@item REG_CLASS_CONTENTS +An initializer containing the contents of the register classes, as integers +which are bit masks. The @var{n}th integer specifies the contents of class +@var{n}. The way the integer @var{mask} is interpreted is that +register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1. + +When the machine has more than 32 registers, an integer does not suffice. +Then the integers are replaced by sub-initializers, braced groupings containing +several integers. Each sub-initializer must be suitable as an initializer +for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}. + +@findex REGNO_REG_CLASS +@item REGNO_REG_CLASS (@var{regno}) +A C expression whose value is a register class containing hard register +@var{regno}. In general there is more than one such class; choose a class +which is @dfn{minimal}, meaning that no smaller class also contains the +register. + +@findex BASE_REG_CLASS +@item BASE_REG_CLASS +A macro whose definition is the name of the class to which a valid +base register must belong. A base register is one used in an address +which is the register value plus a displacement. + +@findex INDEX_REG_CLASS +@item INDEX_REG_CLASS +A macro whose definition is the name of the class to which a valid +index register must belong. An index register is one used in an +address where its value is either multiplied by a scale factor or +added to another register (as well as added to a displacement). + +@findex REG_CLASS_FROM_LETTER +@item REG_CLASS_FROM_LETTER (@var{char}) +A C expression which defines the machine-dependent operand constraint +letters for register classes. If @var{char} is such a letter, the +value should be the register class corresponding to it. Otherwise, +the value should be @code{NO_REGS}. The register letter @samp{r}, +corresponding to class @code{GENERAL_REGS}, will not be passed +to this macro; you do not need to handle it. + +@findex REGNO_OK_FOR_BASE_P +@item REGNO_OK_FOR_BASE_P (@var{num}) +A C expression which is nonzero if register number @var{num} is +suitable for use as a base register in operand addresses. It may be +either a suitable hard register or a pseudo register that has been +allocated such a hard register. + +@findex REGNO_OK_FOR_INDEX_P +@item REGNO_OK_FOR_INDEX_P (@var{num}) +A C expression which is nonzero if register number @var{num} is +suitable for use as an index register in operand addresses. It may be +either a suitable hard register or a pseudo register that has been +allocated such a hard register. + +The difference between an index register and a base register is that +the index register may be scaled. If an address involves the sum of +two registers, neither one of them scaled, then either one may be +labeled the ``base'' and the other the ``index''; but whichever +labeling is used must fit the machine's constraints of which registers +may serve in each capacity. The compiler will try both labelings, +looking for one that is valid, and will reload one or both registers +only if neither labeling works. + +@findex PREFERRED_RELOAD_CLASS +@item PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) +A C expression that places additional restrictions on the register class +to use when it is necessary to copy value @var{x} into a register in class +@var{class}. The value is a register class; perhaps @var{class}, or perhaps +another, smaller class. On many machines, the following definition is +safe: + +@example +#define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS +@end example + +Sometimes returning a more restrictive class makes better code. For +example, on the 68000, when @var{x} is an integer constant that is in range +for a @samp{moveq} instruction, the value of this macro is always +@code{DATA_REGS} as long as @var{class} includes the data registers. +Requiring a data register guarantees that a @samp{moveq} will be used. + +If @var{x} is a @code{const_double}, by returning @code{NO_REGS} +you can force @var{x} into a memory constant. This is useful on +certain machines where immediate floating values cannot be loaded into +certain kinds of registers. + +@findex PREFERRED_OUTPUT_RELOAD_CLASS +@item PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class}) +Like @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of +input reloads. If you don't define this macro, the default is to use +@var{class}, unchanged. + +@findex LIMIT_RELOAD_CLASS +@item LIMIT_RELOAD_CLASS (@var{mode}, @var{class}) +A C expression that places additional restrictions on the register class +to use when it is necessary to be able to hold a value of mode +@var{mode} in a reload register for which class @var{class} would +ordinarily be used. + +Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when +there are certain modes that simply can't go in certain reload classes. + +The value is a register class; perhaps @var{class}, or perhaps another, +smaller class. + +Don't define this macro unless the target machine has limitations which +require the macro to do something nontrivial. + +@findex SECONDARY_RELOAD_CLASS +@findex SECONDARY_INPUT_RELOAD_CLASS +@findex SECONDARY_OUTPUT_RELOAD_CLASS +@item SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) +@itemx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) +@itemx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x}) +Many machines have some registers that cannot be copied directly to or +from memory or even from other types of registers. An example is the +@samp{MQ} register, which on most machines, can only be copied to or +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 +PIC). In some cases, both an intermediate and a scratch register are +required. + +You should define these macros to indicate to the reload phase that it may +need to allocate at least one register for a reload in addition to the +register to contain the data. Specifically, if copying @var{x} to a +register @var{class} in @var{mode} requires an intermediate register, +you should define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the +largest register class all of whose registers can be used as +intermediate registers or scratch registers. + +If copying a register @var{class} in @var{mode} to @var{x} requires an +intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS} +should be defined to return the largest register class required. If the +requirements for input and output reloads are the same, the macro +@code{SECONDARY_RELOAD_CLASS} should be used instead of defining both +macros identically. + +The values returned by these macros are often @code{GENERAL_REGS}. +Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x} +can be directly copied to or from a register of @var{class} in +@var{mode} without requiring a scratch register. Do not define this +macro if it would always return @code{NO_REGS}. + +If a scratch register is required (either with or without an +intermediate register), you should define patterns for +@samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required +(@pxref{Standard Names}. These patterns, which will normally be +implemented with a @code{define_expand}, should be similar to the +@samp{mov@var{m}} patterns, except that operand 2 is the scratch +register. + +Define constraints for the reload register and scratch register that +contain a single register class. If the original reload register (whose +class is @var{class}) can meet the constraint given in the pattern, the +value returned by these macros is used for the class of the scratch +register. Otherwise, two additional reload registers are required. +Their classes are obtained from the constraints in the insn pattern. + +@var{x} might be a pseudo-register or a @code{subreg} of a +pseudo-register, which could either be in a hard register or in memory. +Use @code{true_regnum} to find out; it will return -1 if the pseudo is +in memory and the hard register number if it is in a register. + +These macros should not be used in the case where a particular class of +registers can only be copied to memory and not to another class of +registers. In that case, secondary reload registers are not needed and +would not be helpful. Instead, a stack location must be used to perform +the copy and the @code{mov@var{m}} pattern should use memory as a +intermediate storage. This case often occurs between floating-point and +general registers. + +@findex SECONDARY_MEMORY_NEEDED +@item SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m}) +Certain machines have the property that some registers cannot be copied +to some other registers without using memory. Define this macro on +those machines to be a C expression that is non-zero if objects of mode +@var{m} in registers of @var{class1} can only be copied to registers of +class @var{class2} by storing a register of @var{class1} into memory +and loading that memory location into a register of @var{class2}. + +Do not define this macro if its value would always be zero. + +@findex SECONDARY_MEMORY_NEEDED_RTX +@item SECONDARY_MEMORY_NEEDED_RTX (@var{mode}) +Normally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler +allocates a stack slot for a memory location needed for register copies. +If this macro is defined, the compiler instead uses the memory location +defined by this macro. + +Do not define this macro if you do not define +@code{SECONDARY_MEMORY_NEEDED}. + +@findex SECONDARY_MEMORY_NEEDED_MODE +@item SECONDARY_MEMORY_NEEDED_MODE (@var{mode}) +When the compiler needs a secondary memory location to copy between two +registers of mode @var{mode}, it normally allocates sufficient memory to +hold a quantity of @code{BITS_PER_WORD} bits and performs the store and +load operations in a mode that many bits wide and whose class is the +same as that of @var{mode}. + +This is right thing to do on most machines because it ensures that all +bits of the register are copied and prevents accesses to the registers +in a narrower mode, which some machines prohibit for floating-point +registers. + +However, this default behavior is not correct on some machines, such as +the DEC Alpha, that store short integers in floating-point registers +differently than in integer registers. On those machines, the default +widening will not work correctly and you must define this macro to +suppress that widening in some cases. See the file @file{alpha.h} for +details. + +Do not define this macro if you do not define +@code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that +is @code{BITS_PER_WORD} bits wide is correct for your machine. + +@findex SMALL_REGISTER_CLASSES +@item SMALL_REGISTER_CLASSES +Normally the compiler avoids choosing registers that have been +explicitly mentioned in the rtl as spill registers (these registers are +normally those used to pass parameters and return values). However, +some machines have so few registers of certain classes that there +would not be enough registers to use as spill registers if this were +done. + +Define @code{SMALL_REGISTER_CLASSES} on these machines. When it is +defined, the compiler allows registers explicitly used in the rtl to be +used as spill registers but avoids extending the lifetime of these +registers. + +It is always safe to define this macro, but if you unnecessarily define +it, you will reduce the amount of optimizations that can be performed in +some cases. If you do not define this macro when it is required, the +compiler will run out of spill registers and print a fatal error +message. For most machines, you should not define this macro. + +@findex CLASS_LIKELY_SPILLED_P +@item CLASS_LIKELY_SPILLED_P (@var{class}) +A C expression whose value is nonzero if pseudos that have been assigned +to registers of class @var{class} would likely be spilled because +registers of @var{class} are needed for spill registers. + +The default value of this macro returns 1 if @var{class} has exactly one +register and zero otherwise. On most machines, this default should be +used. Only define this macro to some other expression if pseudo +allocated by @file{local-alloc.c} end up in memory because their hard +registers were needed for spill regisers. If this macro returns nonzero +for those classes, those pseudos will only be allocated by +@file{global.c}, which knows how to reallocate the pseudo to another +register. If there would not be another register available for +reallocation, you should not change the definition of this macro since +the only effect of such a definition would be to slow down register +allocation. + +@findex CLASS_MAX_NREGS +@item CLASS_MAX_NREGS (@var{class}, @var{mode}) +A C expression for the maximum number of consecutive registers +of class @var{class} needed to hold a value of mode @var{mode}. + +This is closely related to the macro @code{HARD_REGNO_NREGS}. In fact, +the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})} +should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, +@var{mode})} for all @var{regno} values in the class @var{class}. + +This macro helps control the handling of multiple-word values +in the reload pass. + +@item CLASS_CANNOT_CHANGE_SIZE +If defined, a C expression for a class that contains registers which the +compiler must always access in a mode that is the same size as the mode +in which it loaded the register, unless neither mode is integral. + +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 this macro as +@code{FLOAT_REGS}. +@end table + +Three other special macros describe which operands fit which constraint +letters. + +@table @code +@findex CONST_OK_FOR_LETTER_P +@item CONST_OK_FOR_LETTER_P (@var{value}, @var{c}) +A C expression that defines the machine-dependent operand constraint letters +that specify particular ranges of integer values. If @var{c} is one +of those letters, the expression should check that @var{value}, an integer, +is in the appropriate range and return 1 if so, 0 otherwise. If @var{c} is +not one of those letters, the value should be 0 regardless of @var{value}. + +@findex CONST_DOUBLE_OK_FOR_LETTER_P +@item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c}) +A C expression that defines the machine-dependent operand constraint +letters that specify particular ranges of @code{const_double} values. + +If @var{c} is one of those letters, the expression should check that +@var{value}, an RTX of code @code{const_double}, is in the appropriate +range and return 1 if so, 0 otherwise. If @var{c} is not one of those +letters, the value should be 0 regardless of @var{value}. + +@code{const_double} is used for all floating-point constants and for +@code{DImode} fixed-point constants. A given letter can accept either +or both kinds of values. It can use @code{GET_MODE} to distinguish +between these kinds. + +@findex EXTRA_CONSTRAINT +@item EXTRA_CONSTRAINT (@var{value}, @var{c}) +A C expression that defines the optional machine-dependent constraint +letters that can be used to segregate specific types of operands, +usually memory references, for the target machine. Normally this macro +will not be defined. If it is required for a particular target machine, +it should return 1 if @var{value} corresponds to the operand type +represented by the constraint letter @var{c}. If @var{c} is not defined +as an extra constraint, the value returned should be 0 regardless of +@var{value}. + +For example, on the ROMP, load instructions cannot have their output in r0 if +the memory reference contains a symbolic address. Constraint letter +@samp{Q} is defined as representing a memory address that does +@emph{not} contain a symbolic address. An alternative is specified with +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. +@end table + +@node Stack and Calling +@section Stack Layout and Calling Conventions +@cindex calling conventions + +@c prevent bad page break with this line +This describes the stack layout and calling conventions. + +@menu +* Frame Layout:: +* Frame Registers:: +* Elimination:: +* Stack Arguments:: +* Register Arguments:: +* Scalar Return:: +* Aggregate Return:: +* Caller Saves:: +* Function Entry:: +* Profiling:: +@end menu + +@node Frame Layout +@subsection Basic Stack Layout +@cindex stack frame layout +@cindex frame layout + +@c prevent bad page break with this line +Here is the basic stack layout. + +@table @code +@findex STACK_GROWS_DOWNWARD +@item STACK_GROWS_DOWNWARD +Define this macro if pushing a word onto the stack moves the stack +pointer to a smaller address. + +When we say, ``define this macro if @dots{},'' it means that the +compiler checks this macro only with @code{#ifdef} so the precise +definition used does not matter. + +@findex FRAME_GROWS_DOWNWARD +@item FRAME_GROWS_DOWNWARD +Define this macro if the addresses of local variable slots are at negative +offsets from the frame pointer. + +@findex ARGS_GROW_DOWNWARD +@item ARGS_GROW_DOWNWARD +Define this macro if successive arguments to a function occupy decreasing +addresses on the stack. + +@findex STARTING_FRAME_OFFSET +@item STARTING_FRAME_OFFSET +Offset from the frame pointer to the first local variable slot to be allocated. + +If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by +subtracting the first slot's length from @code{STARTING_FRAME_OFFSET}. +Otherwise, it is found by adding the length of the first slot to the +value @code{STARTING_FRAME_OFFSET}. +@c i'm not sure if the above is still correct.. had to change it to get +@c rid of an overfull. --mew 2feb93 + +@findex STACK_POINTER_OFFSET +@item STACK_POINTER_OFFSET +Offset from the stack pointer register to the first location at which +outgoing arguments are placed. If not specified, the default value of +zero is used. This is the proper value for most machines. + +If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above +the first location at which outgoing arguments are placed. + +@findex FIRST_PARM_OFFSET +@item FIRST_PARM_OFFSET (@var{fundecl}) +Offset from the argument pointer register to the first argument's +address. On some machines it may depend on the data type of the +function. + +If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above +the first argument's address. + +@findex STACK_DYNAMIC_OFFSET +@item STACK_DYNAMIC_OFFSET (@var{fundecl}) +Offset from the stack pointer register to an item dynamically allocated +on the stack, e.g., by @code{alloca}. + +The default value for this macro is @code{STACK_POINTER_OFFSET} plus the +length of the outgoing arguments. The default is correct for most +machines. See @file{function.c} for details. + +@findex DYNAMIC_CHAIN_ADDRESS +@item DYNAMIC_CHAIN_ADDRESS (@var{frameaddr}) +A C expression whose value is RTL representing the address in a stack +frame where the pointer to the caller's frame is stored. Assume that +@var{frameaddr} is an RTL expression for the address of the stack frame +itself. + +If you don't define this macro, the default is to return the value +of @var{frameaddr}---that is, the stack frame address is also the +address of the stack word that points to the previous frame. + +@findex SETUP_FRAME_ADDRESSES +@item SERTUP_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 +before we can access arbitrary stack frames. +This macro will seldom need to be defined. + +@findex RETURN_ADDR_RTX +@item RETURN_ADDR_RTX (@var{count}, @var{frameaddr}) +A C expression whose value is RTL representing the value of the return +address for the frame @var{count} steps up from the current frame. +@var{frameaddr} is the frame pointer of the @var{count} frame, or +the frame pointer of the @var{count} @minus{} 1 frame if +@code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined. + +@findex RETURN_ADDR_IN_PREVIOUS_FRAME +@item RETURN_ADDR_IN_PREVIOUS_FRAME +Define this if the return address of a particular stack frame is accessed +from the frame pointer of the previous stack frame. +@end table + +@need 2000 +@node Frame Registers +@subsection Registers That Address the Stack Frame + +@c prevent bad page break with this line +This discusses registers that address the stack frame. + +@table @code +@findex STACK_POINTER_REGNUM +@item STACK_POINTER_REGNUM +The register number of the stack pointer register, which must also be a +fixed register according to @code{FIXED_REGISTERS}. On most machines, +the hardware determines which register this is. + +@findex FRAME_POINTER_REGNUM +@item FRAME_POINTER_REGNUM +The register number of the frame pointer register, which is used to +access automatic variables in the stack frame. On some machines, the +hardware determines which register this is. On other machines, you can +choose any register you wish for this purpose. + +@findex HARD_FRAME_POINTER_REGNUM +@item HARD_FRAME_POINTER_REGNUM +On some machines the offset between the frame pointer and starting +offset of the automatic variables is not known until after register +allocation has been done (for example, because the saved registers are +between these two locations). On those machines, define +@code{FRAME_POINTER_REGNUM} the number of a special, fixed register to +be used internally until the offset is known, and define +@code{HARD_FRAME_POINTER_REGNUM} to be actual the hard register number +used for the frame pointer. + +You should define this macro only in the very rare circumstances when it +is not possible to calculate the offset between the frame pointer and +the automatic variables until after register allocation has been +completed. When this macro is defined, you must also indicate in your +definition of @code{ELIMINABLE_REGS} how to eliminate +@code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM} +or @code{STACK_POINTER_REGNUM}. + +Do not define this macro if it would be the same as +@code{FRAME_POINTER_REGNUM}. + +@findex ARG_POINTER_REGNUM +@item ARG_POINTER_REGNUM +The register number of the arg pointer register, which is used to access +the function's argument list. On some machines, this is the same as the +frame pointer register. On some machines, the hardware determines which +register this is. On other machines, you can choose any register you +wish for this purpose. If this is not the same register as the frame +pointer register, then you must mark it as a fixed register according to +@code{FIXED_REGISTERS}, or arrange to be able to eliminate it +(@pxref{Elimination}). + +@findex STATIC_CHAIN_REGNUM +@findex STATIC_CHAIN_INCOMING_REGNUM +@item STATIC_CHAIN_REGNUM +@itemx STATIC_CHAIN_INCOMING_REGNUM +Register numbers used for passing a function's static chain pointer. If +register windows are used, the register number as seen by the called +function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register +number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If +these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need +not be defined.@refill + +The static chain register need not be a fixed register. + +If the static chain is passed in memory, these macros should not be +defined; instead, the next two macros should be defined. + +@findex STATIC_CHAIN +@findex STATIC_CHAIN_INCOMING +@item STATIC_CHAIN +@itemx STATIC_CHAIN_INCOMING +If the static chain is passed in memory, these macros provide rtx giving +@code{mem} expressions that denote where they are stored. +@code{STATIC_CHAIN} and @code{STATIC_CHAIN_INCOMING} give the locations +as seen by the calling and called functions, respectively. Often the former +will be at an offset from the stack pointer and the latter at an offset from +the frame pointer.@refill + +@findex stack_pointer_rtx +@findex frame_pointer_rtx +@findex arg_pointer_rtx +The variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and +@code{arg_pointer_rtx} will have been initialized prior to the use of these +macros and should be used to refer to those items. + +If the static chain is passed in a register, the two previous macros should +be defined instead. +@end table + +@node Elimination +@subsection Eliminating Frame Pointer and Arg Pointer + +@c prevent bad page break with this line +This is about eliminating the frame pointer and arg pointer. + +@table @code +@findex FRAME_POINTER_REQUIRED +@item FRAME_POINTER_REQUIRED +A C expression which is nonzero if a function must have and use a frame +pointer. This expression is evaluated in the reload pass. If its value is +nonzero the function will have a frame pointer. + +The expression can in principle examine the current function and decide +according to the facts, but on most machines the constant 0 or the +constant 1 suffices. Use 0 when the machine allows code to be generated +with no frame pointer, and doing so saves some time or space. Use 1 +when there is no possible advantage to avoiding a frame pointer. + +In certain cases, the compiler does not know how to produce valid code +without a frame pointer. The compiler recognizes those cases and +automatically gives the function a frame pointer regardless of what +@code{FRAME_POINTER_REQUIRED} says. You don't need to worry about +them.@refill + +In a function that does not require a frame pointer, the frame pointer +register can be allocated for ordinary usage, unless you mark it as a +fixed register. See @code{FIXED_REGISTERS} for more information. + +@findex INITIAL_FRAME_POINTER_OFFSET +@findex get_frame_size +@item INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) +A C statement to store in the variable @var{depth-var} the difference +between the frame pointer and the stack pointer values immediately after +the function prologue. The value would be computed from information +such as the result of @code{get_frame_size ()} and the tables of +registers @code{regs_ever_live} and @code{call_used_regs}. + +If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and +need not be defined. Otherwise, it must be defined even if +@code{FRAME_POINTER_REQUIRED} is defined to always be true; in that +case, you may set @var{depth-var} to anything. + +@findex ELIMINABLE_REGS +@item ELIMINABLE_REGS +If defined, this macro specifies a table of register pairs used to +eliminate unneeded registers that point into the stack frame. If it is not +defined, the only elimination attempted by the compiler is to replace +references to the frame pointer with references to the stack pointer. + +The definition of this macro is a list of structure initializations, each +of which specifies an original and replacement register. + +On some machines, the position of the argument pointer is not known until +the compilation is completed. In such a case, a separate hard register +must be used for the argument pointer. This register can be eliminated by +replacing it with either the frame pointer or the argument pointer, +depending on whether or not the frame pointer has been eliminated. + +In this case, you might specify: +@example +#define ELIMINABLE_REGS \ +@{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \ + @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \ + @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@} +@end example + +Note that the elimination of the argument pointer with the stack pointer is +specified first since that is the preferred elimination. + +@findex CAN_ELIMINATE +@item CAN_ELIMINATE (@var{from-reg}, @var{to-reg}) +A C expression that returns non-zero if the compiler is allowed to try +to replace register number @var{from-reg} with register number +@var{to-reg}. This macro need only be defined if @code{ELIMINABLE_REGS} +is defined, and will usually be the constant 1, since most of the cases +preventing register elimination are things that the compiler already +knows about. + +@findex INITIAL_ELIMINATION_OFFSET +@item INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) +This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It +specifies the initial difference between the specified pair of +registers. This macro must be defined if @code{ELIMINABLE_REGS} is +defined. + +@findex LONGJMP_RESTORE_FROM_STACK +@item LONGJMP_RESTORE_FROM_STACK +Define this macro if the @code{longjmp} function restores registers from +the stack frames, rather than from those saved specifically by +@code{setjmp}. Certain quantities must not be kept in registers across +a call to @code{setjmp} on such machines. +@end table + +@node Stack Arguments +@subsection Passing Function Arguments on the Stack +@cindex arguments on stack +@cindex stack arguments + +The macros in this section control how arguments are passed +on the stack. See the following section for other macros that +control passing certain arguments in registers. + +@table @code +@findex PROMOTE_PROTOTYPES +@item PROMOTE_PROTOTYPES +Define this macro if an argument declared in a prototype as an +integral type smaller than @code{int} should actually be passed as an +@code{int}. In addition to avoiding errors in certain cases of +mismatch, it also makes for better code on certain machines. + +@findex PUSH_ROUNDING +@item PUSH_ROUNDING (@var{npushed}) +A C expression that is the number of bytes actually pushed onto the +stack when an instruction attempts to push @var{npushed} bytes. + +If the target machine does not have a push instruction, do not define +this macro. That directs GNU CC to use an alternate strategy: to +allocate the entire argument block and then store the arguments into +it. + +On some machines, the definition + +@example +#define PUSH_ROUNDING(BYTES) (BYTES) +@end example + +@noindent +will suffice. But on other machines, instructions that appear +to push one byte actually push two bytes in an attempt to maintain +alignment. Then the definition should be + +@example +#define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) +@end example + +@findex ACCUMULATE_OUTGOING_ARGS +@findex current_function_outgoing_args_size +@item ACCUMULATE_OUTGOING_ARGS +If defined, the maximum amount of space required for outgoing arguments +will be computed and placed into the variable +@code{current_function_outgoing_args_size}. No space will be pushed +onto the stack for each call; instead, the function prologue should +increase the stack frame size by this amount. + +Defining both @code{PUSH_ROUNDING} and @code{ACCUMULATE_OUTGOING_ARGS} +is not proper. + +@findex REG_PARM_STACK_SPACE +@item REG_PARM_STACK_SPACE (@var{fndecl}) +Define this macro if functions should assume that stack space has been +allocated for arguments even when their values are passed in +registers. + +The value of this macro is the size, in bytes, of the area reserved for +arguments passed in registers for the function represented by @var{fndecl}. + +This space can be allocated by the caller, or be a part of the +machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says +which. +@c above is overfull. not sure what to do. --mew 5feb93 did +@c something, not sure if it looks good. --mew 10feb93 + +@findex MAYBE_REG_PARM_STACK_SPACE +@findex FINAL_REG_PARM_STACK_SPACE +@item MAYBE_REG_PARM_STACK_SPACE +@itemx FINAL_REG_PARM_STACK_SPACE (@var{const_size}, @var{var_size}) +Define these macros in addition to the one above if functions might +allocate stack space for arguments even when their values are passed +in registers. These should be used when the stack space allocated +for arguments in registers is not a simple constant independent of the +function declaration. + +The value of the first macro is the size, in bytes, of the area that +we should initially assume would be reserved for arguments passed in registers. + +The value of the second macro is the actual size, in bytes, of the area +that will be reserved for arguments passed in registers. This takes two +arguments: an integer representing the number of bytes of fixed sized +arguments on the stack, and a tree representing the number of bytes of +variable sized arguments on the stack. + +When these macros are defined, @code{REG_PARM_STACK_SPACE} will only be +called for libcall functions, the current function, or for a function +being called when it is known that such stack space must be allocated. +In each case this value can be easily computed. + +When deciding whether a called function needs such stack space, and how +much space to reserve, GNU CC uses these two macros instead of +@code{REG_PARM_STACK_SPACE}. + +@findex OUTGOING_REG_PARM_STACK_SPACE +@item OUTGOING_REG_PARM_STACK_SPACE +Define this if it is the responsibility of the caller to allocate the area +reserved for arguments passed in registers. + +If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls +whether the space for these arguments counts in the value of +@code{current_function_outgoing_args_size}. + +@findex STACK_PARMS_IN_REG_PARM_AREA +@item STACK_PARMS_IN_REG_PARM_AREA +Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the +stack parameters don't skip the area specified by it. +@c i changed this, makes more sens and it should have taken care of the +@c overfull.. not as specific, tho. --mew 5feb93 + +Normally, when a parameter is not passed in registers, it is placed on the +stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro +suppresses this behavior and causes the parameter to be passed on the +stack in its natural location. + +@findex RETURN_POPS_ARGS +@item RETURN_POPS_ARGS (@var{funtype}, @var{stack-size}) +A C expression that should indicate the number of bytes of its own +arguments that a function pops on returning, or 0 if the +function pops no arguments and the caller must therefore pop them all +after the function returns. + +@var{funtype} is a C variable whose value is a tree node that +describes the function in question. Normally it is a node of type +@code{FUNCTION_TYPE} that describes the data type of the function. +From this it is possible to obtain the data types of the value and +arguments (if known). + +When a call to a library function is being considered, @var{funtype} +will contain an identifier node for the library function. Thus, if +you need to distinguish among various library functions, you can do so +by their names. Note that ``library function'' in this context means +a function used to perform arithmetic, whose name is known specially +in the compiler and was not mentioned in the C code being compiled. + +@var{stack-size} is the number of bytes of arguments passed on the +stack. If a variable number of bytes is passed, it is zero, and +argument popping will always be the responsibility of the calling function. + +On the Vax, all functions always pop their arguments, so the definition +of this macro is @var{stack-size}. On the 68000, using the standard +calling convention, no functions pop their arguments, so the value of +the macro is always 0 in this case. But an alternative calling +convention is available in which functions that take a fixed number of +arguments pop them but other functions (such as @code{printf}) pop +nothing (the caller pops all). When this convention is in use, +@var{funtype} is examined to determine whether a function takes a fixed +number of arguments. +@end table + +@node Register Arguments +@subsection Passing Arguments in Registers +@cindex arguments in registers +@cindex registers arguments + +This section describes the macros which let you control how various +types of arguments are passed in registers or how they are arranged in +the stack. + +@table @code +@findex FUNCTION_ARG +@item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) +A C expression that controls whether a function argument is passed +in a register, and which register. + +The arguments are @var{cum}, which summarizes all the previous +arguments; @var{mode}, the machine mode of the argument; @var{type}, +the data type of the argument as a tree node or 0 if that is not known +(which happens for C support library functions); and @var{named}, +which is 1 for an ordinary argument and 0 for nameless arguments that +correspond to @samp{@dots{}} in the called function's prototype. + +The value of the expression should either be a @code{reg} RTX for the +hard register in which to pass the argument, or zero to pass the +argument on the stack. + +For machines like the Vax and 68000, where normally all arguments are +pushed, zero suffices as a definition. + +@cindex @file{stdarg.h} and register arguments +The usual way to make the ANSI library @file{stdarg.h} work on a machine +where some arguments are usually passed in registers, is to cause +nameless arguments to be passed on the stack instead. This is done +by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0. + +@cindex @code{MUST_PASS_IN_STACK}, and @code{FUNCTION_ARG} +@cindex @code{REG_PARM_STACK_SPACE}, and @code{FUNCTION_ARG} +You may use the macro @code{MUST_PASS_IN_STACK (@var{mode}, @var{type})} +in the definition of this macro to determine if this argument is of a +type that must be passed in the stack. If @code{REG_PARM_STACK_SPACE} +is not defined and @code{FUNCTION_ARG} returns non-zero for such an +argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is +defined, the argument will be computed in the stack and then loaded into +a register. + +@findex FUNCTION_INCOMING_ARG +@item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) +Define this macro if the target machine has ``register windows'', so +that the register in which a function sees an arguments is not +necessarily the same as the one in which the caller passed the +argument. + +For such machines, @code{FUNCTION_ARG} computes the register in which +the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should +be defined in a similar fashion to tell the function being called +where the arguments will arrive. + +If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG} +serves both purposes.@refill + +@findex FUNCTION_ARG_PARTIAL_NREGS +@item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named}) +A C expression for the number of words, at the beginning of an +argument, must be put in registers. The value must be zero for +arguments that are passed entirely in registers or that are entirely +pushed on the stack. + +On some machines, certain arguments must be passed partially in +registers and partially in memory. On these machines, typically the +first @var{n} words of arguments are passed in registers, and the rest +on the stack. If a multi-word argument (a @code{double} or a +structure) crosses that boundary, its first few words must be passed +in registers and the rest must be pushed. This macro tells the +compiler when this occurs, and how many of the words should go in +registers. + +@code{FUNCTION_ARG} for these arguments should return the first +register to be used by the caller for this argument; likewise +@code{FUNCTION_INCOMING_ARG}, for the called function. + +@findex FUNCTION_ARG_PASS_BY_REFERENCE +@item FUNCTION_ARG_PASS_BY_REFERENCE (@var{cum}, @var{mode}, @var{type}, @var{named}) +A C expression that indicates when an argument must be passed by reference. +If nonzero for an argument, a copy of that argument is made in memory and a +pointer to the argument is passed instead of the argument itself. +The pointer is passed in whatever way is appropriate for passing a pointer +to that type. + +On machines where @code{REG_PARM_STACK_SPACE} is not defined, a suitable +definition of this macro might be +@smallexample +#define FUNCTION_ARG_PASS_BY_REFERENCE\ +(CUM, MODE, TYPE, NAMED) \ + MUST_PASS_IN_STACK (MODE, TYPE) +@end smallexample +@c this is *still* too long. --mew 5feb93 + +@findex FUNCTION_ARG_CALLEE_COPIES +@item FUNCTION_ARG_CALLEE_COPIES (@var{cum}, @var{mode}, @var{type}, @var{named}) +If defined, a C expression that indicates when it is the called function's +responsibility to make a copy of arguments passed by invisible reference. +Normally, the caller makes a copy and passes the address of the copy to the +routine being called. When FUNCTION_ARG_CALLEE_COPIES is defined and is +nonzero, the caller does not make a copy. Instead, it passes a pointer to the +``live'' value. The called function must not modify this value. If it can be +determined that the value won't be modified, it need not make a copy; +otherwise a copy must be made. + +@findex CUMULATIVE_ARGS +@item CUMULATIVE_ARGS +A C type for declaring a variable that is used as the first argument of +@code{FUNCTION_ARG} and other related values. For some target machines, +the type @code{int} suffices and can hold the number of bytes of +argument so far. + +There is no need to record in @code{CUMULATIVE_ARGS} anything about the +arguments that have been passed on the stack. The compiler has other +variables to keep track of that. For target machines on which all +arguments are passed on the stack, there is no need to store anything in +@code{CUMULATIVE_ARGS}; however, the data structure must exist and +should not be empty, so use @code{int}. + +@findex INIT_CUMULATIVE_ARGS +@item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}) +A C statement (sans semicolon) for initializing the variable @var{cum} +for the state at the beginning of the argument list. The variable has +type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node +for the data type of the function which will receive the args, or 0 +if the args are to a compiler support library function. + +When processing a call to a compiler support library function, +@var{libname} identifies which one. It is a @code{symbol_ref} rtx which +contains the name of the function, as a string. @var{libname} is 0 when +an ordinary C function call is being processed. Thus, each time this +macro is called, either @var{libname} or @var{fntype} is nonzero, but +never both of them at once. + +@findex INIT_CUMULATIVE_INCOMING_ARGS +@item INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname}) +Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of +finding the arguments for the function being compiled. If this macro is +undefined, @code{INIT_CUMULATIVE_ARGS} is used instead. + +The value passed for @var{libname} is always 0, since library routines +with special calling conventions are never compiled with GNU CC. The +argument @var{libname} exists for symmetry with +@code{INIT_CUMULATIVE_ARGS}. +@c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe. +@c --mew 5feb93 i switched the order of the sentences. --mew 10feb93 + +@findex FUNCTION_ARG_ADVANCE +@item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) +A C statement (sans semicolon) to update the summarizer variable +@var{cum} to advance past an argument in the argument list. The +values @var{mode}, @var{type} and @var{named} describe that argument. +Once this is done, the variable @var{cum} is suitable for analyzing +the @emph{following} argument with @code{FUNCTION_ARG}, etc.@refill + +This macro need not do anything if the argument in question was passed +on the stack. The compiler knows how to track the amount of stack space +used for arguments without any special help. + +@findex FUNCTION_ARG_PADDING +@item FUNCTION_ARG_PADDING (@var{mode}, @var{type}) +If defined, a C expression which determines whether, and in which direction, +to pad out an argument with extra space. The value should be of type +@code{enum direction}: either @code{upward} to pad above the argument, +@code{downward} to pad below, or @code{none} to inhibit padding. + +The @emph{amount} of padding is always just enough to reach the next +multiple of @code{FUNCTION_ARG_BOUNDARY}; this macro does not control +it. + +This macro has a default definition which is right for most systems. +For little-endian machines, the default is to pad upward. For +big-endian machines, the default is to pad downward for an argument of +constant size shorter than an @code{int}, and upward otherwise. + +@findex FUNCTION_ARG_BOUNDARY +@item FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type}) +If defined, a C expression that gives the alignment boundary, in bits, +of an argument with the specified mode and type. If it is not defined, +@code{PARM_BOUNDARY} is used for all arguments. + +@findex FUNCTION_ARG_REGNO_P +@item FUNCTION_ARG_REGNO_P (@var{regno}) +A C expression that is nonzero if @var{regno} is the number of a hard +register in which function arguments are sometimes passed. This does +@emph{not} include implicit arguments such as the static chain and +the structure-value address. On many machines, no registers can be +used for this purpose since all function arguments are pushed on the +stack. +@end table + +@node Scalar Return +@subsection How Scalar Function Values Are Returned +@cindex return values in registers +@cindex values, returned by functions +@cindex scalars, returned as values + +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 @samp{-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 +function returns a value of data type @var{valtype}. @var{valtype} is +a tree node representing a data type. Write @code{TYPE_MODE +(@var{valtype})} to get the machine mode used to represent that type. +On many machines, only the mode is relevant. (Actually, on most +machines, scalar values are returned in the same place regardless of +mode).@refill + +If @code{PROMOTE_FUNCTION_RETURN} is defined, you must apply the same +promotion rules specified in @code{PROMOTE_MODE} if @var{valtype} is a +scalar type. + +If the precise function being called is known, @var{func} is a tree +node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null +pointer. This makes it possible to use a different value-returning +convention for specific functions when all their calls are +known.@refill + +@code{FUNCTION_VALUE} is not used for return vales with aggregate data +types, because these are returned in another way. See +@code{STRUCT_VALUE_REGNUM} and related macros, below. + +@findex FUNCTION_OUTGOING_VALUE +@item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func}) +Define this macro if the target machine has ``register windows'' +so that the register in which a function returns its value is not +the same as the one in which the caller sees the value. + +For such machines, @code{FUNCTION_VALUE} computes the register in which +the caller will see the value. @code{FUNCTION_OUTGOING_VALUE} should be +defined in a similar fashion to tell the function where to put the +value.@refill + +If @code{FUNCTION_OUTGOING_VALUE} is not defined, +@code{FUNCTION_VALUE} serves both purposes.@refill + +@code{FUNCTION_OUTGOING_VALUE} is not used for return vales with +aggregate data types, because these are returned in another way. See +@code{STRUCT_VALUE_REGNUM} and related macros, below. + +@findex LIBCALL_VALUE +@item LIBCALL_VALUE (@var{mode}) +A C expression to create an RTX representing the place where a library +function returns a value of mode @var{mode}. If the precise function +being called is known, @var{func} is a tree node +(@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null +pointer. This makes it possible to use a different value-returning +convention for specific functions when all their calls are +known.@refill + +Note that ``library function'' in this context means a compiler +support routine, used to perform arithmetic, whose name is known +specially by the compiler and was not mentioned in the C code being +compiled. + +The definition of @code{LIBRARY_VALUE} need not be concerned aggregate +data types, because none of the library functions returns such types. + +@findex FUNCTION_VALUE_REGNO_P +@item FUNCTION_VALUE_REGNO_P (@var{regno}) +A C expression that is nonzero if @var{regno} is the number of a hard +register in which the values of called function may come back. + +A register whose use for returning values is limited to serving as the +second of a pair (for a value of type @code{double}, say) need not be +recognized by this macro. So for most machines, this definition +suffices: + +@example +#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) +@end example + +If the machine has register windows, so that the caller and the called +function use different registers for the return value, this macro +should recognize only the caller's register numbers. + +@findex APPLY_RESULT_SIZE +@item APPLY_RESULT_SIZE +Define this macro if @samp{untyped_call} and @samp{untyped_return} +need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for +saving and restoring an arbitrary return value. +@end table + +@node Aggregate Return +@subsection How Large Values Are Returned +@cindex aggregates as return values +@cindex large return values +@cindex returning aggregate values +@cindex structure value address + +When a function value's mode is @code{BLKmode} (and in some other +cases), the value is not returned according to @code{FUNCTION_VALUE} +(@pxref{Scalar Return}). Instead, the caller passes the address of a +block of memory in which the value should be stored. This address +is called the @dfn{structure value address}. + +This section describes how to control returning structure values in +memory. + +@table @code +@findex RETURN_IN_MEMORY +@item RETURN_IN_MEMORY (@var{type}) +A C expression which can inhibit the returning of certain function +values in registers, based on the type of value. A nonzero value says +to return the function value in memory, just as large structures are +always returned. Here @var{type} will be a C expression of type +@code{tree}, representing the data type of the value. + +Note that values of mode @code{BLKmode} must be explicitly handled +by this macro. Also, the option @samp{-fpcc-struct-return} +takes effect regardless of this macro. On most systems, it is +possible to leave the macro undefined; this causes a default +definition to be used, whose value is the constant 1 for @code{BLKmode} +values, and 0 otherwise. + +Do not use this macro to indicate that structures and unions should always +be returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN} +to indicate this. + +@findex DEFAULT_PCC_STRUCT_RETURN +@item DEFAULT_PCC_STRUCT_RETURN +Define this macro to be 1 if all structure and union return values must be +in memory. Since this results in slower code, this should be defined +only if needed for compatibility with other compilers or with an ABI. +If you define this macro to be 0, then the conventions used for structure +and union return values are decided by the @code{RETURN_IN_MEMORY} macro. + +If not defined, this defaults to the value 1. + +@findex STRUCT_VALUE_REGNUM +@item STRUCT_VALUE_REGNUM +If the structure value address is passed in a register, then +@code{STRUCT_VALUE_REGNUM} should be the number of that register. + +@findex STRUCT_VALUE +@item STRUCT_VALUE +If the structure value address is not passed in a register, define +@code{STRUCT_VALUE} as an expression returning an RTX for the place +where the address is passed. If it returns 0, the address is passed as +an ``invisible'' first argument. + +@findex STRUCT_VALUE_INCOMING_REGNUM +@item STRUCT_VALUE_INCOMING_REGNUM +On some architectures the place where the structure value address +is found by the called function is not the same place that the +caller put it. This can be due to register windows, or it could +be because the function prologue moves it to a different place. + +If the incoming location of the structure value address is in a +register, define this macro as the register number. + +@findex STRUCT_VALUE_INCOMING +@item STRUCT_VALUE_INCOMING +If the incoming location is not a register, then you should define +@code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the +called function should find the value. If it should find the value on +the stack, define this to create a @code{mem} which refers to the frame +pointer. A definition of 0 means that the address is passed as an +``invisible'' first argument. + +@findex PCC_STATIC_STRUCT_RETURN +@item PCC_STATIC_STRUCT_RETURN +Define this macro if the usual system convention on the target machine +for returning structures and unions is for the called function to return +the address of a static variable containing the value. + +Do not define this if the usual system convention is for the caller to +pass an address to the subroutine. + +This macro has effect in @samp{-fpcc-struct-return} mode, but it does +nothing when you use @samp{-freg-struct-return} mode. +@end table + +@node Caller Saves +@subsection Caller-Saves Register Allocation + +If you enable it, GNU CC can save registers around function calls. This +makes it possible to use call-clobbered registers to hold variables that +must live across calls. + +@table @code +@findex DEFAULT_CALLER_SAVES +@item DEFAULT_CALLER_SAVES +Define this macro if function calls on the target machine do not preserve +any registers; in other words, if @code{CALL_USED_REGISTERS} has 1 +for all registers. This macro enables @samp{-fcaller-saves} by default. +Eventually that option will be enabled by default on all machines and both +the option and this macro will be eliminated. + +@findex CALLER_SAVE_PROFITABLE +@item CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls}) +A C expression to determine whether it is worthwhile to consider placing +a pseudo-register in a call-clobbered hard register and saving and +restoring it around each function call. The expression should be 1 when +this is worth doing, and 0 otherwise. + +If you don't define this macro, a default is used which is good on most +machines: @code{4 * @var{calls} < @var{refs}}. +@end table + +@node Function Entry +@subsection Function Entry and Exit +@cindex function entry and exit +@cindex prologue +@cindex epilogue + +This section describes the macros that output function entry +(@dfn{prologue}) and exit (@dfn{epilogue}) code. + +@table @code +@findex FUNCTION_PROLOGUE +@item FUNCTION_PROLOGUE (@var{file}, @var{size}) +A C compound statement that outputs the assembler code for entry to a +function. The prologue is responsible for setting up the stack frame, +initializing the frame pointer register, saving registers that must be +saved, and allocating @var{size} additional bytes of storage for the +local variables. @var{size} is an integer. @var{file} is a stdio +stream to which the assembler code should be output. + +The label for the beginning of the function need not be output by this +macro. That has already been done when the macro is run. + +@findex regs_ever_live +To determine which registers to save, the macro can refer to the array +@code{regs_ever_live}: element @var{r} is nonzero if hard register +@var{r} is used anywhere within the function. This implies the function +prologue should save register @var{r}, provided it is not one of the +call-used registers. (@code{FUNCTION_EPILOGUE} must likewise use +@code{regs_ever_live}.) + +On machines that have ``register windows'', the function entry code does +not save on the stack the registers that are in the windows, even if +they are supposed to be preserved by function calls; instead it takes +appropriate steps to ``push'' the register stack, if any non-call-used +registers are used in the function. + +@findex frame_pointer_needed +On machines where functions may or may not have frame-pointers, the +function entry code must vary accordingly; it must set up the frame +pointer if one is wanted, and not otherwise. To determine whether a +frame pointer is in wanted, the macro can refer to the variable +@code{frame_pointer_needed}. The variable's value will be 1 at run +time in a function that needs a frame pointer. @xref{Elimination}. + +The function entry code is responsible for allocating any stack space +required for the function. This stack space consists of the regions +listed below. In most cases, these regions are allocated in the +order listed, with the last listed region closest to the top of the +stack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and +the highest address if it is not defined). You can use a different order +for a machine if doing so is more convenient or required for +compatibility reasons. Except in cases where required by standard +or by a debugger, there is no reason why the stack layout used by GCC +need agree with that used by other compilers for a machine. + +@itemize @bullet +@item +@findex current_function_pretend_args_size +A region of @code{current_function_pretend_args_size} bytes of +uninitialized space just underneath the first argument arriving on the +stack. (This may not be at the very start of the allocated stack region +if the calling sequence has pushed anything else since pushing the stack +arguments. But usually, on such machines, nothing else has been pushed +yet, because the function prologue itself does all the pushing.) 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 @file{varargs.h} and @file{stdargs.h}. + +@item +An area of memory used to save certain registers used by the function. +The size of this area, which may also include space for such things as +the return address and pointers to previous stack frames, is +machine-specific and usually depends on which registers have been used +in the function. Machines with register windows often do not require +a save area. + +@item +A region of at least @var{size} bytes, possibly rounded up to an allocation +boundary, to contain the local variables of the function. On some machines, +this region and the save area may occur in the opposite order, with the +save area closer to the top of the stack. + +@item +@cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames +Optionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of +@code{current_function_outgoing_args_size} bytes to be used for outgoing +argument lists of the function. @xref{Stack Arguments}. +@end itemize + +Normally, it is necessary for the macros @code{FUNCTION_PROLOGUE} and +@code{FUNCTION_EPILOGUE} to treat leaf functions specially. The C +variable @code{leaf_function} is nonzero for such a function. + +@findex EXIT_IGNORE_STACK +@item EXIT_IGNORE_STACK +Define this macro as a C expression that is nonzero if the return +instruction or the function epilogue ignores the value of the stack +pointer; in other words, if it is safe to delete an instruction to +adjust the stack pointer before a return from the function. + +Note that this macro's value is relevant only for functions for which +frame pointers are maintained. It is never safe to delete a final +stack adjustment in a function that has no frame pointer, and the +compiler knows this regardless of @code{EXIT_IGNORE_STACK}. + +@findex FUNCTION_EPILOGUE +@item FUNCTION_EPILOGUE (@var{file}, @var{size}) +A C compound statement that outputs the assembler code for exit from a +function. The epilogue is responsible for restoring the saved +registers and stack pointer to their values when the function was +called, and returning control to the caller. This macro takes the +same arguments as the macro @code{FUNCTION_PROLOGUE}, and the +registers to restore are determined from @code{regs_ever_live} and +@code{CALL_USED_REGISTERS} in the same way. + +On some machines, there is a single instruction that does all the work +of returning from the function. On these machines, give that +instruction the name @samp{return} and do not define the macro +@code{FUNCTION_EPILOGUE} at all. + +Do not define a pattern named @samp{return} if you want the +@code{FUNCTION_EPILOGUE} to be used. If you want the target switches +to control whether return instructions or epilogues are used, define a +@samp{return} pattern with a validity condition that tests the target +switches appropriately. If the @samp{return} pattern's validity +condition is false, epilogues will be used. + +On machines where functions may or may not have frame-pointers, the +function exit code must vary accordingly. Sometimes the code for these +two cases is completely different. To determine whether a frame pointer +is wanted, the macro can refer to the variable +@code{frame_pointer_needed}. The variable's value will be 1 when compiling +a function that needs a frame pointer. + +Normally, @code{FUNCTION_PROLOGUE} and @code{FUNCTION_EPILOGUE} must +treat leaf functions specially. The C variable @code{leaf_function} is +nonzero for such a function. @xref{Leaf Functions}. + +On some machines, some functions pop their arguments on exit while +others leave that for the caller to do. For example, the 68020 when +given @samp{-mrtd} pops arguments in functions that take a fixed +number of arguments. + +@findex current_function_pops_args +Your definition of the macro @code{RETURN_POPS_ARGS} decides which +functions pop their own arguments. @code{FUNCTION_EPILOGUE} needs to +know what was decided. The variable that is called +@code{current_function_pops_args} is the number of bytes of its +arguments that a function should pop. @xref{Scalar Return}. +@c what is the "its arguments" in the above sentence referring to, pray +@c tell? --mew 5feb93 + +@findex DELAY_SLOTS_FOR_EPILOGUE +@item DELAY_SLOTS_FOR_EPILOGUE +Define this macro if the function epilogue contains delay slots to which +instructions from the rest of the function can be ``moved''. The +definition should be a C expression whose value is an integer +representing the number of delay slots there. + +@findex ELIGIBLE_FOR_EPILOGUE_DELAY +@item ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n}) +A C expression that returns 1 if @var{insn} can be placed in delay +slot number @var{n} of the epilogue. + +The argument @var{n} is an integer which identifies the delay slot now +being considered (since different slots may have different rules of +eligibility). It is never negative and is always less than the number +of epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns). +If you reject a particular insn for a given delay slot, in principle, it +may be reconsidered for a subsequent delay slot. Also, other insns may +(at least in principle) be considered for the so far unfilled delay +slot. + +@findex current_function_epilogue_delay_list +@findex final_scan_insn +The insns accepted to fill the epilogue delay slots are put in an RTL +list made with @code{insn_list} objects, stored in the variable +@code{current_function_epilogue_delay_list}. The insn for the first +delay slot comes first in the list. Your definition of the macro +@code{FUNCTION_EPILOGUE} should fill the delay slots by outputting the +insns in this list, usually by calling @code{final_scan_insn}. + +You need not define this macro if you did not define +@code{DELAY_SLOTS_FOR_EPILOGUE}. +@end table + +@node Profiling +@subsection Generating Code for Profiling +@cindex profiling, code generation + +These macros will help you generate code for profiling. + +@table @code +@findex FUNCTION_PROFILER +@item FUNCTION_PROFILER (@var{file}, @var{labelno}) +A C statement or compound statement to output to @var{file} some +assembler code to call the profiling subroutine @code{mcount}. +Before calling, the assembler code must load the address of a +counter variable into a register where @code{mcount} expects to +find the address. The name of this variable is @samp{LP} followed +by the number @var{labelno}, so you would generate the name using +@samp{LP%d} in a @code{fprintf}. + +@findex mcount +The details of how the address should be passed to @code{mcount} are +determined by your operating system environment, not by GNU CC. To +figure them out, compile a small program for profiling using the +system's installed C compiler and look at the assembler code that +results. + +@findex PROFILE_BEFORE_PROLOGUE +@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 FUNCTION_BLOCK_PROFILER +@findex __bb_init_func +@item FUNCTION_BLOCK_PROFILER (@var{file}, @var{labelno}) +A C statement or compound statement to output to @var{file} some +assembler code to initialize basic-block profiling for the current +object module. This code should call the subroutine +@code{__bb_init_func} once per object module, passing it as its sole +argument the address of a block allocated in the object module. + +The name of the block is a local symbol made with this statement: + +@example +ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 0); +@end example + +Of course, since you are writing the definition of +@code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you +can take a short cut in the definition of this macro and use the name +that you know will result. + +The first word of this block is a flag which will be nonzero if the +object module has already been initialized. So test this word first, +and do not call @code{__bb_init_func} if the flag is nonzero. + +@findex BLOCK_PROFILER +@item BLOCK_PROFILER (@var{file}, @var{blockno}) +A C statement or compound statement to increment the count associated +with the basic block number @var{blockno}. Basic blocks are numbered +separately from zero within each compilation. The count associated +with block number @var{blockno} is at index @var{blockno} in a vector +of words; the name of this array is a local symbol made with this +statement: + +@example +ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 2); +@end example + +@c This paragraph is the same as one a few paragraphs up. +@c That is not an error. +Of course, since you are writing the definition of +@code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you +can take a short cut in the definition of this macro and use the name +that you know will result. + +@findex BLOCK_PROFILER_CODE +@item BLOCK_PROFILER_CODE +A C function or functions which are needed in the library to +support block profiling. +@end table + +@node Varargs +@section Implementing the Varargs Macros +@cindex varargs implementation + +GNU CC comes with an implementation of @file{varargs.h} and +@file{stdarg.h} that work without change on machines that pass arguments +on the stack. Other machines require their own implementations of +varargs, and the two machine independent header files must have +conditionals to include it. + +ANSI @file{stdarg.h} differs from traditional @file{varargs.h} mainly in +the calling convention for @code{va_start}. The traditional +implementation takes just one argument, which is the variable in which +to store the argument pointer. The ANSI implementation of +@code{va_start} takes an additional second argument. The user is +supposed to write the last named argument of the function here. + +However, @code{va_start} should not use this argument. The way to find +the end of the named arguments is with the built-in functions described +below. + +@table @code +@findex __builtin_saveregs +@item __builtin_saveregs () +Use this built-in function to save the argument registers in memory so +that the varargs mechanism can access them. Both ANSI and traditional +versions of @code{va_start} must use @code{__builtin_saveregs}, unless +you use @code{SETUP_INCOMING_VARARGS} (see below) instead. + +On some machines, @code{__builtin_saveregs} is open-coded under the +control of the macro @code{EXPAND_BUILTIN_SAVEREGS}. On other machines, +it calls a routine written in assembler language, found in +@file{libgcc2.c}. + +Code generated for the call to @code{__builtin_saveregs} appears at the +beginning of the function, as opposed to where the call to +@code{__builtin_saveregs} is written, regardless of what the code is. +This is because the registers must be saved before the function starts +to use them for its own purposes. +@c i rewrote the first sentence above to fix an overfull hbox. --mew +@c 10feb93 + +@findex __builtin_args_info +@item __builtin_args_info (@var{category}) +Use this built-in function to find the first anonymous arguments in +registers. + +In general, a machine may have several categories of registers used for +arguments, each for a particular category of data types. (For example, +on some machines, floating-point registers are used for floating-point +arguments while other arguments are passed in the general registers.) +To make non-varargs functions use the proper calling convention, you +have defined the @code{CUMULATIVE_ARGS} data type to record how many +registers in each category have been used so far + +@code{__builtin_args_info} accesses the same data structure of type +@code{CUMULATIVE_ARGS} after the ordinary argument layout is finished +with it, with @var{category} specifying which word to access. Thus, the +value indicates the first unused register in a given category. + +Normally, you would use @code{__builtin_args_info} in the implementation +of @code{va_start}, accessing each category just once and storing the +value in the @code{va_list} object. This is because @code{va_list} will +have to update the values, and there is no way to alter the +values accessed by @code{__builtin_args_info}. + +@findex __builtin_next_arg +@item __builtin_next_arg (@var{lastarg}) +This is the equivalent of @code{__builtin_args_info}, for stack +arguments. It returns the address of the first anonymous stack +argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it +returns the address of the location above the first anonymous stack +argument. Use it in @code{va_start} to initialize the pointer for +fetching arguments from the stack. Also use it in @code{va_start} to +verify that the second parameter @var{lastarg} is the last named argument +of the current function. + +@findex __builtin_classify_type +@item __builtin_classify_type (@var{object}) +Since each machine has its own conventions for which data types are +passed in which kind of register, your implementation of @code{va_arg} +has to embody these conventions. The easiest way to categorize the +specified data type is to use @code{__builtin_classify_type} together +with @code{sizeof} and @code{__alignof__}. + +@code{__builtin_classify_type} ignores the value of @var{object}, +considering only its data type. It returns an integer describing what +kind of type that is---integer, floating, pointer, structure, and so on. + +The file @file{typeclass.h} defines an enumeration that you can use to +interpret the values of @code{__builtin_classify_type}. +@end table + +These machine description macros help implement varargs: + +@table @code +@findex EXPAND_BUILTIN_SAVEREGS +@item EXPAND_BUILTIN_SAVEREGS (@var{args}) +If defined, is a C expression that produces the machine-specific code +for a call to @code{__builtin_saveregs}. This code will be moved to the +very beginning of the function, before any parameter access are made. +The return value of this function should be an RTX that contains the +value to use as the return of @code{__builtin_saveregs}. + +The argument @var{args} is a @code{tree_list} containing the arguments +that were passed to @code{__builtin_saveregs}. + +If this macro is not defined, the compiler will output an ordinary +call to the library function @samp{__builtin_saveregs}. + +@c !!! a bug in texinfo; how to make the entry on the @item line allow +@c more than one line of text... help... --mew 10feb93 +@findex SETUP_INCOMING_VARARGS +@item SETUP_INCOMING_VARARGS (@var{args_so_far}, @var{mode}, @var{type}, +@var{pretend_args_size}, @var{second_time}) +This macro offers an alternative to using @code{__builtin_saveregs} and +defining the macro @code{EXPAND_BUILTIN_SAVEREGS}. Use it to store the +anonymous register arguments into the stack so that all the arguments +appear to have been passed consecutively on the stack. Once this is +done, you can use the standard implementation of varargs that works for +machines that pass all their arguments on the stack. + +The argument @var{args_so_far} is the @code{CUMULATIVE_ARGS} data +structure, containing the values that obtain after processing of the +named arguments. The arguments @var{mode} and @var{type} describe the +last named argument---its machine mode and its data type as a tree node. + +The macro implementation should do two things: first, push onto the +stack all the argument registers @emph{not} used for the named +arguments, and second, store the size of the data thus pushed into the +@code{int}-valued variable whose name is supplied as the argument +@var{pretend_args_size}. The value that you store here will serve as +additional offset for setting up the stack frame. + +Because you must generate code to push the anonymous arguments at +compile time without knowing their data types, +@code{SETUP_INCOMING_VARARGS} is only useful on machines that have just +a single category of argument register and use it uniformly for all data +types. + +If the argument @var{second_time} is nonzero, it means that the +arguments of the function are being analyzed for the second time. This +happens for an inline function, which is not actually compiled until the +end of the source file. The macro @code{SETUP_INCOMING_VARARGS} should +not generate any instructions in this case. +@end table + +@node Trampolines +@section Trampolines for Nested Functions +@cindex trampolines for nested functions +@cindex nested functions, trampolines for + +A @dfn{trampoline} is a small piece of code that is created at run time +when the address of a nested function is taken. It normally resides on +the stack, in the stack frame of the containing function. These macros +tell GNU CC how to generate code to allocate and initialize a +trampoline. + +The instructions in the trampoline must do two things: load a constant +address into the static chain register, and jump to the real address of +the nested function. On CISC machines such as the m68k, this requires +two instructions, a move immediate and a jump. Then the two addresses +exist in the trampoline as word-long immediate operands. On RISC +machines, it is often necessary to load each address into a register in +two parts. Then pieces of each address form separate immediate +operands. + +The code generated to initialize the trampoline must store the variable +parts---the static chain value and the function address---into the +immediate operands of the instructions. On a CISC machine, this is +simply a matter of copying each address to a memory reference at the +proper offset from the start of the trampoline. On a RISC machine, it +may be necessary to take out pieces of the address and store them +separately. + +@table @code +@findex TRAMPOLINE_TEMPLATE +@item TRAMPOLINE_TEMPLATE (@var{file}) +A C statement to output, on the stream @var{file}, assembler code for a +block of data that contains the constant parts of a trampoline. This +code should not include a label---the label is taken care of +automatically. + +@findex TRAMPOLINE_SECTION +@item TRAMPOLINE_SECTION +The name of a subroutine to switch to the section in which the +trampoline template is to be placed (@pxref{Sections}). The default is +a value of @samp{readonly_data_section}, which places the trampoline in +the section containing read-only data. + +@findex TRAMPOLINE_SIZE +@item TRAMPOLINE_SIZE +A C expression for the size in bytes of the trampoline, as an integer. + +@findex TRAMPOLINE_ALIGNMENT +@item TRAMPOLINE_ALIGNMENT +Alignment required for trampolines, in bits. + +If you don't define this macro, the value of @code{BIGGEST_ALIGNMENT} +is used for aligning trampolines. + +@findex INITIALIZE_TRAMPOLINE +@item INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain}) +A C statement to initialize the variable parts of a trampoline. +@var{addr} is an RTX for the address of the trampoline; @var{fnaddr} is +an RTX for the address of the nested function; @var{static_chain} is an +RTX for the static chain value that should be passed to the function +when it is called. + +@findex ALLOCATE_TRAMPOLINE +@item ALLOCATE_TRAMPOLINE (@var{fp}) +A C expression to allocate run-time space for a trampoline. The +expression value should be an RTX representing a memory reference to the +space for the trampoline. + +@cindex @code{FUNCTION_EPILOGUE} and trampolines +@cindex @code{FUNCTION_PROLOGUE} and trampolines +If this macro is not defined, by default the trampoline is allocated as +a stack slot. This default is right for most machines. The exceptions +are machines where it is impossible to execute instructions in the stack +area. On such machines, you may have to implement a separate stack, +using this macro in conjunction with @code{FUNCTION_PROLOGUE} and +@code{FUNCTION_EPILOGUE}. + +@var{fp} points to a data structure, a @code{struct function}, which +describes the compilation status of the immediate containing function of +the function which the trampoline is for. Normally (when +@code{ALLOCATE_TRAMPOLINE} is not defined), the stack slot for the +trampoline is in the stack frame of this containing function. Other +allocation strategies probably must do something analogous with this +information. +@end table + +Implementing trampolines is difficult on many machines because they have +separate instruction and data caches. Writing into a stack location +fails to clear the memory in the instruction cache, so when the program +jumps to that location, it executes the old contents. + +Here are two possible solutions. One is to clear the relevant parts of +the instruction cache whenever a trampoline is set up. The other is to +make all trampolines identical, by having them jump to a standard +subroutine. The former technique makes trampoline execution faster; the +latter makes initialization faster. + +To clear the instruction cache when a trampoline is initialized, define +the following macros which describe the shape of the cache. + +@table @code +@findex INSN_CACHE_SIZE +@item INSN_CACHE_SIZE +The total size in bytes of the cache. + +@findex INSN_CACHE_LINE_WIDTH +@item INSN_CACHE_LINE_WIDTH +The length in bytes of each cache line. The cache is divided into cache +lines which are disjoint slots, each holding a contiguous chunk of data +fetched from memory. Each time data is brought into the cache, an +entire line is read at once. The data loaded into a cache line is +always aligned on a boundary equal to the line size. + +@findex INSN_CACHE_DEPTH +@item INSN_CACHE_DEPTH +The number of alternative cache lines that can hold any particular memory +location. +@end table + +Alternatively, if the machine has system calls or instructions to clear +the instruction cache directly, you can define the following macro. + +@table @code +@findex CLEAR_INSN_CACHE +@item CLEAR_INSN_CACHE (@var{BEG}, @var{END}) +If defined, expands to a C expression clearing the @emph{instruction +cache} in the specified interval. If it is not defined, and the macro +INSN_CACHE_SIZE is defined, some generic code is generated to clear the +cache. The definition of this macro would typically be a series of +@code{asm} statements. Both @var{BEG} and @var{END} are both pointer +expressions. +@end table + +To use a standard subroutine, define the following macro. In addition, +you must make sure that the instructions in a trampoline fill an entire +cache line with identical instructions, or else ensure that the +beginning of the trampoline code is always aligned at the same point in +its cache line. Look in @file{m68k.h} as a guide. + +@table @code +@findex TRANSFER_FROM_TRAMPOLINE +@item TRANSFER_FROM_TRAMPOLINE +Define this macro if trampolines need a special subroutine to do their +work. The macro should expand to a series of @code{asm} statements +which will be compiled with GNU CC. They go in a library function named +@code{__transfer_from_trampoline}. + +If you need to avoid executing the ordinary prologue code of a compiled +C function when you jump to the subroutine, you can do so by placing a +special label of your own in the assembler code. Use one @code{asm} +statement to generate an assembler label, and another to make the label +global. Then trampolines can use that label to jump directly to your +special assembler code. +@end table + +@node Library Calls +@section Implicit Calls to Library Routines +@cindex library subroutine names +@cindex @file{libgcc.a} + +@c prevent bad page break with this line +Here is an explanation of implicit calls to library routines. + +@table @code +@findex MULSI3_LIBCALL +@item MULSI3_LIBCALL +A C string constant giving the name of the function to call for +multiplication of one signed full-word by another. If you do not +define this macro, the default name is used, which is @code{__mulsi3}, +a function defined in @file{libgcc.a}. + +@findex DIVSI3_LIBCALL +@item DIVSI3_LIBCALL +A C string constant giving the name of the function to call for +division of one signed full-word by another. If you do not define +this macro, the default name is used, which is @code{__divsi3}, a +function defined in @file{libgcc.a}. + +@findex UDIVSI3_LIBCALL +@item UDIVSI3_LIBCALL +A C string constant giving the name of the function to call for +division of one unsigned full-word by another. If you do not define +this macro, the default name is used, which is @code{__udivsi3}, a +function defined in @file{libgcc.a}. + +@findex MODSI3_LIBCALL +@item MODSI3_LIBCALL +A C string constant giving the name of the function to call for the +remainder in division of one signed full-word by another. If you do +not define this macro, the default name is used, which is +@code{__modsi3}, a function defined in @file{libgcc.a}. + +@findex UMODSI3_LIBCALL +@item UMODSI3_LIBCALL +A C string constant giving the name of the function to call for the +remainder in division of one unsigned full-word by another. If you do +not define this macro, the default name is used, which is +@code{__umodsi3}, a function defined in @file{libgcc.a}. + +@findex MULDI3_LIBCALL +@item MULDI3_LIBCALL +A C string constant giving the name of the function to call for +multiplication of one signed double-word by another. If you do not +define this macro, the default name is used, which is @code{__muldi3}, +a function defined in @file{libgcc.a}. + +@findex DIVDI3_LIBCALL +@item DIVDI3_LIBCALL +A C string constant giving the name of the function to call for +division of one signed double-word by another. If you do not define +this macro, the default name is used, which is @code{__divdi3}, a +function defined in @file{libgcc.a}. + +@findex UDIVDI3_LIBCALL +@item UDIVDI3_LIBCALL +A C string constant giving the name of the function to call for +division of one unsigned full-word by another. If you do not define +this macro, the default name is used, which is @code{__udivdi3}, a +function defined in @file{libgcc.a}. + +@findex MODDI3_LIBCALL +@item MODDI3_LIBCALL +A C string constant giving the name of the function to call for the +remainder in division of one signed double-word by another. If you do +not define this macro, the default name is used, which is +@code{__moddi3}, a function defined in @file{libgcc.a}. + +@findex UMODDI3_LIBCALL +@item UMODDI3_LIBCALL +A C string constant giving the name of the function to call for the +remainder in division of one unsigned full-word by another. If you do +not define this macro, the default name is used, which is +@code{__umoddi3}, a function defined in @file{libgcc.a}. + +@findex INIT_TARGET_OPTABS +@item INIT_TARGET_OPTABS +Define this macro as a C statement that declares additional library +routines renames existing ones. @code{init_optabs} calls this macro after +initializing all the normal library routines. + +@findex TARGET_EDOM +@cindex @code{EDOM}, implicit usage +@item TARGET_EDOM +The value of @code{EDOM} on the target machine, as a C integer constant +expression. If you don't define this macro, GNU CC does not attempt to +deposit the value of @code{EDOM} into @code{errno} directly. Look in +@file{/usr/include/errno.h} to find the value of @code{EDOM} on your +system. + +If you do not define @code{TARGET_EDOM}, then compiled code reports +domain errors by calling the library function and letting it report the +error. If mathematical functions on your system use @code{matherr} when +there is an error, then you should leave @code{TARGET_EDOM} undefined so +that @code{matherr} is used normally. + +@findex GEN_ERRNO_RTX +@cindex @code{errno}, implicit usage +@item GEN_ERRNO_RTX +Define this macro as a C expression to create an rtl expression that +refers to the global ``variable'' @code{errno}. (On certain systems, +@code{errno} may not actually be a variable.) If you don't define this +macro, a reasonable default is used. + +@findex TARGET_MEM_FUNCTIONS +@cindex @code{bcopy}, implicit usage +@cindex @code{memcpy}, implicit usage +@cindex @code{bzero}, implicit usage +@cindex @code{memset}, implicit usage +@item TARGET_MEM_FUNCTIONS +Define this macro if GNU CC should generate calls to the System V +(and ANSI C) library functions @code{memcpy} and @code{memset} +rather than the BSD functions @code{bcopy} and @code{bzero}. + +@findex LIBGCC_NEEDS_DOUBLE +@item LIBGCC_NEEDS_DOUBLE +Define this macro if only @code{float} arguments cannot be passed to +library routines (so they must be converted to @code{double}). This +macro affects both how library calls are generated and how the library +routines in @file{libgcc1.c} accept their arguments. It is useful on +machines where floating and fixed point arguments are passed +differently, such as the i860. + +@findex FLOAT_ARG_TYPE +@item FLOAT_ARG_TYPE +Define this macro to override the type used by the library routines to +pick up arguments of type @code{float}. (By default, they use a union +of @code{float} and @code{int}.) + +The obvious choice would be @code{float}---but that won't work with +traditional C compilers that expect all arguments declared as @code{float} +to arrive as @code{double}. To avoid this conversion, the library routines +ask for the value as some other type and then treat it as a @code{float}. + +On some systems, no other type will work for this. For these systems, +you must use @code{LIBGCC_NEEDS_DOUBLE} instead, to force conversion of +the values @code{double} before they are passed. + +@findex FLOATIFY +@item FLOATIFY (@var{passed-value}) +Define this macro to override the way library routines redesignate a +@code{float} argument as a @code{float} instead of the type it was +passed as. The default is an expression which takes the @code{float} +field of the union. + +@findex FLOAT_VALUE_TYPE +@item FLOAT_VALUE_TYPE +Define this macro to override the type used by the library routines to +return values that ought to have type @code{float}. (By default, they +use @code{int}.) + +The obvious choice would be @code{float}---but that won't work with +traditional C compilers gratuitously convert values declared as +@code{float} into @code{double}. + +@findex INTIFY +@item INTIFY (@var{float-value}) +Define this macro to override the way the value of a +@code{float}-returning library routine should be packaged in order to +return it. These functions are actually declared to return type +@code{FLOAT_VALUE_TYPE} (normally @code{int}). + +These values can't be returned as type @code{float} because traditional +C compilers would gratuitously convert the value to a @code{double}. + +A local variable named @code{intify} is always available when the macro +@code{INTIFY} is used. It is a union of a @code{float} field named +@code{f} and a field named @code{i} whose type is +@code{FLOAT_VALUE_TYPE} or @code{int}. + +If you don't define this macro, the default definition works by copying +the value through that union. + +@findex nongcc_SI_type +@item nongcc_SI_type +Define this macro as the name of the data type corresponding to +@code{SImode} in the system's own C compiler. + +You need not define this macro if that type is @code{long int}, as it usually +is. + +@findex nongcc_word_type +@item nongcc_word_type +Define this macro as the name of the data type corresponding to the +word_mode in the system's own C compiler. + +You need not define this macro if that type is @code{long int}, as it usually +is. + +@findex perform_@dots{} +@item perform_@dots{} +Define these macros to supply explicit C statements to carry out various +arithmetic operations on types @code{float} and @code{double} in the +library routines in @file{libgcc1.c}. See that file for a full list +of these macros and their arguments. + +On most machines, you don't need to define any of these macros, because +the C compiler that comes with the system takes care of doing them. + +@findex NEXT_OBJC_RUNTIME +@item NEXT_OBJC_RUNTIME +Define this macro to generate code for Objective C message sending using +the calling convention of the NeXT system. This calling convention +involves passing the object, the selector and the method arguments all +at once to the method-lookup library function. + +The default calling convention passes just the object and the selector +to the lookup function, which returns a pointer to the method. +@end table + +@node Addressing Modes +@section Addressing Modes +@cindex addressing modes + +@c prevent bad page break with this line +This is about addressing modes. + +@table @code +@findex HAVE_POST_INCREMENT +@item HAVE_POST_INCREMENT +Define this macro if the machine supports post-increment addressing. + +@findex HAVE_PRE_INCREMENT +@findex HAVE_POST_DECREMENT +@findex HAVE_PRE_DECREMENT +@item HAVE_PRE_INCREMENT +@itemx HAVE_POST_DECREMENT +@itemx HAVE_PRE_DECREMENT +Similar for other kinds of addressing. + +@findex CONSTANT_ADDRESS_P +@item CONSTANT_ADDRESS_P (@var{x}) +A C expression that is 1 if the RTX @var{x} is a constant which +is a valid address. On most machines, this can be defined as +@code{CONSTANT_P (@var{x})}, but a few machines are more restrictive +in which constant addresses are supported. + +@findex CONSTANT_P +@code{CONSTANT_P} accepts integer-values expressions whose values are +not explicitly known, such as @code{symbol_ref}, @code{label_ref}, and +@code{high} expressions and @code{const} arithmetic expressions, in +addition to @code{const_int} and @code{const_double} expressions. + +@findex MAX_REGS_PER_ADDRESS +@item MAX_REGS_PER_ADDRESS +A number, the maximum number of registers that can appear in a valid +memory address. Note that it is up to you to specify a value equal to +the maximum number that @code{GO_IF_LEGITIMATE_ADDRESS} would ever +accept. + +@findex GO_IF_LEGITIMATE_ADDRESS +@item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label}) +A C compound statement with a conditional @code{goto @var{label};} +executed if @var{x} (an RTX) is a legitimate memory address on the +target machine for a memory operand of mode @var{mode}. + +It usually pays to define several simpler macros to serve as +subroutines for this one. Otherwise it may be too complicated to +understand. + +This macro must exist in two variants: a strict variant and a +non-strict one. The strict variant is used in the reload pass. It +must be defined so that any pseudo-register that has not been +allocated a hard register is considered a memory reference. In +contexts where some kind of register is required, a pseudo-register +with no hard register must be rejected. + +The non-strict variant is used in other passes. It must be defined to +accept all pseudo-registers in every context where some kind of +register is required. + +@findex REG_OK_STRICT +Compiler source files that want to use the strict variant of this +macro define the macro @code{REG_OK_STRICT}. You should use an +@code{#ifdef REG_OK_STRICT} conditional to define the strict variant +in that case and the non-strict variant otherwise. + +Subroutines to check for acceptable registers for various purposes (one +for base registers, one for index registers, and so on) are typically +among the subroutines used to define @code{GO_IF_LEGITIMATE_ADDRESS}. +Then only these subroutine macros need have two variants; the higher +levels of macros may be the same whether strict or not.@refill + +Normally, constant addresses which are the sum of a @code{symbol_ref} +and an integer are stored inside a @code{const} RTX to mark them as +constant. Therefore, there is no need to recognize such sums +specifically as legitimate addresses. Normally you would simply +recognize any @code{const} as legitimate. + +Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant +sums that are not marked with @code{const}. It assumes that a naked +@code{plus} indicates indexing. If so, then you @emph{must} reject such +naked constant sums as illegitimate addresses, so that none of them will +be given to @code{PRINT_OPERAND_ADDRESS}. + +@cindex @code{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 +@code{const}, you will have to look inside it to find the +@code{symbol_ref} in order to determine the section. @xref{Assembler +Format}. + +@findex saveable_obstack +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. + +You can check the information stored here into the @code{symbol_ref} in +the definitions of the macros @code{GO_IF_LEGITIMATE_ADDRESS} and +@code{PRINT_OPERAND_ADDRESS}. + +@findex REG_OK_FOR_BASE_P +@item REG_OK_FOR_BASE_P (@var{x}) +A C expression that is nonzero if @var{x} (assumed to be a @code{reg} +RTX) is valid for use as a base register. For hard registers, it +should always accept those which the hardware permits and reject the +others. Whether the macro accepts or rejects pseudo registers must be +controlled by @code{REG_OK_STRICT} as described above. This usually +requires two variant definitions, of which @code{REG_OK_STRICT} +controls the one actually used. + +@findex REG_OK_FOR_INDEX_P +@item REG_OK_FOR_INDEX_P (@var{x}) +A C expression that is nonzero if @var{x} (assumed to be a @code{reg} +RTX) is valid for use as an index register. + +The difference between an index register and a base register is that +the index register may be scaled. If an address involves the sum of +two registers, neither one of them scaled, then either one may be +labeled the ``base'' and the other the ``index''; but whichever +labeling is used must fit the machine's constraints of which registers +may serve in each capacity. The compiler will try both labelings, +looking for one that is valid, and will reload one or both registers +only if neither labeling works. + +@findex LEGITIMIZE_ADDRESS +@item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) +A C compound statement that attempts to replace @var{x} with a valid +memory address for an operand of mode @var{mode}. @var{win} will be a +C statement label elsewhere in the code; the macro definition may use + +@example +GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win}); +@end example + +@noindent +to avoid further processing if the address has become legitimate. + +@findex break_out_memory_refs +@var{x} will always be the result of a call to @code{break_out_memory_refs}, +and @var{oldx} will be the operand that was given to that function to produce +@var{x}. + +The code generated by this macro should not alter the substructure of +@var{x}. If it transforms @var{x} into a more legitimate form, it +should assign @var{x} (which will always be a C variable) a new value. + +It is not necessary for this macro to come up with a legitimate +address. The compiler has standard ways of doing so in all cases. In +fact, it is safe for this macro to do nothing. But often a +machine-dependent strategy can generate better code. + +@findex GO_IF_MODE_DEPENDENT_ADDRESS +@item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label}) +A C statement or compound statement with a conditional @code{goto +@var{label};} executed if memory address @var{x} (an RTX) can have +different meanings depending on the machine mode of the memory +reference it is used for or if the address is valid for some modes +but not others. + +Autoincrement and autodecrement addresses typically have mode-dependent +effects because the amount of the increment or decrement is the size +of the operand being addressed. Some machines have other mode-dependent +addresses. Many RISC machines have no mode-dependent addresses. + +You may assume that @var{addr} is a valid address for the machine. + +@findex LEGITIMATE_CONSTANT_P +@item LEGITIMATE_CONSTANT_P (@var{x}) +A C expression that is nonzero if @var{x} is a legitimate constant for +an immediate operand on the target machine. You can assume that +@var{x} satisfies @code{CONSTANT_P}, so you need not check this. In fact, +@samp{1} is a suitable definition for this macro on machines where +anything @code{CONSTANT_P} is valid.@refill +@end table + +@node Condition Code +@section Condition Code Status +@cindex condition code status + +@c prevent bad page break with this line +This describes the condition code status. + +@findex cc_status +The file @file{conditions.h} defines a variable @code{cc_status} to +describe how the condition code was computed (in case the interpretation of +the condition code depends on the instruction that it was set by). This +variable contains the RTL expressions on which the condition code is +currently based, and several standard flags. + +Sometimes additional machine-specific flags must be defined in the machine +description header file. It can also add additional machine-specific +information by defining @code{CC_STATUS_MDEP}. + +@table @code +@findex CC_STATUS_MDEP +@item CC_STATUS_MDEP +C code for a data type which is used for declaring the @code{mdep} +component of @code{cc_status}. It defaults to @code{int}. + +This macro is not used on machines that do not use @code{cc0}. + +@findex CC_STATUS_MDEP_INIT +@item CC_STATUS_MDEP_INIT +A C expression to initialize the @code{mdep} field to ``empty''. +The default definition does nothing, since most machines don't use +the field anyway. If you want to use the field, you should probably +define this macro to initialize it. + +This macro is not used on machines that do not use @code{cc0}. + +@findex NOTICE_UPDATE_CC +@item NOTICE_UPDATE_CC (@var{exp}, @var{insn}) +A C compound statement to set the components of @code{cc_status} +appropriately for an insn @var{insn} whose body is @var{exp}. It is +this macro's responsibility to recognize insns that set the condition +code as a byproduct of other activity as well as those that explicitly +set @code{(cc0)}. + +This macro is not used on machines that do not use @code{cc0}. + +If there are insns that do not set the condition code but do alter +other machine registers, this macro must check to see whether they +invalidate the expressions that the condition code is recorded as +reflecting. For example, on the 68000, insns that store in address +registers do not set the condition code, which means that usually +@code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such +insns. But suppose that the previous insn set the condition code +based on location @samp{a4@@(102)} and the current insn stores a new +value in @samp{a4}. Although the condition code is not changed by +this, it will no longer be true that it reflects the contents of +@samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter +@code{cc_status} in this case to say that nothing is known about the +condition code value. + +The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal +with the results of peephole optimization: insns whose patterns are +@code{parallel} RTXs containing various @code{reg}, @code{mem} or +constants which are just the operands. The RTL structure of these +insns is not sufficient to indicate what the insns actually do. What +@code{NOTICE_UPDATE_CC} should do when it sees one is just to run +@code{CC_STATUS_INIT}. + +A possible definition of @code{NOTICE_UPDATE_CC} is to call a function +that looks at an attribute (@pxref{Insn Attributes}) named, for example, +@samp{cc}. This avoids having detailed information about patterns in +two places, the @file{md} file and in @code{NOTICE_UPDATE_CC}. + +@findex EXTRA_CC_MODES +@item EXTRA_CC_MODES +A list of names to be used for additional modes for condition code +values in registers (@pxref{Jump Patterns}). These names are added +to @code{enum machine_mode} and all have class @code{MODE_CC}. By +convention, they should start with @samp{CC} and end with @samp{mode}. + +You should only define this macro if your machine does not use @code{cc0} +and only if additional modes are required. + +@findex EXTRA_CC_NAMES +@item EXTRA_CC_NAMES +A list of C strings giving the names for the modes listed in +@code{EXTRA_CC_MODES}. For example, the Sparc defines this macro and +@code{EXTRA_CC_MODES} as + +@smallexample +#define EXTRA_CC_MODES CC_NOOVmode, CCFPmode, CCFPEmode +#define EXTRA_CC_NAMES "CC_NOOV", "CCFP", "CCFPE" +@end smallexample + +This macro is not required if @code{EXTRA_CC_MODES} is not defined. + +@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 +@pxref{Jump Patterns} for a description of the reason for this +definition) + +@smallexample +#define SELECT_CC_MODE(OP,X,Y) \ + (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \ + ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \ + : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \ + || GET_CODE (X) == NEG) \ + ? CC_NOOVmode : CCmode)) +@end smallexample + +You need not define this macro if @code{EXTRA_CC_MODES} is not defined. + +@findex CANONICALIZE_COMPARISON +@item CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1}) +One some machines not all possible comparisons are defined, but you can +convert an invalid comparison into a valid one. For example, the Alpha +does not have a @code{GT} comparison, but you can use an @code{LT} +comparison instead and swap the order of the operands. + +On such machines, define this macro to be a C statement to do any +required conversions. @var{code} is the initial comparison code +and @var{op0} and @var{op1} are the left and right operands of the +comparison, respectively. You should modify @var{code}, @var{op0}, and +@var{op1} as required. + +GNU CC will not assume that the comparison resulting from this macro is +valid but will see if the resulting insn matches a pattern in the +@file{md} file. + +You need not define this macro if it would never change the comparison +code or operands. + +@findex REVERSIBLE_CC_MODE +@item REVERSIBLE_CC_MODE (@var{mode}) +A C expression whose value is one if it is always safe to reverse a +comparison whose mode is @var{mode}. If @code{SELECT_CC_MODE} +can ever return @var{mode} for a floating-point inequality comparison, +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 +inequality comparisons are always given @code{CCFPEmode}: + +@smallexample +#define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode) +@end smallexample + +@end table + +@node Costs +@section Describing Relative Costs of Operations +@cindex costs of instructions +@cindex relative costs +@cindex speed of instructions + +These macros let you describe the relative speed of various operations +on the target machine. + +@table @code +@findex CONST_COSTS +@item CONST_COSTS (@var{x}, @var{code}, @var{outer_code}) +A part of a C @code{switch} statement that describes the relative costs +of constant RTL expressions. It must contain @code{case} labels for +expression codes @code{const_int}, @code{const}, @code{symbol_ref}, +@code{label_ref} and @code{const_double}. Each case must ultimately +reach a @code{return} statement to return the relative cost of the use +of that kind of constant value in an expression. The cost may depend on +the precise value of the constant, which is available for examination in +@var{x}, and the rtx code of the expression in which it is contained, +found in @var{outer_code}. + +@var{code} is the expression code---redundant, since it can be +obtained with @code{GET_CODE (@var{x})}. + +@findex RTX_COSTS +@findex COSTS_N_INSNS +@item RTX_COSTS (@var{x}, @var{code}, @var{outer_code}) +Like @code{CONST_COSTS} but applies to nonconstant RTL expressions. +This can be used, for example, to indicate how costly a multiply +instruction is. In writing this macro, you can use the construct +@code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast +instructions. @var{outer_code} is the code of the expression in which +@var{x} is contained. + +This macro is optional; do not define it if the default cost assumptions +are adequate for the target machine. + +@findex ADDRESS_COST +@item ADDRESS_COST (@var{address}) +An expression giving the cost of an addressing mode that contains +@var{address}. If not defined, the cost is computed from +the @var{address} expression and the @code{CONST_COSTS} values. + +For most CISC machines, the default cost is a good approximation of the +true cost of the addressing mode. However, on RISC machines, all +instructions normally have the same length and execution time. Hence +all addresses will have equal costs. + +In cases where more than one form of an address is known, the form with +the lowest cost will be used. If multiple forms have the same, lowest, +cost, the one that is the most complex will be used. + +For example, suppose an address that is equal to the sum of a register +and a constant is used twice in the same basic block. When this macro +is not defined, the address will be computed in a register and memory +references will be indirect through that register. On machines where +the cost of the addressing mode containing the sum is no higher than +that of a simple indirect reference, this will produce an additional +instruction and possibly require an additional register. Proper +specification of this macro eliminates this overhead for such machines. + +Similar use of this macro is made in strength reduction of loops. + +@var{address} need not be valid as an address. In such a case, the cost +is not relevant and can be any value; invalid addresses need not be +assigned a different cost. + +On machines where an address involving more than one register is as +cheap as an address computation involving only one register, defining +@code{ADDRESS_COST} to reflect this can cause two registers to be live +over a region of code where only one would have been if +@code{ADDRESS_COST} were not defined in that manner. This effect should +be considered in the definition of this macro. Equivalent costs should +probably only be given to addresses with different numbers of registers +on machines with lots of registers. + +This macro will normally either not be defined or be defined as a +constant. + +@findex REGISTER_MOVE_COST +@item REGISTER_MOVE_COST (@var{from}, @var{to}) +A C expression for the cost of moving data from a register in class +@var{from} to one in class @var{to}. The classes are expressed using +the enumeration values such as @code{GENERAL_REGS}. A value of 4 is the +default; other values are interpreted relative to that. + +It is not required that the cost always equal 2 when @var{from} is the +same as @var{to}; on some machines it is expensive to move between +registers if they are not general registers. + +If reload sees an insn consisting of a single @code{set} between two +hard registers, and if @code{REGISTER_MOVE_COST} applied to their +classes returns a value of 2, reload does not check to ensure that the +constraints of the insn are met. Setting a cost of other than 2 will +allow reload to verify that the constraints are met. You should do this +if the @samp{mov@var{m}} pattern's constraints do not allow such copying. + +@findex MEMORY_MOVE_COST +@item MEMORY_MOVE_COST (@var{m}) +A C expression for the cost of moving data of mode @var{m} between a +register and memory. A value of 2 is the default; this cost is relative +to those in @code{REGISTER_MOVE_COST}. + +If moving between registers and memory is more expensive than between +two registers, you should define this macro to express the relative cost. + +@findex BRANCH_COST +@item BRANCH_COST +A C expression for the cost of a branch instruction. A value of 1 is +the default; other values are interpreted relative to that. +@end table + +Here are additional macros which do not specify precise relative costs, +but only that certain actions are more expensive than GNU CC would +ordinarily expect. + +@table @code +@findex SLOW_BYTE_ACCESS +@item SLOW_BYTE_ACCESS +Define this macro as a C expression which is nonzero if accessing less +than a word of memory (i.e. a @code{char} or a @code{short}) is no +faster than accessing a word of memory, i.e., if such access +require more than one instruction or if there is no difference in cost +between byte and (aligned) word loads. + +When this macro is not defined, the compiler will access a field by +finding the smallest containing object; when it is defined, a fullword +load will be used if alignment permits. Unless bytes accesses are +faster than word accesses, using word accesses is preferable since it +may eliminate subsequent memory access if subsequent accesses occur to +other fields in the same word of the structure, but to different bytes. + +@findex SLOW_ZERO_EXTEND +@item SLOW_ZERO_EXTEND +Define this macro if zero-extension (of a @code{char} or @code{short} +to an @code{int}) can be done faster if the destination is a register +that is known to be zero. + +If you define this macro, you must have instruction patterns that +recognize RTL structures like this: + +@smallexample +(set (strict_low_part (subreg:QI (reg:SI @dots{}) 0)) @dots{}) +@end smallexample + +@noindent +and likewise for @code{HImode}. + +@findex SLOW_UNALIGNED_ACCESS +@item SLOW_UNALIGNED_ACCESS +Define this macro to be the value 1 if unaligned accesses have a cost +many times greater than aligned accesses, for example if they are +emulated in a trap handler. + +When this macro is non-zero, the compiler will act as if +@code{STRICT_ALIGNMENT} were non-zero when generating code for block +moves. This can cause significantly more instructions to be produced. +Therefore, do not set this macro non-zero if unaligned accesses only add a +cycle or two to the time for a memory access. + +If the value of this macro is always zero, it need not be defined. + +@findex DONT_REDUCE_ADDR +@item DONT_REDUCE_ADDR +Define this macro to inhibit strength reduction of memory addresses. +(On some machines, such strength reduction seems to do harm rather +than good.) + +@findex MOVE_RATIO +@item MOVE_RATIO +The number of scalar move insns which should be generated instead of a +string move 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 NO_FUNCTION_CSE +@item NO_FUNCTION_CSE +Define this macro if it is as good or better to call a constant +function address than to call an address kept in a register. + +@findex NO_RECURSIVE_FUNCTION_CSE +@item NO_RECURSIVE_FUNCTION_CSE +Define this macro if it is as good or better for a function to call +itself with an explicit address than to call an address kept in a +register. + +@findex ADJUST_COST +@item ADJUST_COST (@var{insn}, @var{link}, @var{dep_insn}, @var{cost}) +A C statement (sans semicolon) to update the integer variable @var{cost} +based on the relationship between @var{insn} that is dependent on +@var{dep_insn} through the dependence @var{link}. The default is to +make no adjustment to @var{cost}. This can be used for example to +specify to the scheduler that an output- or anti-dependence does not +incur the same cost as a data-dependence. +@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 +@c the (...)? --mew 10feb93 + +An object file is divided into sections containing different types of +data. In the most common case, there are three sections: the @dfn{text +section}, which holds instructions and read-only data; the @dfn{data +section}, which holds initialized writable data; and the @dfn{bss +section}, which holds uninitialized data. Some systems have other kinds +of sections. + +The compiler must tell the assembler when to switch sections. These +macros control what commands to output to tell the assembler this. You +can also define additional sections. + +@table @code +@findex TEXT_SECTION_ASM_OP +@item TEXT_SECTION_ASM_OP +A C expression whose value is a string containing the assembler +operation that should precede instructions and read-only data. Normally +@code{".text"} is right. + +@findex DATA_SECTION_ASM_OP +@item DATA_SECTION_ASM_OP +A C expression whose value is a string containing the assembler +operation to identify the following data as writable initialized data. +Normally @code{".data"} is right. + +@findex SHARED_SECTION_ASM_OP +@item SHARED_SECTION_ASM_OP +if defined, a C expression whose value is a string containing the +assembler operation to identify the following data as shared data. If +not defined, @code{DATA_SECTION_ASM_OP} will be used. + +@findex INIT_SECTION_ASM_OP +@item INIT_SECTION_ASM_OP +if defined, a C expression whose value is a string containing the +assembler operation to identify the following data as initialization +code. If not defined, GNU CC will assume such a section does not +exist. + +@findex EXTRA_SECTIONS +@findex in_text +@findex in_data +@item EXTRA_SECTIONS +A list of names for sections other than the standard two, which are +@code{in_text} and @code{in_data}. You need not define this macro +on a system with no other sections (that GCC needs to use). + +@findex EXTRA_SECTION_FUNCTIONS +@findex text_section +@findex data_section +@item EXTRA_SECTION_FUNCTIONS +One or more functions to be defined in @file{varasm.c}. These +functions should do jobs analogous to those of @code{text_section} and +@code{data_section}, for your additional sections. Do not define this +macro if you do not define @code{EXTRA_SECTIONS}. + +@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}) +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. Select the section by calling @code{text_section} or one +of the alternatives for other sections. + +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}) +A C statement or statements to switch to the appropriate section for +output of @var{rtx} in mode @var{mode}. You can assume that @var{rtx} +is some kind of constant in RTL. The argument @var{mode} is redundant +except in the case of a @code{const_int} rtx. Select the section by +calling @code{text_section} or one of the alternatives for other +sections. + +Do not define this macro if you put all constants in the read-only +data section. + +@findex JUMP_TABLES_IN_TEXT_SECTION +@item JUMP_TABLES_IN_TEXT_SECTION +Define this macro if jump tables (for @code{tablejump} insns) should be +output in the text 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. + +@findex ENCODE_SECTION_INFO +@item ENCODE_SECTION_INFO (@var{decl}) +Define this macro if references to a symbol 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 immediately after the rtl for +@var{decl} 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}. + +@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 +@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. +@end table + +@node PIC +@section Position Independent Code +@cindex position independent code +@cindex PIC + +This section describes macros that help implement generation of position +independent code. Simply defining these macros is not enough to +generate valid PIC; you must also add support to the macros +@code{GO_IF_LEGITIMATE_ADDRESS} and @code{PRINT_OPERAND_ADDRESS}, as +well as @code{LEGITIMIZE_ADDRESS}. You must modify the definition of +@samp{movsi} to do something appropriate when the source operand +contains a symbolic address. You may also need to alter the handling of +switch statements so that they use relative addresses. +@c i rearranged the order of the macros above to try to force one of +@c them to the next line, to eliminate an overfull hbox. --mew 10feb93 + +@table @code +@findex PIC_OFFSET_TABLE_REGNUM +@item PIC_OFFSET_TABLE_REGNUM +The register number of the register used to address a table of static +data addresses in memory. In some cases this register is defined by a +processor's ``application binary interface'' (ABI). When this macro +is defined, RTL is generated for this register once, as with the stack +pointer and frame pointer registers. If this macro is not defined, it +is up to the machine-dependent files to allocate such a register (if +necessary). + +findex PIC_OFFSET_TABLE_REG_CALL_CLOBBERED +@item PIC_OFFSET_TABLE_REG_CALL_CLOBBERED +Define this macro if the register defined by +@code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. Do not define +this macro if @code{PPIC_OFFSET_TABLE_REGNUM} is not defined. + +@findex FINALIZE_PIC +@item FINALIZE_PIC +By generating position-independent code, when two different programs (A +and B) share a common library (libC.a), the text of the library can be +shared whether or not the library is linked at the same address for both +programs. In some of these environments, position-independent code +requires not only the use of different addressing modes, but also +special code to enable the use of these addressing modes. + +The @code{FINALIZE_PIC} macro serves as a hook to emit these special +codes once the function is being compiled into assembly code, but not +before. (It is not done before, because in the case of compiling an +inline function, it would lead to multiple PIC prologues being +included in functions which used inline functions and were compiled to +assembly language.) + +@findex LEGITIMATE_PIC_OPERAND_P +@item LEGITIMATE_PIC_OPERAND_P (@var{x}) +A C expression that is nonzero if @var{x} is a legitimate immediate +operand on the target machine when generating position independent code. +You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not +check this. You can also assume @var{flag_pic} is true, so you need not +check it either. You need not define this macro if all constants +(including @code{SYMBOL_REF}) can be immediate operands when generating +position independent code. +@end table + +@node Assembler Format +@section Defining the Output Assembler Language + +This section describes macros whose principal purpose is to describe how +to write instructions in assembler language--rather than what the +instructions do. + +@menu +* File Framework:: Structural information for the assembler file. +* Data Output:: Output of constants (numbers, strings, addresses). +* Uninitialized Data:: Output of uninitialized variables. +* Label Output:: Output and generation of labels. +* Initialization:: General principles of initialization + and termination routines. +* Macros for Initialization:: + Specific macros that control the handling of + initialization and termination routines. +* Instruction Output:: Output of actual instructions. +* Dispatch Tables:: Output of jump tables. +* Alignment Output:: Pseudo ops for alignment and skipping data. +@end menu + +@node File Framework +@subsection The Overall Framework of an Assembler File +@cindex assembler format +@cindex output of assembler code + +@c prevent bad page break with this line +This describes the overall framework of an assembler file. + +@table @code +@findex ASM_FILE_START +@item ASM_FILE_START (@var{stream}) +A C expression which outputs to the stdio stream @var{stream} +some appropriate text to go at the start of an assembler file. + +Normally this macro is defined to output a line containing +@samp{#NO_APP}, which is a comment that has no effect on most +assemblers but tells the GNU assembler that it can save time by not +checking for certain assembler constructs. + +On systems that use SDB, it is necessary to output certain commands; +see @file{attasm.h}. + +@findex ASM_FILE_END +@item ASM_FILE_END (@var{stream}) +A C expression which outputs to the stdio stream @var{stream} +some appropriate text to go at the end of an assembler file. + +If this macro is not defined, the default is to output nothing +special at the end of the file. Most systems don't require any +definition. + +On systems that use SDB, it is necessary to output certain commands; +see @file{attasm.h}. + +@findex ASM_IDENTIFY_GCC +@item ASM_IDENTIFY_GCC (@var{file}) +A C statement to output assembler commands which will identify +the object file as having been compiled with GNU CC (or another +GNU compiler). + +If you don't define this macro, the string @samp{gcc_compiled.:} +is output. This string is calculated to define a symbol which, +on BSD systems, will never be defined for any other reason. +GDB checks for the presence of this symbol when reading the +symbol table of an executable. + +On non-BSD systems, you must arrange communication with GDB in +some other fashion. If GDB is not used on your system, you can +define this macro with an empty body. + +@findex ASM_COMMENT_START +@item ASM_COMMENT_START +A C string constant describing how to begin a comment in the target +assembler language. The compiler assumes that the comment will end at +the end of the line. + +@findex ASM_APP_ON +@item ASM_APP_ON +A C string constant for text to be output before each @code{asm} +statement or group of consecutive ones. Normally this is +@code{"#APP"}, which is a comment that has no effect on most +assemblers but tells the GNU assembler that it must check the lines +that follow for all valid assembler constructs. + +@findex ASM_APP_OFF +@item ASM_APP_OFF +A C string constant for text to be output after each @code{asm} +statement or group of consecutive ones. Normally this is +@code{"#NO_APP"}, which tells the GNU assembler to resume making the +time-saving assumptions that are valid for ordinary compiler output. + +@findex ASM_OUTPUT_SOURCE_FILENAME +@item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) +A C statement to output COFF information or DWARF debugging information +which indicates that filename @var{name} is the current source file to +the stdio stream @var{stream}. + +This macro need not be defined if the standard form of output +for the file format in use is appropriate. + +@findex ASM_OUTPUT_SOURCE_LINE +@item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) +A C statement to output DBX or SDB debugging information before code +for line number @var{line} of the current source file to the +stdio stream @var{stream}. + +This macro need not be defined if the standard form of debugging +information for the debugger in use is appropriate. + +@findex ASM_OUTPUT_IDENT +@item ASM_OUTPUT_IDENT (@var{stream}, @var{string}) +A C statement to output something to the assembler file to handle a +@samp{#ident} directive containing the text @var{string}. If this +macro is not defined, nothing is output for a @samp{#ident} directive. + +@findex ASM_OUTPUT_SECTION_NAME +@item ASM_OUTPUT_SECTION_NAME (@var{stream}, @var{string}) +A C statement to output something to the assembler file to switch to the +section contained in @var{string}. Some target formats do not support +arbitrary sections. Do not define this macro in such cases. + +At present this macro is only used to support section attributes. +When this macro is undefined, section attributes are disabled. + +@findex OBJC_PROLOGUE +@item OBJC_PROLOGUE +A C statement to output any assembler statements which are required to +precede any Objective C object definitions or message sending. The +statement is executed only when compiling an Objective C program. +@end table + +@need 2000 +@node Data Output +@subsection Output of Data + +@c prevent bad page break with this line +This describes data output. + +@table @code +@findex ASM_OUTPUT_LONG_DOUBLE +@findex ASM_OUTPUT_DOUBLE +@findex ASM_OUTPUT_FLOAT +@item ASM_OUTPUT_LONG_DOUBLE (@var{stream}, @var{value}) +@itemx ASM_OUTPUT_DOUBLE (@var{stream}, @var{value}) +@itemx ASM_OUTPUT_FLOAT (@var{stream}, @var{value}) +@itemx ASM_OUTPUT_THREE_QUARTER_FLOAT (@var{stream}, @var{value}) +@itemx ASM_OUTPUT_SHORT_FLOAT (@var{stream}, @var{value}) +@itemx ASM_OUTPUT_BYTE_FLOAT (@var{stream}, @var{value}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to assemble a floating-point constant of @code{TFmode}, +@code{DFmode}, @code{SFmode}, @code{TQFmode}, @code{HFmode}, or +@code{QFmode}, respectively, whose value is @var{value}. @var{value} +will be a C expression of type @code{REAL_VALUE_TYPE}. Macros such as +@code{REAL_VALUE_TO_TARGET_DOUBLE} are useful for writing these +definitions. + +@findex ASM_OUTPUT_QUADRUPLE_INT +@findex ASM_OUTPUT_DOUBLE_INT +@findex ASM_OUTPUT_INT +@findex ASM_OUTPUT_SHORT +@findex ASM_OUTPUT_CHAR +@findex output_addr_const +@item ASM_OUTPUT_QUADRUPLE_INT (@var{stream}, @var{exp}) +@itemx ASM_OUTPUT_DOUBLE_INT (@var{stream}, @var{exp}) +@itemx ASM_OUTPUT_INT (@var{stream}, @var{exp}) +@itemx ASM_OUTPUT_SHORT (@var{stream}, @var{exp}) +@itemx ASM_OUTPUT_CHAR (@var{stream}, @var{exp}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to assemble an integer of 16, 8, 4, 2 or 1 bytes, +respectively, whose value is @var{value}. The argument @var{exp} will +be an RTL expression which represents a constant value. Use +@samp{output_addr_const (@var{stream}, @var{exp})} to output this value +as an assembler expression.@refill + +For sizes larger than @code{UNITS_PER_WORD}, if the action of a macro +would be identical to repeatedly calling the macro corresponding to +a size of @code{UNITS_PER_WORD}, once for each word, you need not define +the macro. + +@findex ASM_OUTPUT_BYTE +@item ASM_OUTPUT_BYTE (@var{stream}, @var{value}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to assemble a single byte containing the number @var{value}. + +@findex ASM_BYTE_OP +@item ASM_BYTE_OP +A C string constant giving the pseudo-op to use for a sequence of +single-byte constants. If this macro is not defined, the default is +@code{"byte"}. + +@findex ASM_OUTPUT_ASCII +@item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to assemble a string constant containing the @var{len} +bytes at @var{ptr}. @var{ptr} will be a C expression of type +@code{char *} and @var{len} a C expression of type @code{int}. + +If the assembler has a @code{.ascii} pseudo-op as found in the +Berkeley Unix assembler, do not define the macro +@code{ASM_OUTPUT_ASCII}. + +@findex ASM_OUTPUT_POOL_PROLOGUE +@item ASM_OUTPUT_POOL_PROLOGUE (@var{file} @var{funname} @var{fundecl} @var{size}) +A C statement to output assembler commands to define the start of the +constant pool for a function. @var{funname} is a string giving +the name of the function. Should the return type of the function +be required, it can be obtained via @var{fundecl}. @var{size} +is the size, in bytes, of the constant pool that will be written +immediately after this call. + +If no constant-pool prefix is required, the usual case, this macro need +not be defined. + +@findex ASM_OUTPUT_SPECIAL_POOL_ENTRY +@item ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto}) +A C statement (with or without semicolon) to output a constant in the +constant pool, if it needs special treatment. (This macro need not do +anything for RTL expressions that can be output normally.) + +The argument @var{file} is the standard I/O stream to output the +assembler code on. @var{x} is the RTL expression for the constant to +output, and @var{mode} is the machine mode (in case @var{x} is a +@samp{const_int}). @var{align} is the required alignment for the value +@var{x}; you should output an assembler directive to force this much +alignment. + +The argument @var{labelno} is a number to use in an internal label for +the address of this pool entry. The definition of this macro is +responsible for outputting the label definition at the proper place. +Here is how to do this: + +@example +ASM_OUTPUT_INTERNAL_LABEL (@var{file}, "LC", @var{labelno}); +@end example + +When you output a pool entry specially, you should end with a +@code{goto} to the label @var{jumpto}. This will prevent the same pool +entry from being output a second time in the usual manner. + +You need not define this macro if it would do nothing. + +@findex IS_ASM_LOGICAL_LINE_SEPARATOR +@item IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C}) +Define this macro as a C expression which is nonzero if @var{C} is +used as a logical line separator by the assembler. + +If you do not define this macro, the default is that only +the character @samp{;} is treated as a logical line separator. + + +@findex ASM_OPEN_PAREN +@findex ASM_CLOSE_PAREN +@item ASM_OPEN_PAREN +@itemx ASM_CLOSE_PAREN +These macros are defined as C string constant, describing the syntax +in the assembler for grouping arithmetic expressions. The following +definitions are correct for most assemblers: + +@example +#define ASM_OPEN_PAREN "(" +#define ASM_CLOSE_PAREN ")" +@end example +@end table + + These macros are provided by @file{real.h} for writing the definitions +of @code{ASM_OUTPUT_DOUBLE} and the like: + +@table @code +@item REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l}) +@itemx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l}) +@itemx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l}) +@findex REAL_VALUE_TO_TARGET_SINGLE +@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. + +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 +@subsection Output of Uninitialized Variables + +Each of the macros in this section is used to do the whole job of +outputting a single uninitialized variable. + +@table @code +@findex ASM_OUTPUT_COMMON +@item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} the assembler definition of a common-label named +@var{name} whose size is @var{size} bytes. The variable @var{rounded} +is the size rounded up to whatever alignment the caller wants. + +Use the expression @code{assemble_name (@var{stream}, @var{name})} to +output the name itself; before and after that, output the additional +assembler syntax for defining the name, and a newline. + +This macro controls how the assembler definitions of uninitialized +global variables are output. + +@findex ASM_OUTPUT_ALIGNED_COMMON +@item ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment}) +Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a +separate, explicit argument. If you define this macro, it is used in +place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in +handling the required alignment of the variable. The alignment is specified +as the number of bits. + +@findex ASM_OUTPUT_SHARED_COMMON +@item ASM_OUTPUT_SHARED_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded}) +If defined, it is similar to @code{ASM_OUTPUT_COMMON}, except that it +is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_COMMON} +will be used. + +@findex ASM_OUTPUT_LOCAL +@item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} the assembler definition of a local-common-label named +@var{name} whose size is @var{size} bytes. The variable @var{rounded} +is the size rounded up to whatever alignment the caller wants. + +Use the expression @code{assemble_name (@var{stream}, @var{name})} to +output the name itself; before and after that, output the additional +assembler syntax for defining the name, and a newline. + +This macro controls how the assembler definitions of uninitialized +static variables are output. + +@findex ASM_OUTPUT_ALIGNED_LOCAL +@item ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment}) +Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a +separate, explicit argument. If you define this macro, it is used in +place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in +handling the required alignment of the variable. The alignment is specified +as the number of bits. + +@findex ASM_OUTPUT_SHARED_LOCAL +@item ASM_OUTPUT_SHARED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded}) +If defined, it is similar to @code{ASM_OUTPUT_LOCAL}, except that it +is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_LOCAL} +will be used. +@end table + +@node Label Output +@subsection Output and Generation of Labels + +@c prevent bad page break with this line +This is about outputting labels. + +@table @code +@findex ASM_OUTPUT_LABEL +@findex assemble_name +@item ASM_OUTPUT_LABEL (@var{stream}, @var{name}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} the assembler definition of a label named @var{name}. +Use the expression @code{assemble_name (@var{stream}, @var{name})} to +output the name itself; before and after that, output the additional +assembler syntax for defining the name, and a newline. + +@findex ASM_DECLARE_FUNCTION_NAME +@item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} any text necessary for declaring the name @var{name} of a +function which is being defined. This macro is responsible for +outputting the label definition (perhaps using +@code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the +@code{FUNCTION_DECL} tree node representing the function. + +If this macro is not defined, then the function name is defined in the +usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). + +@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 +@var{stream} any text necessary for declaring the size of a function +which is being defined. The argument @var{name} is the name of the +function. The argument @var{decl} is the @code{FUNCTION_DECL} tree node +representing the function. + +If this macro is not defined, then the function size is not defined. + +@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 +@var{stream} any text necessary for declaring the name @var{name} of an +initialized variable which is being defined. This macro must output the +label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument +@var{decl} is the @code{VAR_DECL} tree node representing the variable. + +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}). + +@findex ASM_FINISH_DECLARE_OBJECT +@item ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend}) +A C statement (sans semicolon) to finish up declaring a variable name +once the compiler has processed its initializer fully and thus has had a +chance to determine the size of an array when controlled by an +initializer. This is used on systems where it's necessary to declare +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 +@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. + +@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 +@var{stream} any text necessary for declaring the name of an external +symbol named @var{name} which is referenced in this compilation but +not defined. The value of @var{decl} is the tree node for the +declaration. + +This macro need not be defined if it does not need to output anything. +The GNU assembler and most Unix assemblers don't require anything. + +@findex ASM_OUTPUT_EXTERNAL_LIBCALL +@item ASM_OUTPUT_EXTERNAL_LIBCALL (@var{stream}, @var{symref}) +A C statement (sans semicolon) to output on @var{stream} an assembler +pseudo-op to declare a library function name external. The name of the +library function is given by @var{symref}, which has type @code{rtx} and +is a @code{symbol_ref}. + +This macro need not be defined if it does not need to output anything. +The GNU assembler and most Unix assemblers don't require anything. + +@findex ASM_OUTPUT_LABELREF +@item ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) +A C statement (sans semicolon) to output to the stdio stream +@var{stream} a reference in assembler syntax to a label named +@var{name}. This should add @samp{_} to the front of the name, if that +is customary on your operating system, as it is in most Berkeley Unix +systems. This macro is used in @code{assemble_name}. + +@ignore @c Seems not to exist anymore. +@findex ASM_OUTPUT_LABELREF_AS_INT +@item ASM_OUTPUT_LABELREF_AS_INT (@var{file}, @var{label}) +Define this macro for systems that use the program @code{collect2}. +The definition should be a C statement to output a word containing +a reference to the label @var{label}. +@end ignore + +@findex ASM_OUTPUT_INTERNAL_LABEL +@item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) +A C statement to output to the stdio stream @var{stream} a label whose +name is made from the string @var{prefix} and the number @var{num}. + +It is absolutely essential that these labels be distinct from the labels +used for user-level functions and variables. Otherwise, certain programs +will have name conflicts with internal labels. + +It is desirable to exclude internal labels from the symbol table of the +object file. Most assemblers have a naming convention for labels that +should be excluded; on many systems, the letter @samp{L} at the +beginning of a label has this effect. You should find out what +convention your system uses, and follow it. + +The usual definition of this macro is as follows: + +@example +fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num}) +@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 +is made from the string @var{prefix} and the number @var{num}. + +This string, when output subsequently by @code{assemble_name}, should +produce the output that @code{ASM_OUTPUT_INTERNAL_LABEL} would produce +with the same @var{prefix} and @var{num}. + +If the string begins with @samp{*}, then @code{assemble_name} will +output the rest of the string unchanged. It is often convenient for +@code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the +string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets +to output the string, and may change it. (Of course, +@code{ASM_OUTPUT_LABELREF} is also part of your machine description, so +you should know what it does on your machine.) + +@findex ASM_FORMAT_PRIVATE_NAME +@item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number}) +A C expression to assign to @var{outvar} (which is a variable of type +@code{char *}) a newly allocated string made from the string +@var{name} and the number @var{number}, with some suitable punctuation +added. Use @code{alloca} to get space for the string. + +The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to +produce an assembler label for an internal static variable whose name is +@var{name}. Therefore, the string must be such as to result in valid +assembler code. The argument @var{number} is different each time this +macro is executed; it prevents conflicts between similarly-named +internal static variables in different scopes. + +Ideally this string should not be a valid C identifier, to prevent any +conflict with the user's own symbols. Most assemblers allow periods +or percent signs in assembler symbols; putting at least one of these +between the name and the number will suffice. + +@findex ASM_OUTPUT_DEF +@item ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value}) +A C statement to output to the stdio stream @var{stream} assembler code +which defines (equates) the symbol @var{name} to have the value @var{value}. + +If SET_ASM_OP is defined, a default definition is provided which is +correct for most systems. +@findex OBJC_GEN_METHOD_LABEL +@item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name}) +Define this macro to override the default assembler names used for +Objective C methods. + +The default name is a unique method number followed by the name of the +class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of +the category is also included in the assembler name (e.g.@: +@samp{_1_Foo_Bar}). + +These names are safe on most systems, but make debugging difficult since +the method's selector is not present in the name. Therefore, particular +systems define other ways of computing names. + +@var{buf} is an expression of type @code{char *} which gives you a +buffer in which to store the name; its length is as long as +@var{class_name}, @var{cat_name} and @var{sel_name} put together, plus +50 characters extra. + +The argument @var{is_inst} specifies whether the method is an instance +method or a class method; @var{class_name} is the name of the class; +@var{cat_name} is the name of the category (or NULL if the method is not +in a category); and @var{sel_name} is the name of the selector. + +On systems where the assembler can handle quoted names, you can use this +macro to provide more human-readable names. +@end table + +@node Initialization +@subsection How Initialization Functions Are Handled +@cindex initialization routines +@cindex termination routines +@cindex constructors, output of +@cindex destructors, output of + +The compiled code for certain languages includes @dfn{constructors} +(also called @dfn{initialization routines})---functions to initialize +data in the program when the program is started. These functions need +to be called before the program is ``started''---that is to say, before +@code{main} is called. + +Compiling some languages generates @dfn{destructors} (also called +@dfn{termination routines}) that should be called when the program +terminates. + +To make the initialization and termination functions work, the compiler +must output something in the assembler code to cause those functions to +be called at the appropriate time. When you port the compiler to a new +system, you need to specify how to do this. + +There are two major ways that GCC currently supports the execution of +initialization and termination functions. Each way has two variants. +Much of the structure is common to all four variations. + +@findex __CTOR_LIST__ +@findex __DTOR_LIST__ +The linker must build two lists of these functions---a list of +initialization functions, called @code{__CTOR_LIST__}, and a list of +termination functions, called @code{__DTOR_LIST__}. + +Each list always begins with an ignored function pointer (which may hold +0, @minus{}1, or a count of the function pointers after it, depending on +the environment). This is followed by a series of zero or more function +pointers to constructors (or destructors), followed by a function +pointer containing zero. + +Depending on the operating system and its executable file format, either +@file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup +time and exit time. Constructors are called in forward order of the +list; destructors in reverse order. + +The best way to handle static constructors works only for object file +formats which provide arbitrarily-named sections. A section is set +aside for a list of constructors, and another for a list of destructors. +Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each +object file that defines an initialization function also puts a word in +the constructor section to point to that function. The linker +accumulates all these words into one contiguous @samp{.ctors} section. +Termination functions are handled similarly. + +To use this method, you need appropriate definitions of the macros +@code{ASM_OUTPUT_CONSTRUCTOR} and @code{ASM_OUTPUT_DESTRUCTOR}. Usually +you can get them by including @file{svr4.h}. + +When arbitrary sections are available, there are two variants, depending +upon how the code in @file{crtstuff.c} is called. On systems that +support an @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: + +@example +ld -o @var{output_file} crtbegin.o @dots{} crtend.o -lgcc +@end example + +The head of a function (@code{__do_global_ctors}) appears in the init +section of @file{crtbegin.o}; the remainder of the function appears in +the init section of @file{crtend.o}. The linker will pull these two +parts of the section together, making a whole function. If any of the +user's object files linked into the middle of it contribute code, then that +code will be executed as part of the body of @code{__do_global_ctors}. + +To use this variant, you must define the @code{INIT_SECTION_ASM_OP} +macro properly. + +If no init section is available, do not define +@code{INIT_SECTION_ASM_OP}. Then @code{__do_global_ctors} is built into +the text section like all other functions, and resides in +@file{libgcc.a}. When GCC compiles any function called @code{main}, it +inserts a procedure call to @code{__main} as the first executable code +after the function prologue. The @code{__main} function, also defined +in @file{libgcc2.c}, simply calls @file{__do_global_ctors}. + +In file formats that don't support arbitrary sections, there are again +two variants. In the simplest variant, the GNU linker (GNU @code{ld}) +and an `a.out' format must be used. In this case, +@code{ASM_OUTPUT_CONSTRUCTOR} is defined to produce a @code{.stabs} +entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__}, +and with the address of the void function containing the initialization +code as its value. The GNU linker recognizes this as a request to add +the value to a ``set''; the values are accumulated, and are eventually +placed in the executable as a vector in the format described above, with +a leading (ignored) count and a trailing zero element. +@code{ASM_OUTPUT_DESTRUCTOR} is handled similarly. Since no init +section is available, the absence of @code{INIT_SECTION_ASM_OP} causes +the compilation of @code{main} to call @code{__main} as above, starting +the initialization process. + +The last variant uses neither arbitrary sections nor the GNU linker. +This is preferable when you want to do dynamic linking and when using +file formats which the GNU linker does not support, such as `ECOFF'. In +this case, @code{ASM_OUTPUT_CONSTRUCTOR} does not produce an +@code{N_SETT} symbol; initialization and termination functions are +recognized simply by their names. This requires an extra program in the +linkage step, called @code{collect2}. This program pretends to be the +linker, for use with GNU CC; it does its job by running the ordinary +linker, but also arranges to include the vectors of initialization and +termination functions. These functions are called via @code{__main} as +described above. + +Choosing among these configuration options has been simplified by a set +of operating-system-dependent files in the @file{config} subdirectory. +These files define all of the relevant parameters. Usually it is +sufficient to include one into your specific machine-dependent +configuration file. These files are: + +@table @file +@item aoutos.h +For operating systems using the `a.out' format. + +@item next.h +For operating systems using the `MachO' format. + +@item svr3.h +For System V Release 3 and similar systems using `COFF' format. + +@item svr4.h +For System V Release 4 and similar systems using `ELF' format. + +@item vms.h +For the VMS operating system. +@end table + +@ifinfo +The following section describes the specific macros that control and +customize the handling of initialization and termination functions. +@end ifinfo + +@node Macros for Initialization +@subsection Macros Controlling Initialization Routines + +Here are the macros that control how the compiler handles initialization +and termination functions: + +@table @code +@findex INIT_SECTION_ASM_OP +@item INIT_SECTION_ASM_OP +If defined, a C string constant for the assembler operation to identify +the following data as initialization code. If not defined, GNU CC will +assume such a section does not exist. When you are using special +sections for initialization and termination functions, this macro also +controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to run the +initialization functions. + +@item HAS_INIT_SECTION +@findex HAS_INIT_SECTION +If defined, @code{main} will not call @code{__main} as described above. +This macro should be defined for systems that control the contents of the +init section on a symbol-by-symbol basis, such as OSF/1, and should not +be defined explicitly for systems that support +@code{INIT_SECTION_ASM_OP}. + +@item INVOKE__main +@findex INVOKE__main +If defined, @code{main} will call @code{__main} despite the presence of +@code{INIT_SECTION_ASM_OP}. This macro should be defined for systems +where the init section is not actually run automatically, but is still +useful for collecting the lists of constructors and destructors. + +@item ASM_OUTPUT_CONSTRUCTOR (@var{stream}, @var{name}) +@findex ASM_OUTPUT_CONSTRUCTOR +Define this macro as a C statement to output on the stream @var{stream} +the assembler code to arrange to call the function named @var{name} at +initialization time. + +Assume that @var{name} is the name of a C function generated +automatically by the compiler. This function takes no arguments. Use +the function @code{assemble_name} to output the name @var{name}; this +performs any system-specific syntactic transformations such as adding an +underscore. + +If you don't define this macro, nothing special is output to arrange to +call the function. This is correct when the function will be called in +some other manner---for example, by means of the @code{collect2} program, +which looks through the symbol table to find these functions by their +names. + +@item ASM_OUTPUT_DESTRUCTOR (@var{stream}, @var{name}) +@findex ASM_OUTPUT_DESTRUCTOR +This is like @code{ASM_OUTPUT_CONSTRUCTOR} but used for termination +functions rather than initialization functions. +@end table + +If your system uses @code{collect2} as the means of processing +constructors, then that program normally uses @code{nm} to scan an +object file for constructor functions to be called. On certain kinds of +systems, you can define these macros to make @code{collect2} work faster +(and, in some cases, make it work at all): + +@table @code +@findex OBJECT_FORMAT_COFF +@item OBJECT_FORMAT_COFF +Define this macro if the system uses COFF (Common Object File Format) +object files, so that @code{collect2} can assume this format and scan +object files directly for dynamic constructor/destructor functions. + +@findex OBJECT_FORMAT_ROSE +@item OBJECT_FORMAT_ROSE +Define this macro if the system uses ROSE format object files, so that +@code{collect2} can assume this format and scan object files directly +for dynamic constructor/destructor functions. + +@findex REAL_NM_FILE_NAME +@item REAL_NM_FILE_NAME +Define this macro as a C string constant containing the file name to use +to execute @code{nm}. The default is to search the path normally for +@code{nm}. +@end table + +These macros are effective only in a native compiler; @code{collect2} as +part of a cross compiler always uses @code{nm} for the target machine. + +@node Instruction Output +@subsection Output of Assembler Instructions + +@c prevent bad page break with this line +This describes assembler instruction output. + +@table @code +@findex REGISTER_NAMES +@item REGISTER_NAMES +A C initializer containing the assembler's names for the machine +registers, each one as a C string constant. This is what translates +register numbers in the compiler into assembler language. + +@findex ADDITIONAL_REGISTER_NAMES +@item ADDITIONAL_REGISTER_NAMES +If defined, a C initializer for an array of structures containing a name +and a register number. This macro defines additional names for hard +registers, thus allowing the @code{asm} option in declarations to refer +to registers using alternate names. + +@findex ASM_OUTPUT_OPCODE +@item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr}) +Define this macro if you are using an unusual assembler that +requires different names for the machine instructions. + +The definition is a C statement or statements which output an +assembler instruction opcode to the stdio stream @var{stream}. The +macro-operand @var{ptr} is a variable of type @code{char *} which +points to the opcode name in its ``internal'' form---the form that is +written in the machine description. The definition should output the +opcode name to @var{stream}, performing any translation you desire, and +increment the variable @var{ptr} to point at the end of the opcode +so that it will not be output twice. + +In fact, your macro definition may process less than the entire opcode +name, or more than the opcode name; but if you want to process text +that includes @samp{%}-sequences to substitute operands, you must take +care of the substitution yourself. Just be sure to increment +@var{ptr} over whatever text should not be output normally. + +@findex recog_operand +If you need to look at the operand values, they can be found as the +elements of @code{recog_operand}. + +If the macro definition does nothing, the instruction is output +in the usual way. + +@findex FINAL_PRESCAN_INSN +@item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) +If defined, a C statement to be executed just prior to the output of +assembler code for @var{insn}, to modify the extracted operands so +they will be output differently. + +Here the argument @var{opvec} is the vector containing the operands +extracted from @var{insn}, and @var{noperands} is the number of +elements of the vector which contain meaningful data for this insn. +The contents of this vector are what will be used to convert the insn +template into assembler code, so you can change the assembler output +by changing the contents of the vector. + +This macro is useful when various assembler syntaxes share a single +file of instruction patterns; by defining this macro differently, you +can cause a large class of instructions to be output differently (such +as with rearranged operands). Naturally, variations in assembler +syntax affecting individual insn patterns ought to be handled by +writing conditional output routines in those patterns. + +If this macro is not defined, it is equivalent to a null statement. + +@findex PRINT_OPERAND +@item PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) +A C compound statement to output to stdio stream @var{stream} the +assembler syntax for an instruction operand @var{x}. @var{x} is an +RTL expression. + +@var{code} is a value that can be used to specify one of several ways +of printing the operand. It is used when identical operands must be +printed differently depending on the context. @var{code} comes from +the @samp{%} specification that was used to request printing of the +operand. If the specification was just @samp{%@var{digit}} then +@var{code} is 0; if the specification was @samp{%@var{ltr} +@var{digit}} then @var{code} is the ASCII code for @var{ltr}. + +@findex reg_names +If @var{x} is a register, this macro should print the register's name. +The names can be found in an array @code{reg_names} whose type is +@code{char *[]}. @code{reg_names} is initialized from +@code{REGISTER_NAMES}. + +When the machine description has a specification @samp{%@var{punct}} +(a @samp{%} followed by a punctuation character), this macro is called +with a null pointer for @var{x} and the punctuation character for +@var{code}. + +@findex PRINT_OPERAND_PUNCT_VALID_P +@item PRINT_OPERAND_PUNCT_VALID_P (@var{code}) +A C expression which evaluates to true if @var{code} is a valid +punctuation character for use in the @code{PRINT_OPERAND} macro. If +@code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no +punctuation characters (except for the standard one, @samp{%}) are used +in this way. + +@findex PRINT_OPERAND_ADDRESS +@item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x}) +A C compound statement to output to stdio stream @var{stream} the +assembler syntax for an instruction operand that is a memory reference +whose address is @var{x}. @var{x} is an RTL expression. + +@cindex @code{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 +@code{symbol_ref}, and then check for it here. @xref{Assembler Format}. + +@findex DBR_OUTPUT_SEQEND +@findex dbr_sequence_length +@item DBR_OUTPUT_SEQEND(@var{file}) +A C statement, to be executed after all slot-filler instructions have +been output. If necessary, call @code{dbr_sequence_length} to +determine the number of slots filled in a sequence (zero if not +currently outputting a sequence), to decide how many no-ops to output, +or whatever. + +Don't define this macro if it has nothing to do, but it is helpful in +reading assembly output if the extent of the delay sequence is made +explicit (e.g. with white space). + +@findex final_sequence +Note that output routines for instructions with delay slots must be +prepared to deal with not being output as part of a sequence (i.e. +when the scheduling pass is not run, or when no slot fillers could be +found.) The variable @code{final_sequence} is null when not +processing a sequence, otherwise it contains the @code{sequence} rtx +being output. + +@findex REGISTER_PREFIX +@findex LOCAL_LABEL_PREFIX +@findex USER_LABEL_PREFIX +@findex IMMEDIATE_PREFIX +@findex asm_fprintf +@item REGISTER_PREFIX +@itemx LOCAL_LABEL_PREFIX +@itemx USER_LABEL_PREFIX +@itemx IMMEDIATE_PREFIX +If defined, C string expressions to be used for the @samp{%R}, @samp{%L}, +@samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see +@file{final.c}). These are useful when a single @file{md} file must +support multiple assembler formats. In that case, the various @file{tm.h} +files can define these macros differently. + +@findex ASSEMBLER_DIALECT +@item ASSEMBLER_DIALECT +If your target supports multiple dialects of assembler language (such as +different opcodes), define this macro as a C expression that gives the +numeric index of the assembler langauge dialect to use, with zero as the +first variant. + +If this macro is defined, you may use +@samp{@{option0|option1|option2@dots{}@}} constructs in the output +templates of patterns (@pxref{Output Template}) or in the first argument +of @code{asm_fprintf}. This construct outputs @samp{option0}, +@samp{option1} or @samp{option2}, etc., if the value of +@code{ASSEMBLER_DIALECT} is zero, one or two, etc. Any special +characters within these strings retain their usual meaning. + +If you do not define this macro, the characters @samp{@{}, @samp{|} and +@samp{@}} do not have any special meaning when used in templates or +operands to @code{asm_fprintf}. + +Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX}, +@code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express +the variations in assemble language syntax with that mechanism. Define +@code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax +if the syntax variant are larger and involve such things as different +opcodes or operand order. + +@findex ASM_OUTPUT_REG_PUSH +@item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno}) +A C expression to output to @var{stream} some assembler code +which will push hard register number @var{regno} onto the stack. +The code need not be optimal, since this macro is used only when +profiling. + +@findex ASM_OUTPUT_REG_POP +@item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno}) +A C expression to output to @var{stream} some assembler code +which will pop hard register number @var{regno} off of the stack. +The code need not be optimal, since this macro is used only when +profiling. +@end table + +@node Dispatch Tables +@subsection Output of Dispatch Tables + +@c prevent bad page break with this line +This concerns dispatch tables. + +@table @code +@cindex dispatch table +@findex ASM_OUTPUT_ADDR_DIFF_ELT +@item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{value}, @var{rel}) +This macro should be provided on machines where the addresses +in a dispatch table are relative to the table's own address. + +The definition should be a C statement to output to the stdio stream +@var{stream} an assembler pseudo-instruction to generate a difference +between two labels. @var{value} and @var{rel} are the numbers of two +internal labels. The definitions of these labels are output using +@code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same +way here. For example, + +@example +fprintf (@var{stream}, "\t.word L%d-L%d\n", + @var{value}, @var{rel}) +@end example + +@findex ASM_OUTPUT_ADDR_VEC_ELT +@item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value}) +This macro should be provided on machines where the addresses +in a dispatch table are absolute. + +The definition should be a C statement to output to the stdio stream +@var{stream} an assembler pseudo-instruction to generate a reference to +a label. @var{value} is the number of an internal label whose +definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}. +For example, + +@example +fprintf (@var{stream}, "\t.word L%d\n", @var{value}) +@end example + +@findex ASM_OUTPUT_CASE_LABEL +@item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table}) +Define this if the label before a jump-table needs to be output +specially. The first three arguments are the same as for +@code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the +jump-table which follows (a @code{jump_insn} containing an +@code{addr_vec} or @code{addr_diff_vec}). + +This feature is used on system V to output a @code{swbeg} statement +for the table. + +If this macro is not defined, these labels are output with +@code{ASM_OUTPUT_INTERNAL_LABEL}. + +@findex ASM_OUTPUT_CASE_END +@item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) +Define this if something special must be output at the end of a +jump-table. The definition should be a C statement to be executed +after the assembler code for the table is written. It should write +the appropriate code to stdio stream @var{stream}. The argument +@var{table} is the jump-table insn, and @var{num} is the label-number +of the preceding label. + +If this macro is not defined, nothing special is output at the end of +the jump-table. +@end table + +@node Alignment Output +@subsection Assembler Commands for Alignment + +@c prevent bad page break with this line +This describes commands for alignment. + +@table @code +@findex ASM_OUTPUT_ALIGN_CODE +@item ASM_OUTPUT_ALIGN_CODE (@var{file}) +A C expression to output text to align the location counter in the way +that is desirable at a point in the code that is reached only by +jumping. + +This macro need not be defined if you don't want any special alignment +to be done at such a time. Most machine descriptions do not currently +define the macro. + +@findex ASM_OUTPUT_LOOP_ALIGN +@item ASM_OUTPUT_LOOP_ALIGN (@var{file}) +A C expression to output text to align the location counter in the way +that is desirable at the beginning of a loop. + +This macro need not be defined if you don't want any special alignment +to be done at such a time. Most machine descriptions do not currently +define the macro. + +@findex ASM_OUTPUT_SKIP +@item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) +A C statement to output to the stdio stream @var{stream} an assembler +instruction to advance the location counter by @var{nbytes} bytes. +Those bytes should be zero when loaded. @var{nbytes} will be a C +expression of type @code{int}. + +@findex ASM_NO_SKIP_IN_TEXT +@item ASM_NO_SKIP_IN_TEXT +Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the +text section because it fails put zeros in the bytes that are skipped. +This is true on many Unix systems, where the pseudo--op to skip bytes +produces no-op instructions rather than zeros when used in the text +section. + +@findex ASM_OUTPUT_ALIGN +@item ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) +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}. +@end table + +@need 3000 +@node Debugging Info +@section Controlling Debugging Information Format + +@c prevent bad page break with this line +This describes how to specify debugging information. + +@menu +* All Debuggers:: Macros that affect all debugging formats uniformly. +* DBX Options:: Macros enabling specific options in DBX format. +* DBX Hooks:: Hook macros for varying DBX format. +* File Names and DBX:: Macros controlling output of file names in DBX format. +* SDB and DWARF:: Macros for SDB (COFF) and DWARF formats. +@end menu + +@node All Debuggers +@subsection Macros Affecting All Debugging Formats + +@c prevent bad page break with this line +These macros affect all debugging formats. + +@table @code +@findex DBX_REGISTER_NUMBER +@item DBX_REGISTER_NUMBER (@var{regno}) +A C expression that returns the DBX register number for the compiler +register number @var{regno}. In simple cases, the value of this +expression may be @var{regno} itself. But sometimes there are some +registers that the compiler knows about and DBX does not, or vice +versa. In such cases, some register may need to have one number in +the compiler and another for DBX. + +If two registers have consecutive numbers inside GNU CC, and they can be +used as a pair to hold a multiword value, then they @emph{must} have +consecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}. +Otherwise, debuggers will be unable to access such a pair, because they +expect register pairs to be consecutive in their own numbering scheme. + +If you find yourself defining @code{DBX_REGISTER_NUMBER} in way that +does not preserve register pairs, then what you must do instead is +redefine the actual register numbering scheme. + +@findex DEBUGGER_AUTO_OFFSET +@item DEBUGGER_AUTO_OFFSET (@var{x}) +A C expression that returns the integer offset value for an automatic +variable having address @var{x} (an RTL expression). The default +computation assumes that @var{x} is based on the frame-pointer and +gives the offset from the frame-pointer. This is required for targets +that produce debugging output for DBX or COFF-style debugging output +for SDB and allow the frame-pointer to be eliminated when the +@samp{-g} options is used. + +@findex DEBUGGER_ARG_OFFSET +@item DEBUGGER_ARG_OFFSET (@var{offset}, @var{x}) +A C expression that returns the integer offset value for an argument +having address @var{x} (an RTL expression). The nominal offset is +@var{offset}. + +@findex PREFERRED_DEBUGGING_TYPE +@item PREFERRED_DEBUGGING_TYPE +A C expression that returns the type of debugging output GNU CC produces +when the user specifies @samp{-g} or @samp{-ggdb}. Define this if you +have arranged for GNU CC to support more than one format of debugging +output. Currently, the allowable values are @code{DBX_DEBUG}, +@code{SDB_DEBUG}, @code{DWARF_DEBUG}, and @code{XCOFF_DEBUG}. + +The value of this macro only affects the default debugging output; the +user can always get a specific type of output by using @samp{-gstabs}, +@samp{-gcoff}, @samp{-gdwarf}, or @samp{-gxcoff}. +@end table + +@node DBX Options +@subsection Specific Options for DBX Output + +@c prevent bad page break with this line +These are specific options for DBX output. + +@table @code +@findex DBX_DEBUGGING_INFO +@item DBX_DEBUGGING_INFO +Define this macro if GNU CC should produce debugging output for DBX +in response to the @samp{-g} option. + +@findex XCOFF_DEBUGGING_INFO +@item XCOFF_DEBUGGING_INFO +Define this macro if GNU CC should produce XCOFF format debugging output +in response to the @samp{-g} option. This is a variant of DBX format. + +@findex DEFAULT_GDB_EXTENSIONS +@item DEFAULT_GDB_EXTENSIONS +Define this macro to control whether GNU CC should by default generate +GDB's extended version of DBX debugging information (assuming DBX-format +debugging information is enabled at all). If you don't define the +macro, the default is 1: always generate the extended information +if there is any occasion to. + +@findex DEBUG_SYMS_TEXT +@item DEBUG_SYMS_TEXT +Define this macro if all @code{.stabs} commands should be output while +in the text section. + +@findex ASM_STABS_OP +@item ASM_STABS_OP +A C string constant naming the assembler pseudo op to use instead of +@code{.stabs} to define an ordinary debugging symbol. If you don't +define this macro, @code{.stabs} is used. This macro applies only to +DBX debugging information format. + +@findex ASM_STABD_OP +@item ASM_STABD_OP +A C string constant naming the assembler pseudo op to use instead of +@code{.stabd} to define a debugging symbol whose value is the current +location. If you don't define this macro, @code{.stabd} is used. +This macro applies only to DBX debugging information format. + +@findex ASM_STABN_OP +@item ASM_STABN_OP +A C string constant naming the assembler pseudo op to use instead of +@code{.stabn} to define a debugging symbol with no name. If you don't +define this macro, @code{.stabn} is used. This macro applies only to +DBX debugging information format. + +@findex DBX_NO_XREFS +@item DBX_NO_XREFS +Define this macro if DBX on your system does not support the construct +@samp{xs@var{tagname}}. On some systems, this construct is used to +describe a forward reference to a structure named @var{tagname}. +On other systems, this construct is not supported at all. + +@findex DBX_CONTIN_LENGTH +@item DBX_CONTIN_LENGTH +A symbol name in DBX-format debugging information is normally +continued (split into two separate @code{.stabs} directives) when it +exceeds a certain length (by default, 80 characters). On some +operating systems, DBX requires this splitting; on others, splitting +must not be done. You can inhibit splitting by defining this macro +with the value zero. You can override the default splitting-length by +defining this macro as an expression for the length you desire. + +@findex DBX_CONTIN_CHAR +@item DBX_CONTIN_CHAR +Normally continuation is indicated by adding a @samp{\} character to +the end of a @code{.stabs} string when a continuation follows. To use +a different character instead, define this macro as a character +constant for the character you want to use. Do not define this macro +if backslash is correct for your system. + +@findex DBX_STATIC_STAB_DATA_SECTION +@item DBX_STATIC_STAB_DATA_SECTION +Define this macro if it is necessary to go to the data section before +outputting the @samp{.stabs} pseudo-op for a non-global static +variable. + +@findex DBX_TYPE_DECL_STABS_CODE +@item DBX_TYPE_DECL_STABS_CODE +The value to use in the ``code'' field of the @code{.stabs} directive +for a typedef. The default is @code{N_LSYM}. + +@findex DBX_STATIC_CONST_VAR_CODE +@item DBX_STATIC_CONST_VAR_CODE +The value to use in the ``code'' field of the @code{.stabs} directive +for a static variable located in the text section. DBX format does not +provide any ``right'' way to do this. The default is @code{N_FUN}. + +@findex DBX_REGPARM_STABS_CODE +@item DBX_REGPARM_STABS_CODE +The value to use in the ``code'' field of the @code{.stabs} directive +for a parameter passed in registers. DBX format does not provide any +``right'' way to do this. The default is @code{N_RSYM}. + +@findex DBX_REGPARM_STABS_LETTER +@item DBX_REGPARM_STABS_LETTER +The letter to use in DBX symbol data to identify a symbol as a parameter +passed in registers. DBX format does not customarily provide any way to +do this. The default is @code{'P'}. + +@findex DBX_MEMPARM_STABS_LETTER +@item DBX_MEMPARM_STABS_LETTER +The letter to use in DBX symbol data to identify a symbol as a stack +parameter. The default is @code{'p'}. + +@findex DBX_FUNCTION_FIRST +@item DBX_FUNCTION_FIRST +Define this macro if the DBX information for a function and its +arguments should precede the assembler code for the function. Normally, +in DBX format, the debugging information entirely follows the assembler +code. + +@findex DBX_LBRAC_FIRST +@item DBX_LBRAC_FIRST +Define this macro if the @code{N_LBRAC} symbol for a block should +precede the debugging information for variables and functions defined in +that block. Normally, in DBX format, the @code{N_LBRAC} symbol comes +first. + +@findex DBX_BLOCKS_FUNCTION_RELATIVE +@item DBX_BLOCKS_FUNCTION_RELATIVE +Define this macro if the value of a symbol describing the scope of a +block (@code{N_LBRAC} or @code{N_RBRAC}) should be relative to the start +of the enclosing function. Normally, GNU C uses an absolute address. +@end table + +@node DBX Hooks +@subsection Open-Ended Hooks for DBX Format + +@c prevent bad page break with this line +These are hooks for DBX format. + +@table @code +@findex DBX_OUTPUT_LBRAC +@item DBX_OUTPUT_LBRAC (@var{stream}, @var{name}) +Define this macro to say how to output to @var{stream} the debugging +information for the start of a scope level for variable names. The +argument @var{name} is the name of an assembler symbol (for use with +@code{assemble_name}) whose value is the address where the scope begins. + +@findex DBX_OUTPUT_RBRAC +@item DBX_OUTPUT_RBRAC (@var{stream}, @var{name}) +Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level. + +@findex DBX_OUTPUT_ENUM +@item DBX_OUTPUT_ENUM (@var{stream}, @var{type}) +Define this macro if the target machine requires special handling to +output an enumeration type. The definition should be a C statement +(sans semicolon) to output the appropriate information to @var{stream} +for the type @var{type}. + +@findex DBX_OUTPUT_FUNCTION_END +@item DBX_OUTPUT_FUNCTION_END (@var{stream}, @var{function}) +Define this macro if the target machine requires special output at the +end of the debugging information for a function. The definition should +be a C statement (sans semicolon) to output the appropriate information +to @var{stream}. @var{function} is the @code{FUNCTION_DECL} node for +the function. + +@findex DBX_OUTPUT_STANDARD_TYPES +@item DBX_OUTPUT_STANDARD_TYPES (@var{syms}) +Define this macro if you need to control the order of output of the +standard data types at the beginning of compilation. The argument +@var{syms} is a @code{tree} which is a chain of all the predefined +global symbols, including names of data types. + +Normally, DBX output starts with definitions of the types for integers +and characters, followed by all the other predefined types of the +particular language in no particular order. + +On some machines, it is necessary to output different particular types +first. To do this, define @code{DBX_OUTPUT_STANDARD_TYPES} to output +those symbols in the necessary order. Any predefined types that you +don't explicitly output will be output afterward in no particular order. + +Be careful not to define this macro so that it works only for C. There +are no global variables to access most of the built-in types, because +another language may have another set of types. The way to output a +particular type is to look through @var{syms} to see if you can find it. +Here is an example: + +@smallexample +@{ + tree decl; + for (decl = syms; decl; decl = TREE_CHAIN (decl)) + if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)), + "long int")) + dbxout_symbol (decl); + @dots{} +@} +@end smallexample + +@noindent +This does nothing if the expected type does not exist. + +See the function @code{init_decl_processing} in @file{c-decl.c} to find +the names to use for all the built-in C types. + +Here is another way of finding a particular type: + +@c this is still overfull. --mew 10feb93 +@smallexample +@{ + tree decl; + for (decl = syms; decl; decl = TREE_CHAIN (decl)) + if (TREE_CODE (decl) == TYPE_DECL + && (TREE_CODE (TREE_TYPE (decl)) + == INTEGER_CST) + && TYPE_PRECISION (TREE_TYPE (decl)) == 16 + && TYPE_UNSIGNED (TREE_TYPE (decl))) +@group + /* @r{This must be @code{unsigned short}.} */ + dbxout_symbol (decl); + @dots{} +@} +@end group +@end smallexample +@end table + +@node File Names and DBX +@subsection File Names in DBX Format + +@c prevent bad page break with this line +This describes file names in DBX format. + +@table @code +@findex DBX_WORKING_DIRECTORY +@item DBX_WORKING_DIRECTORY +Define this if DBX wants to have the current directory recorded in each +object file. + +Note that the working directory is always recorded if GDB extensions are +enabled. + +@findex DBX_OUTPUT_MAIN_SOURCE_FILENAME +@item DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name}) +A C statement to output DBX debugging information to the stdio stream +@var{stream} which indicates that file @var{name} is the main source +file---the file specified as the input file for compilation. +This macro is called only once, at the beginning of compilation. + +This macro need not be defined if the standard form of output +for DBX debugging information is appropriate. + +@findex DBX_OUTPUT_MAIN_SOURCE_DIRECTORY +@item DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (@var{stream}, @var{name}) +A C statement to output DBX debugging information to the stdio stream +@var{stream} which indicates that the current directory during +compilation is named @var{name}. + +This macro need not be defined if the standard form of output +for DBX debugging information is appropriate. + +@findex DBX_OUTPUT_MAIN_SOURCE_FILE_END +@item DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name}) +A C statement to output DBX debugging information at the end of +compilation of the main source file @var{name}. + +If you don't define this macro, nothing special is output at the end +of compilation, which is correct for most machines. + +@findex DBX_OUTPUT_SOURCE_FILENAME +@item DBX_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name}) +A C statement to output DBX debugging information to the stdio stream +@var{stream} which indicates that file @var{name} is the current source +file. This output is generated each time input shifts to a different +source file as a result of @samp{#include}, the end of an included file, +or a @samp{#line} command. + +This macro need not be defined if the standard form of output +for DBX debugging information is appropriate. +@end table + +@need 2000 +@node SDB and DWARF +@subsection Macros for SDB and DWARF Output + +@c prevent bad page break with this line +Here are macros for SDB and DWARF output. + +@table @code +@findex SDB_DEBUGGING_INFO +@item SDB_DEBUGGING_INFO +Define this macro if GNU CC should produce COFF-style debugging output +for SDB in response to the @samp{-g} option. + +@findex DWARF_DEBUGGING_INFO +@item DWARF_DEBUGGING_INFO +Define this macro if GNU CC should produce dwarf format debugging output +in response to the @samp{-g} option. + +@findex PUT_SDB_@dots{} +@item PUT_SDB_@dots{} +Define these macros to override the assembler syntax for the special +SDB assembler directives. See @file{sdbout.c} for a list of these +macros and their arguments. If the standard syntax is used, you need +not define them yourself. + +@findex SDB_DELIM +@item SDB_DELIM +Some assemblers do not support a semicolon as a delimiter, even between +SDB assembler directives. In that case, define this macro to be the +delimiter to use (usually @samp{\n}). It is not necessary to define +a new set of @code{PUT_SDB_@var{op}} macros if this is the only change +required. + +@findex SDB_GENERATE_FAKE +@item SDB_GENERATE_FAKE +Define this macro to override the usual method of constructing a dummy +name for anonymous structure and union types. See @file{sdbout.c} for +more information. + +@findex SDB_ALLOW_UNKNOWN_REFERENCES +@item SDB_ALLOW_UNKNOWN_REFERENCES +Define this macro to allow references to unknown structure, +union, or enumeration tags to be emitted. Standard COFF does not +allow handling of unknown references, MIPS ECOFF has support for +it. + +@findex SDB_ALLOW_FORWARD_REFERENCES +@item SDB_ALLOW_FORWARD_REFERENCES +Define this macro to allow references to structure, union, or +enumeration tags that have not yet been seen to be handled. Some +assemblers choke if forward tags are used, while some require it. +@end table + +@node Cross-compilation +@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, +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). + +The macros in the following table should be defined only if you are cross +compiling between different floating point formats. + +Otherwise, don't define them. Then default definitions will be set up which +use @code{double} as the data type, @code{==} to test for equality, etc. + +You don't need to worry about how many times you use an operand of any +of these macros. The compiler never uses operands which have side effects. + +@table @code +@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 + +@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. + +@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}.@refill + +@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}. + +There is no way for this macro to report overflow. + +@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}. + +@item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high}) +@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}. +@end table + +@node Misc +@section Miscellaneous Parameters +@cindex parameters, miscellaneous + +@c prevent bad page break with this line +Here are several miscellaneous parameters. + +@table @code +@item PREDICATE_CODES +@findex PREDICATE_CODES +Define this if you have defined special-purpose predicates in the file +@file{@var{machine}.c}. This macro is called within an initializer of an +array of structures. The first field in the structure is the name of a +predicate and the second field is an array of rtl codes. For each +predicate, list all rtl codes that can be in expressions matched by the +predicate. The list should have a trailing comma. Here is an example +of two entries in the list for a typical RISC machine: + +@smallexample +#define PREDICATE_CODES \ + @{"gen_reg_rtx_operand", @{SUBREG, REG@}@}, \ + @{"reg_or_short_cint_operand", @{SUBREG, REG, CONST_INT@}@}, +@end smallexample + +Defining this macro does not affect the generated code (however, +incorrect definitions that omit an rtl code that may be matched by the +predicate can cause the compiler to malfunction). Instead, it allows +the table built by @file{genrecog} to be more compact and efficient, +thus speeding up the compiler. The most important predicates to include +in the list specified by this macro are thoses used in the most insn +patterns. + +@findex CASE_VECTOR_MODE +@item CASE_VECTOR_MODE +An alias for a machine mode name. This is the machine mode that +elements of a jump-table should have. + +@findex CASE_VECTOR_PC_RELATIVE +@item CASE_VECTOR_PC_RELATIVE +Define this macro if jump-tables should contain relative addresses. + +@findex CASE_DROPS_THROUGH +@item CASE_DROPS_THROUGH +Define this if control falls through a @code{case} insn when the index +value is out of range. This means the specified default-label is +actually ignored by the @code{case} insn proper. + +@findex CASE_VALUES_THRESHOLD +@item CASE_VALUES_THRESHOLD +Define this to be the smallest number of different values for which it +is best to use a jump-table instead of a tree of conditional branches. +The default is four for machines with a @code{casesi} instruction and +five otherwise. This is best for most machines. + +@findex WORD_REGISTER_OPERATIONS +@item WORD_REGISTER_OPERATIONS +Define this macro if operations between registers with integral mode +smaller than a word are always performed on the entire register. +Most RISC machines have this property and most CISC machines do not. + +@findex LOAD_EXTEND_OP +@item LOAD_EXTEND_OP (@var{mode}) +Define this macro to be a C expression indicating when insns that read +memory in @var{mode}, an integral mode narrower than a word, set the +bits outside of @var{mode} to be either the sign-extension or the +zero-extension of the data read. Return @code{SIGN_EXTEND} for values +of @var{mode} for which the +insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and +@code{NIL} for other modes. + +This macro is not called with @var{mode} non-integral or with a width +greater than or equal to @code{BITS_PER_WORD}, so you may return any +value in this case. Do not define this macro if it would always return +@code{NIL}. On machines where this macro is defined, you will normally +define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}. + +@findex IMPLICIT_FIX_EXPR +@item IMPLICIT_FIX_EXPR +An alias for a tree code that should be used by default for conversion +of floating point values to fixed point. Normally, +@code{FIX_ROUND_EXPR} is used.@refill + +@findex FIXUNS_TRUNC_LIKE_FIX_TRUNC +@item FIXUNS_TRUNC_LIKE_FIX_TRUNC +Define this macro if the same instructions that convert a floating +point number to a signed fixed point number also convert validly to an +unsigned one. + +@findex EASY_DIV_EXPR +@item EASY_DIV_EXPR +An alias for a tree code that is the easiest kind of division to +compile code for in the general case. It may be +@code{TRUNC_DIV_EXPR}, @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or +@code{ROUND_DIV_EXPR}. These four division operators differ in how +they round the result to an integer. @code{EASY_DIV_EXPR} is used +when it is permissible to use any of those kinds of division and the +choice should be made on the basis of efficiency.@refill + +@findex MOVE_MAX +@item MOVE_MAX +The maximum number of bytes that a single instruction can move quickly +from memory to memory. + +@findex MAX_MOVE_MAX +@item MAX_MOVE_MAX +The maximum number of bytes that a single instruction can move quickly +from memory to memory. If this is undefined, the default is +@code{MOVE_MAX}. Otherwise, it is the constant value that is the +largest value that @code{MOVE_MAX} can have at run-time. + +@findex SHIFT_COUNT_TRUNCATED +@item SHIFT_COUNT_TRUNCATED +A C expression that is nonzero if on this machine the number of bits +actually used for the count of a shift operation is equal to the number +of bits needed to represent the size of the object being shifted. When +this macro is non-zero, the compiler will assume that it is safe to omit +a sign-extend, zero-extend, and certain bitwise `and' instructions that +truncates the count of a shift operation. On machines that have +instructions that act on bitfields at variable positions, which may +include `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED} +also enables deletion of truncations of the values that serve as +arguments to bitfield instructions. + +If both types of instructions truncate the count (for shifts) and +position (for bitfield operations), or if no variable-position bitfield +instructions exist, you should define this macro. + +However, on some machines, such as the 80386 and the 680x0, truncation +only applies to shift operations and not the (real or pretended) +bitfield operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on +such machines. Instead, add patterns to the @file{md} file that include +the implied truncation of the shift instructions. + +You need not define this macro if it would always have the value of zero. + +@findex TRULY_NOOP_TRUNCATION +@item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec}) +A C expression which is nonzero if on this machine it is safe to +``convert'' an integer of @var{inprec} bits to one of @var{outprec} +bits (where @var{outprec} is smaller than @var{inprec}) by merely +operating on it as if it had only @var{outprec} bits. + +On many machines, this expression can be 1. + +@c rearranged this, removed the phrase "it is reported that". this was +@c to fix an overfull hbox. --mew 10feb93 +When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for +modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result. +If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in +such cases may improve things. + +@findex STORE_FLAG_VALUE +@item STORE_FLAG_VALUE +A C expression describing the value returned by a comparison operator +with an integral mode and stored by a store-flag instruction +(@samp{s@var{cond}}) when the condition is true. This description must +apply to @emph{all} the @samp{s@var{cond}} patterns and all the +comparison operators whose results have a @code{MODE_INT} mode. + +A value of 1 or -1 means that the instruction implementing the +comparison operator returns exactly 1 or -1 when the comparison is true +and 0 when the comparison is false. Otherwise, the value indicates +which bits of the result are guaranteed to be 1 when the comparison is +true. This value is interpreted in the mode of the comparison +operation, which is given by the mode of the first operand in the +@samp{s@var{cond}} pattern. Either the low bit or the sign bit of +@code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by +the compiler. + +If @code{STORE_FLAG_VALUE} is neither 1 or -1, the compiler will +generate code that depends only on the specified bits. It can also +replace comparison operators with equivalent operations if they cause +the required bits to be set, even if the remaining bits are undefined. +For example, on a machine whose comparison operators return an +@code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as +@samp{0x80000000}, saying that just the sign bit is relevant, the +expression + +@smallexample +(ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0)) +@end smallexample + +@noindent +can be converted to + +@smallexample +(ashift:SI @var{x} (const_int @var{n})) +@end smallexample + +@noindent +where @var{n} is the appropriate shift count to move the bit being +tested into the sign bit. + +There is no way to describe a machine that always sets the low-order bit +for a true value, but does not guarantee the value of any other bits, +but we do not know of any machine that has such an instruction. If you +are trying to port GNU CC to such a machine, include an instruction to +perform a logical-and of the result with 1 in the pattern for the +comparison operators and let us know +@ifset USING +(@pxref{Bug Reporting,,How to Report Bugs}). +@end ifset +@ifclear USING +(@pxref{Bug Reporting,,How to Report Bugs,gcc.info,Using GCC}). +@end ifclear + +Often, a machine will have multiple instructions that obtain a value +from a comparison (or the condition codes). Here are rules to guide the +choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions +to be used: + +@itemize @bullet +@item +Use the shortest sequence that yields a valid definition for +@code{STORE_FLAG_VALUE}. It is more efficient for the compiler to +``normalize'' the value (convert it to, e.g., 1 or 0) than for the +comparison operators to do so because there may be opportunities to +combine the normalization with other operations. + +@item +For equal-length sequences, use a value of 1 or -1, with -1 being +slightly preferred on machines with expensive jumps and 1 preferred on +other machines. + +@item +As a second choice, choose a value of @samp{0x80000001} if instructions +exist that set both the sign and low-order bits but do not define the +others. + +@item +Otherwise, use a value of @samp{0x80000000}. +@end itemize + +Many machines can produce both the value chosen for +@code{STORE_FLAG_VALUE} and its negation in the same number of +instructions. On those machines, you should also define a pattern for +those cases, e.g., one matching + +@smallexample +(set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C}))) +@end smallexample + +Some machines can also perform @code{and} or @code{plus} operations on +condition code values with less instructions than the corresponding +@samp{s@var{cond}} insn followed by @code{and} or @code{plus}. On those +machines, define the appropriate patterns. Use the names @code{incscc} +and @code{decscc}, respectively, for the the patterns which perform +@code{plus} or @code{minus} operations on condition code values. See +@file{rs6000.md} for some examples. The GNU Superoptizer can be used to +find such instruction sequences on other machines. + +You need not define @code{STORE_FLAG_VALUE} if the machine has no store-flag +instructions. + +@findex FLOAT_STORE_FLAG_VALUE +@item FLOAT_STORE_FLAG_VALUE +A C expression that gives a non-zero floating point value that is +returned when comparison operators with floating-point results are true. +Define this macro on machine that have comparison operations that return +floating-point values. If there are no such operations, do not define +this macro. + +@findex Pmode +@item Pmode +An alias for the machine mode for pointers. Normally the definition +can be + +@smallexample +#define Pmode SImode +@end smallexample + +@findex FUNCTION_MODE +@item FUNCTION_MODE +An alias for the machine mode used for memory references to functions +being called, in @code{call} RTL expressions. On most machines this +should be @code{QImode}. + +@findex INTEGRATE_THRESHOLD +@item INTEGRATE_THRESHOLD (@var{decl}) +A C expression for the maximum number of instructions above which the +function @var{decl} should not be inlined. @var{decl} is a +@code{FUNCTION_DECL} node. + +The default definition of this macro is 64 plus 8 times the number of +arguments that the function accepts. Some people think a larger +threshold should be used on RISC machines. + +@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. +This macro inhibits the usual method of using system header files in +C++, which is to pretend that the file's contents are enclosed in +@samp{extern "C" @{@dots{}@}}. + +@findex HANDLE_PRAGMA +@findex #pragma +@findex pragma +@item HANDLE_PRAGMA (@var{stream}) +Define this macro if you want to implement any pragmas. If defined, it +should be a C statement to be executed when @code{#pragma} is seen. The +argument @var{stream} is the stdio input stream from which the source +text can be read. + +It is generally a bad idea to implement new uses of @code{#pragma}. The +only reason to define this macro is for compatibility with other +compilers that do support @code{#pragma} for the sake of any user +programs which already use it. + +@findex VALID_MACHINE_ATTRIBUTE +@item VALID_MACHINE_ATTRIBUTE (@var{type}, @var{attributes}, @var{identifier}) +Define this macro if you want to support machine specific attributes for +types. If defined, it should be a C statement whose value is nonzero if +@var{identifier} is an attribute that is valid for @var{type}. The +attributes in @var{attributes} have previously been assigned to @var{type}. + +@findex COMP_TYPE_ATTRIBUTES +@item COMP_TYPE_ATTRIBUTES (@var{type1}, @var{type2}) +Define this macro if type attributes must be checked for compatibility. +If defined, it should be a C statement that returns zero if the +attributes on @var{type1} and @var{type2} are incompatible, one if they +are compatible, and two if they are nearly compatible (which causes a +warning to be generated). + +@findex SET_DEFAULT_TYPE_ATTRIBUTES +@item SET_DEFAULT_TYPE_ATTRIBUTES (@var{type}) +Define this macro if you want to give the newly defined @var{type} some +default attributes. + +@findex DOLLARS_IN_IDENTIFIERS +@item DOLLARS_IN_IDENTIFIERS +Define this macro to control use of the character @samp{$} in identifier +names. The value should be 0, 1, or 2. 0 means @samp{$} is not allowed +by default; 1 means it is allowed by default if @samp{-traditional} is +used; 2 means it is allowed by default provided @samp{-ansi} is not used. +1 is the default; there is no need to define this macro in that case. + +@findex NO_DOLLAR_IN_LABEL +@item NO_DOLLAR_IN_LABEL +Define this macro if the assembler does not accept the character +@samp{$} in label names. By default constructors and destructors in +G++ have @samp{$} in the identifiers. If this macro is defined, +@samp{.} is used instead. + +@findex NO_DOT_IN_LABEL +@item NO_DOT_IN_LABEL +Define this macro if the assembler does not accept the character +@samp{.} in label names. By default constructors and destructors in G++ +have names that use @samp{.}. If this macro is defined, these names +are rewritten to avoid @samp{.}. + +@findex DEFAULT_MAIN_RETURN +@item DEFAULT_MAIN_RETURN +Define this macro if the target system expects every program's @code{main} +function to return a standard ``success'' value by default (if no other +value is explicitly returned). + +The definition should be a C statement (sans semicolon) to generate the +appropriate rtl instructions. It is used only when compiling the end of +@code{main}. + +@item HAVE_ATEXIT +@findex HAVE_ATEXIT +Define this if the target system supports the function +@code{atexit} from the ANSI C standard. If this is not defined, +and @code{INIT_SECTION_ASM_OP} is not defined, a default +@code{exit} function will be provided to support C++. + +@item EXIT_BODY +@findex EXIT_BODY +Define this if your @code{exit} function needs to do something +besides calling an external function @code{_cleanup} before +terminating with @code{_exit}. The @code{EXIT_BODY} macro is +only needed if netiher @code{HAVE_ATEXIT} nor +@code{INIT_SECTION_ASM_OP} are defined. + +@findex INSN_SETS_ARE_DELAYED +@item INSN_SETS_ARE_DELAYED (@var{insn}) +Define this macro as a C expression that is nonzero if it is safe for the +delay slot scheduler to place instructions in the delay slot of @var{insn}, +even if they appear to use a resource set or clobbered in @var{insn}. +@var{insn} is always a @code{jump_insn} or an @code{insn}; GNU CC knows that +every @code{call_insn} has this behavior. On machines where some @code{insn} +or @code{jump_insn} is really a function call and hence has this behavior, +you should define this macro. + +You need not define this macro if it would always return zero. + +@findex INSN_REFERENCES_ARE_DELAYED +@item INSN_REFERENCES_ARE_DELAYED (@var{insn}) +Define this macro as a C expression that is nonzero if it is safe for the +delay slot scheduler to place instructions in the delay slot of @var{insn}, +even if they appear to set or clobber a resource referenced in @var{insn}. +@var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where +some @code{insn} or @code{jump_insn} is really a function call and its operands +are registers whose use is actually in the subroutine it calls, you should +define this macro. Doing so allows the delay slot scheduler to move +instructions which copy arguments into the argument registers into the delay +slot of @var{insn}. + +You need not define this macro if it would always return zero. + +@findex MACHINE_DEPENDENT_REORG +@item MACHINE_DEPENDENT_REORG (@var{insn}) +In rare cases, correct code generation requires extra machine +dependent processing between the second jump optimization pass and +delayed branch scheduling. On those machines, define this macro as a C +statement to act on the code starting at @var{insn}. +@end table |