--- gcc/internals.texinfo 2018/04/24 16:38:04 1.1.1.2 +++ gcc/internals.texinfo 2018/04/24 16:43:51 1.1.1.8 @@ -39,9 +39,9 @@ Free Software Foundation instead of in t @sp 2 @center Richard M. Stallman @sp 3 -@center last updated 24 April 1988 +@center last updated 6 September 1988 @sp 1 -@center for version 1.21 +@center for version 1.27 @page @vskip 0pt plus 1filll Copyright @copyright{} 1988 Free Software Foundation, Inc. @@ -78,6 +78,7 @@ well as its new features and incompatibi * Contributors:: People who have contributed to GNU CC. * Options:: Command options supported by @samp{gcc}. * Installation:: How to configure, compile and install GNU CC. +* Trouble:: If you have trouble installing GNU CC. * Incompatibilities:: Incompatibilities of GNU CC. * Extensions:: GNU extensions to the C language. * Bugs:: How to report bugs (if you want to get them fixed). @@ -274,20 +275,33 @@ Charles LaBrec contributed the support f 68020 system. @item -Michael Tiemann of MCC wrote the description of the National -Semiconductor 32000 series cpu, with some contributions from Jan Stein -of the Chalmers Computer Club. Tiemann also wrote the code for inline -function integration. +Michael Tiemann of MCC wrote most of the description of the National +Semiconductor 32000 series cpu. He also wrote the code for inline +function integration and for the SPARC cpu and Motorola 88000 cpu +and part of the Sun FPA support. @item -Michael Kashtan of SRI adapted GNU CC to the Vomit-Making System. +Jan Stein of the Chalmers Computer Society provided support for +Genix, as well as part of the 32000 machine description. + +@item +Randy Smith finished the Sun FPA support. + +@item +Robert Brown implemented the support for Encore 32000 systems. + +@item +David Kashtan of SRI adapted GNU CC to the Vomit-Making System. @item Alex Crain provided changes for the 3b1. @item -Chris Hanson and another person who should remind me of his name -assisted in making GNU CC work on HP-UX for the 9000 series 300. +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. @end itemize @node Options, Installation, Contributors, Top @@ -323,7 +337,7 @@ Place output in file @var{file}. This a sort of output is being produced, whether it be an executable file, an object file, an assembler file or preprocessed C code. -If @samp{-o} is not specified, the default is to put an excutable file +If @samp{-o} is not specified, the default is to put an executable file in @file{a.out}, the object file @file{@var{source}.c} in @file{@var{source}.o}, an assembler file in @file{@var{source}.s}, and preprocessed C on standard output.@refill @@ -413,14 +427,18 @@ Integer types @code{unsigned short} and to @code{unsigned int}. @item -In the preprocessor, comments convert to nothing at all, rather than to -a space. This allows traditional token concatenation. +Out-of-range floating point literals are not an error. + +@item +In the preprocessor, comments convert to nothing at all, rather than +to a space. This allows traditional token concatenation. @item -In the preprocessor, single and double quote characters are ignored -when scanning macro definitions, so that macro arguments can be replaced -even within a string or character constant. Quote characters are also -ignored when skipping text inside a failing conditional directive. +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. @end itemize @item -O @@ -445,7 +463,8 @@ Some of the @samp{-f} options described optimization on or off. @item -g -Produce debugging information in DBX format. +Produce debugging information in the operating system's native +format (for DBX or SDB). Unlike most other C compilers, GNU CC allows you to use @samp{-g} with @samp{-O}. The shortcuts taken by optimized code may occasionally @@ -520,7 +539,7 @@ another common case: @end example @noindent -This has no bug because @code{x} is used only if it is set. +This has no bug because @code{save_y} is used only if it is set. @item A nonvolatile automatic variable might be changed by a call to @@ -566,6 +585,18 @@ return-value in a function whose return- @item -Wcomment Warn whenever a comment-start sequence @samp{/*} appears in a comment. +@item -Wall +All of the above @samp{-W} options combined. + +@item -Wwrite-strings +Give string constants the type @code{const char[@var{length}]} so that +copying the address of one into a non-@code{const} @code{char *} +pointer will get a warning. These warnings will help you find at +compile time code that can try to write into a string constant, but +only if you have been very careful about using @code{const} in +declarations and prototypes. Otherwise, it will just be a nuisance; +this is why we did not make @samp{-Wall} request these warnings. + @item -p Generate extra code to write profile information suitable for the analysis program @code{prof}. @@ -574,10 +605,26 @@ analysis program @code{prof}. Generate extra code to write profile information suitable for the analysis program @code{gprof}. -@item -nostdinc -Don't search the standard directories for include files. Only the -directories you specify explicitly with the @samp{-I} option will be -searched. +@item -l@var{library} +Search a standard list of directories for a library named +@var{library}, which is actually a file named +@file{lib@var{library}.a}. The linker uses this file as if it +had been specified precisely by name. + +The directories searched include several standard system directories +plus any that you specify with @samp{-L}. + +Normally the files found this way are library files---archive files +whose members are object files. The linker handles an archive file by +scanning through it for members which define symbols that have so far +been referenced but not defined. But if the file that is found is an +ordinary object file, it is linked in the usual fashion. The only +difference between using an @samp{-l} option and specifying a file name +is that @samp{-l} searches several directories. + +@item -L@var{dir} +Add directory @var{dir} to the list of directories to be searched +for @samp{-l}. @item -nostdlib Don't use the standard system libraries and startup files when @@ -596,16 +643,21 @@ description: @table @samp @item -m68020 +@itemx -mc68020 Generate output for a 68020 (rather than a 68000). This is the default if you use the unmodified sources. @item -m68000 +@item -mc68000 Generate output for a 68000 (rather than a 68020). @item -m68881 Generate output containing 68881 instructions for floating point. This is the default if you use the unmodified sources. +@item -mfpa +Generate output containing Sun FPA instructions for floating point. + @item -msoft-float Generate output containing library calls for floating point. @@ -656,6 +708,9 @@ 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 @item -f@var{flag} @@ -851,6 +906,32 @@ Tell the preprocessor not to discard com @item -I@var{dir} Search directory @var{dir} for include files. +@item -I- +Any directories specified with @samp{-I} options before the @samp{-I-} +option are searched only for the case of @samp{#include "@var{file}"}; +they are not searched for @samp{#include <@var{file}>}. + +If additional directories are specified with @samp{-I} options after +the @samp{-I-}, these directories are searched for all @samp{#include} +directives. (Ordinarily @emph{all} @samp{-I} directories are used +this way.) + +In addition, the @samp{-I-} option inhibits the use of the current +directory 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 +Do not search the standard system directories for header files. Only +the directories you have specified with @samp{-I} options (and the +current directory, if appropriate) are searched. + +Between @samp{-nostdinc} and @samp{-I-}, you can eliminate all +directories from the search path except those you specify. + @item -M Tell the preprocessor to output a rule suitable for @code{make} describing the dependencies of each source file. For each source @@ -882,7 +963,7 @@ Support ANSI C trigraphs. You don't wan brain-damage. The @samp{-ansi} option also has this effect. @end table -@node Installation, Incompatibilities, Options, Top +@node Installation, Trouble, Options, Top @chapter Installing GNU CC Here is the procedure for installing GNU CC on a Unix system. @@ -895,8 +976,12 @@ Here is the procedure for installing GNU @enumerate @item -Edit @file{Makefile}. If you are using HPUX, you must make a few -changes described in comments at the beginning of the file. +Edit @file{Makefile}. If you are using HPUX, or any form of system V, +you must make a few changes described in comments at the beginning of +the file. + +@item +On a Sequent system, go to the Berkeley universe. @item Choose configuration files. @@ -908,10 +993,23 @@ config file for the machine you are usin file is responsible for defining information about the host machine. It includes @file{tm.h}. -The file's name should be @file{config-@var{machine}.h}. On VMS, -use @file{config-vms.h} rather than @file{config-vax.h}. On the -HP 9000 series 300, use @file{config-hp9k3.h} rather than -@file{config-m68k.h}.@refill +The file's name should be @file{config-@var{machine}.h}, with these +exceptions: + +@table @file +@item config-vms.h +for vaxen running VMS. +@item config-vaxv.h +for vaxen running system V. +@item config-i386v.h +for Intel 80386's running system V. +@item config-sun4.h +for Suns (model 3 or 4) running @emph{operating system} version 4. +@item config-hp9k3.h +for the HP 9000 series 300. +@item config-gnx.h +for the ns32000 running Genix +@end table If your system does not support symbolic links, you might want to set up @file{config.h} to contain a @samp{#include} command which @@ -922,27 +1020,55 @@ Make a symbolic link named @file{tm.h} t macro file for your machine (its name should be @file{tm-@var{machine}.h}). -For the 68000/68020, do not use @file{tm-m68k.h} directly; -instead use one of the files @file{tm-sun3.h}, @file{tm-sun2.h}, -@file{tm-isi68.h}, @file{tm-news800.h} or @file{tm-3b1.h}. Each -of those files includes @file{tm-m68k.h} but sets up a few things -differently as appropriate to the specific model of -machine.@refill - -There are two files you can use for a 680x0 running HPUX: -@file{tm-hp9k320.h} and @file{tm-hp9k320g.h}. Use the former if -you are installing GNU CC alone. The latter is for another option -where GNU CC together with the GNU assembler, linker, debugger -and other utilities are used to replace all of HPUX that deals -with compilation. Not all of the pieces of GNU software needed for -this mode of operation are as yet in distribution; full instructions -will appear here in the future.@refill +If your system is a 68000, don't use the file @file{tm-m68k.h} +directly. Instead, use one of these files: + +@table @file +@item tm-sun3.h +for Sun 3 machines. +@item tm-sun2.h +for Sun 2 machines. +@item tm-3b1.h +for AT&T 3b1 (aka 7300 Unix PC). +@item tm-isi68.h +for Integrated Solutions systems. +@item tm-news800.h +for SONY News systems. +@item tm-hp9k320.h +for HPUX systems, if you are using GNU CC with the system's +assembler and linker. +@item tm-hp9k320g.h +for HPUX systems, if you are using the GNU assembler, linker and +other utilities. Not all of the pieces of GNU software needed +for this mode of operation are as yet in distribution; full +instructions will appear here in the future.@refill +@end table + +For the vax, use @file{tm-vax.h} on BSD Unix, @file{tm-vaxv.h} on +system V, or @file{tm-vms.h} on VMS.@refill + +For the SPARC (Sun 4), use @file{tm-sparc.h}. + +For the Motorola 88000, use @file{tm-m88k.h}. The support for the +88000 has a few unfinished spots because there was no way to run the +output. Bugs are suspected in handling of branch-tables and in +the function prologue and epilogue. + +For the 80386, don't use @file{tm-i386.h} directly. Use +@file{tm-i386v.h} if the target machine is running system V, +@file{tm-seq386.h} for a Sequent 386 system, or @file{tm-compaq.h} for +a Compaq. For the 32000, use @file{tm-sequent.h} if you are using a Sequent -machine; otherwise, use @file{tm-ns32k.h}. +machine, or @file{tm-encore.h} for an Encore machine, or +@file{tm-gnx.h} if you are using Genix version 3; otherwise, perhaps +@file{tm-ns32k.h} will work for you. + +Note that Genix has bugs in @code{alloca} and @code{malloc}; you must +get the compiled versions of these from GNU Emacs and edit GNU CC's +@file{Makefile} to use them. -For the vax, use @file{tm-vax.h} on BSD Unix, @file{tm-ultrix.h} -on Ultrix, or @file{tm-vms.h} on VMS.@refill +Note that Encore systems are supported only under BSD. @item Make a symbolic link named @file{md} to the machine description @@ -956,12 +1082,13 @@ subroutine file for your machine (its na @item Make sure the Bison parser generator is installed. (This is -unnecessary if the Bison output file @file{parse.tab.c} is more recent -than @file{parse.y} and you do not plan to change @file{parse.y}.) +unnecessary if the Bison output files @file{c-parse.tab.c} and +@file{cexp.c} are more recent than @file{c-parse.y} and @file{cexp.y} +and you do not plan to change the @samp{.y} files.) Note that if you have an old version of Bison you may get an error from the line with the @samp{%expect} directive. If so, simply remove -that line from @file{parse.y} and proceed. +that line from @file{c-parse.y} and proceed. @item If you are using a Sun, make sure the environment variable @@ -1006,7 +1133,7 @@ time, do this: @example make stage2 -make CC=stage2/gcc CFLAGS="-g -O -Bstage2/" +Make CC=stage2/gcc CFLAGS="-g -O -Bstage2/" foreach file (*.o) cmp $file stage2/$file end @@ -1018,6 +1145,9 @@ that the stage 2 compiler has compiled G therefore a potentially serious bug which you should investigate and report (@pxref{Bugs}). +Aside from the @samp{-B} option, the options should be the same as +when you made stage 2. + @item Install the compiler driver, the compiler's passes and run-time support. You can use the following command: @@ -1034,6 +1164,11 @@ program looks for them. It also copies into the directory @file{/usr/local}, so that it appears in typical execution search paths.@refill +@strong{Warning: there is a bug in @code{alloca} in the Sun library. +To avoid this bug, install the binaries of GNU CC that were compiled +by GNU CC. They use @code{alloca} as a built-in function and never +the one in the library.} + @strong{Warning: the GNU CPP may not work for @file{ioctl.h}, @file{ttychars.h} and other system header files unless the @samp{-traditional} option is used.} The bug is in the header files: @@ -1049,12 +1184,12 @@ the system's own C preprocessor. To do Alternatively, on Sun systems and 4.3BSD at least, you can correct the include files by running the shell script @file{fixincludes}. This -installs modified, corrected copies of the files @file{ioctl.h} and -@file{ttychars.h} in a special directory where only GNU CC will -normally look for them. +installs modified, corrected copies of the files @file{ioctl.h}, +@file{ttychars.h} and many others, in a special directory where only +GNU CC will normally look for them. -The file @file{/usr/include/vaxuba/qvioctl.h} used in the X window -system needs a similar correction. +See the file @file{fixincludes} for a list of all the files we know to +require correction. @end enumerate If you cannot install the compiler's passes and run-time support in @@ -1064,12 +1199,24 @@ the prefix with the names @file{cpp}, @ Thus, you can put the files in a directory @file{/usr/foo/gcc} and specify @samp{-B/usr/foo/gcc/} when you run GNU CC. +Also, you can specify an alternative default directory for these files +by setting the Make variable @code{libdir} when you make GNU CC. + @node VMS Install,, Installation, Installation @section Installing GNU CC on VMS -The VMS version of GNU CC is normally distributed as a Backup -saveset, so the only installation required is to copy the files. -But here is how to rebuild GNU CC if you change it: +The VMS version of GNU CC is distributed in an unusual tape format which +consists of several tape files. The first is a command file; the second is +an executable program which reads Unix tar format; the third is another +command file which uses this program to read the remainder of the tape. + +To load the tape, it suffices to mount it @samp{/foreign} and then do +@samp{@@mta0:} to execute the command file at the beginning of the tape. + +The tape contains executables and object files as well as sources, so no +compilation is necessary unless you change the sources. (This is a good +thing, since you probably don't have any other C compiler.) If you must +recompile, here is how: @enumerate @item @@ -1081,7 +1228,70 @@ to @file{aux-output.c}.@refill Type @samp{@@make} to do recompile everything. @end enumerate -@node Incompatibilities, Extensions, Installation, Top +To install the @samp{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 +(@samp{gcc-cpp}, @samp{gcc-cc1}, etc.) and the C include files are +kept. This should be done with the commands:@refill + +@example +$ assign /super /system disk:[gcc] gnu_cc +$ assign /super /system disk:[gcc.include] gnu_cc_include +@end example + +@noindent +with the appropriate disk and directory names. These commands can be +placed in your system startup file so they will be executed whenever +the machine is rebooted. + +@item +Install the @samp{GCC} command with the command line: + +@example +$ set command /table=sys$library:dcltables gnu_cc:gcc +@end example + +@noindent +Now you can invoke the compiler with a command like @samp{gcc /verbose +file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in +Unix. +@end enumerate + +@node Trouble, Incompatibilities, Installation, Top +@chapter Trouble in Installation + +Here are some of the things that have caused trouble for people installing +GNU CC. + +@itemize @bullet +@item +On certain systems, defining certain environment variables such as +@samp{CC} can interfere with the functioning of @code{make}. + +@item +Cross compilation can run into trouble for certain machines because +some target machines' assemblers require floating point numbers to be +written as @emph{integer} constants in certain contexts. + +The compiler writes these integer constants by examining the floating +point value as an integer and printing that integer, because this is +simple to write and independent of the details of the floating point +representation. But this does not work if the compiler is running on +a different machine with an incompatible floating point format, or +even a different byte-ordering. + +It is possible to fix this by writing machine-independent code which +understands the floating point representation of the target machine. +I am not interested in doing that much work to compensate for bugs +in assemblers. +@end itemize + +@node Incompatibilities, Extensions, Trouble, Top @chapter Incompatibilities of GNU CC There are several noteworthy incompatibilities between GNU C and most @@ -1183,6 +1393,22 @@ by Bison grammar rules rather than C cod flag cannot alter it. @item +PCC allows typedef names to be used as function parameters. The +difficulty described immediately above applies here too. + +@item +PCC allows whitespace in the middle of compound assignment operators +such as @samp{+=}. GNU CC, following the ANSI standard, does not +allow this. The difficulty described immediately above applies here +too. + +@item +When compiling functions that return @code{float}, PCC converts it to +a double. GNU CC actually returns a @code{float}. If you are concerned +with PCC compatibility, you should declare your functions to return +@code{double}; you might as well say what you mean. + +@item When compiling functions that return structures or unions, GNU CC output code uses a method different from that used on most versions of Unix. As a result, code compiled with GNU CC cannot call a @@ -1215,8 +1441,9 @@ struct foo *nextfoo (); @end example @noindent -(Note that this assumes you are using the GNU preprocessor, so that -the ANSI antirecursion rules for macro expansions are effective.) +(Note that this assumes you are using the GNU preprocessor and not +@samp{-traditional}, so that the ANSI antirecursion rules for macro +expansions are effective.) @end itemize @node Extensions, Bugs, Incompatibilities, Top @@ -1516,7 +1743,7 @@ struct line @{ @{ struct line *thisline = (struct line *) malloc (sizeof (struct line) + this_length); - thisline->length = thislength; + thisline->length = this_length; @} @end example @@ -1791,20 +2018,26 @@ from the first input, if any. Commas se inputs. The number of operands is limited to the maximum number of operands in any instruction pattern in the machine description. -Output operand expressions must be lvalues, and there must be at least one -of them. The compiler can check this. The input operands need not be -lvalues, and there need not be any. The compiler cannot check whether the -operands have data types that are reasonable for the instruction being -executed. +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. + +If there are no output operands, and there are input operands, then you +should write two colons in a row where the output operands would go. The output operands must be write-only; GNU CC will assume that the values in these operands before the instruction are dead and need not be -generated. For an operand that is read-write, 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) +generated. For an operand that is read-write, or in which not all bits are +written and the other bits contain useful information, you must logically +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: @@ -1814,8 +2047,42 @@ asm ("combine %2,%0" : "=r" (foo) : "0" @noindent The constraint @samp{"0"} for operand 1 says that it must occupy the same -location as operand 0. Therefore it is not necessary to substitute operand -1 into the assembler code output. +location as operand 0. + +Only a digit in the constraint can guarantee that one operand will be in +the same place as another. The mere fact that @code{foo} is the value of +both operands is not enough to guarantee that they will be in the same +place in the generated assembler code. The following would not work: + +@example +asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); +@end example + +Various optimizations or reloading could cause operands 0 and 1 to be in +different registers; GNU CC knows no reason not to do so. For example, the +compiler might find a copy of the value of @code{foo} in one register and +use it for operand 1, but generate the output operand 0 in a different +register (copying it afterward to @code{foo}'s own address). Of course, +since the register for operand 1 is not even mentioned in the assembler +code, the result will not work, but GNU CC can't tell that. + +Unless an output operand has the @samp{&} constraint modifier, GNU CC may +allocate it in the same register as an unrelated input operand, on the +assumption that the inputs are consumed before the outputs are produced. +This assumption may be false if the assembler code actually consists of +more than one instruction. In such a case, use @samp{&} for each output +operand that may not overlap an input. @xref{Modifiers}. + +Some instructions clobber specific hard registers. To describe this, +write a third colon after the input operands, followed by the names of +the clobbered hard registers (given as strings). For example, on 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 Usually the most convenient way to use these @code{asm} instructions is to encapsulate them in macros that look like functions. For example, @@ -1950,8 +2217,7 @@ execute the input source code, that is a 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 features valuable -features. +bugs, but they are inescapable consequences of valuable features. Or you may have a program whose behavior is undefined, which happened by chance to give the desired results with another C compiler. @@ -2112,6 +2378,14 @@ generated for that line. If you send me examples of output from GNU CC, please use @samp{-g} when you make them. The debugging information includes source line numbers which are essential for correlating the output with the input. + +@item +If you wish to suggest changes to the GNU CC source, send me context +diffs. If you even discuss something in the GNU CC source, refer to +it by context, not by line number. + +The line numbers in my development sources don't match those in your +sources. They won't tell me anything. @end itemize Here are some things that are not necessary: @@ -2207,7 +2481,7 @@ and unions of other sizes are returned b passed by the caller in a register. This method is faster than the one normally used by PCC and is also reentrant. The register used for passing the address is specified by the machine-description macro -@code{STRUCT_VALUE_REGNUM}. +@code{STRUCT_VALUE}. GNU CC always passes arguments on the stack. At some point it will be extended to pass arguments in registers, for machines which use that as @@ -2292,12 +2566,12 @@ represented as declaration nodes. Constant folding and associative-law simplifications are also done during this pass. -The source files for parsing are @file{parse.y}, @file{decl.c}, -@file{typecheck.c}, @file{stor-layout.c}, @file{fold-const.c}, and -@file{tree.c}. The last three are intended to be language-independent. -There are also header files @file{parse.h}, @file{c-tree.h}, -@file{tree.h} and @file{tree.def}. The last two define the format of -the tree representation.@refill +The source files for parsing are @file{c-parse.y}, @file{c-decl.c}, +@file{c-typeck.c}, @file{c-convert.c}, @file{stor-layout.c}, +@file{fold-const.c}, and @file{tree.c}. The last three files are +intended to be language-independent. There are also header files +@file{c-parse.h}, @file{c-tree.h}, @file{tree.h} and @file{tree.def}. +The last two define the format of the tree representation.@refill @item RTL generation. This is the conversion of syntax tree into RTL code. @@ -2741,6 +3015,16 @@ that the value of the expression never c current function). In an RTL dump, this flag is represented as @samp{/u}. + +@item integrated +In some kinds of expressions, including insns, this flag means the +rtl was produced by procedure integration. + +In a @samp{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 @@ -3001,6 +3285,11 @@ The compilation parameter @code{WORDS_BI that word number zero is the most significant part; otherwise, it is the least significant part. +Between the combiner pass and the reload pass, it is possible to have +a @samp{subreg} which contains a @samp{mem} instead of a @samp{reg} as +its first operand. The reload pass eliminates these cases by +reloading the @samp{mem} into a suitable register. + Note that it is not valid to access a @code{DFmode} value in @code{SFmode} using a @samp{subreg}. On some machines the most significant part of a @code{DFmode} value does not have the same format as a single-precision @@ -3422,8 +3711,10 @@ used. @item (call @var{function} @var{nargs}) Represents a function call. @var{function} is a @samp{mem} expression -whose address is the address of the function to be called. @var{nargs} -is an expression representing the number of words of argument. +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 @@ -3482,6 +3773,15 @@ location addressed by it are interchange @code{(reg:SI 1)} appears as a memory address it refers to the value in register 1 @emph{before} the execution of the instruction. +Peephole optimization, which takes place in the last jump-optimization +pass, can produce insns whose patterns consist of a @samp{parallel} +whose elements are the operands needed to output the resulting +assembler code--often @samp{reg}, @samp{mem} or constant expressions. +This would not be well-formed RTL at any other stage in compilation, +but it is ok then because no further optimization remains to be done. +However, the definition of the macro @code{NOTICE_UPDATE_CC} may need +to deal with such insns. + @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 @@ -3863,8 +4163,11 @@ appropriate register receives a useful v Immediately after RTL generation, if the value of the subroutine is actually used, this call insn is always followed closely by an insn which -refers to the register @var{r}. The following insn has one of two forms. -Either it copies the value into a pseudo-register, like this: +refers to the register @var{r}. This remains true through all the +optimizer passes until cross jumping occurs. + +The following insn has one of two forms. Either it copies the value into a +pseudo-register, like this: @example (set (reg:@var{m} @var{p}) (reg:@var{m} @var{r})) @@ -3879,7 +4182,7 @@ value the call produced, and no operatio @end example @noindent -Between the call insn and this insn there may intervene only a +Between the call insn and this following insn there may intervene only a stack-adjustment insn (and perhaps some @samp{note} insns). When a subroutine returns a @code{BLKmode} value, it is handled by @@ -4102,8 +4405,9 @@ pattern will not match at all. Operand numbers must be chosen consecutively counting from zero in each instruction pattern. There may be only one @samp{match_operand} -expression in the pattern for each expression number, and they must -appear in order of increasing expression number. +expression in the pattern for each operand number. Usually operands +are numbered in the order of appearance in @samp{match_operand} +expressions. @var{testfn} is a string that is the name of a C function that accepts two arguments, a machine mode and an expression. During matching, @@ -4692,6 +4996,36 @@ natural mode is wider than @var{m}, the 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 have a reload. + +Therefore, when given such a pair of operands, the pattern must +generate RTL which needs no temporary registers---no registers other +than the operands. For example, if you support the pattern with a +@code{define_expand}, then in such a case you mustn't call +@code{force_reg} or any other such function which might generate new +pseudo registers. + +This requirement exists even for subword modes on a RISC machine where +fetching those modes from memory normally requires several insns and +some temporary registers. Look in @file{spur.md} to see how the +requirement is satisfied. + +The variety of operands that have reloads depends on the rest of the +machine description, but typically on a RISC machine these can only be +pseudo registers that did not get hard registers, while on other +machines explicit memory references will get optional reloads. + +In addition, the constraints must allow any hard register to be moved +to any other hard register (provided that @code{HARD_REGNO_MODE_OK} +permits mode @var{m} in each of the registers). + @item @samp{movstrict@var{m}} Like @samp{mov@var{m}} except that if operand 0 is a @samp{subreg} with mode @var{m} of a register whose natural mode is wider, @@ -4706,6 +5040,12 @@ means of constraints requiring operands @item @samp{sub@var{m}3}, @samp{mul@var{m}3}, @samp{umul@var{m}3}, @samp{div@var{m}3}, @samp{udiv@var{m}3}, @samp{mod@var{m}3}, @samp{umod@var{m}3}, @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3} Similar, for other arithmetic operations. +There are special considerations for register classes for logical-and +instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}. +They apply not only to the patterns with these standard names, but to +any patterns that will match such an instruction. @xref{Register +Classes}. + @item @samp{andcb@var{m}3} Bitwise logical-and operand 1 with the complement of operand 2 and store the result in operand 0. @@ -4751,6 +5091,12 @@ allow negative shift counts often have o shifting left. On such machines, you should define a pattern named @samp{ashl@var{m}3} and leave @samp{lshl@var{m}3} undefined. +There are special considerations for register classes for shift +instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}. +They apply not only to the patterns with these standard names, but to +any patterns that will match such an instruction. @xref{Register +Classes}. + @item @samp{neg@var{m}2} Negate operand 1 and store the result in operand 0. @@ -4895,18 +5241,78 @@ that refers to the label to jump to. Ju meet condition @var{cond}. @item @samp{call} -Subroutine call instruction. Operand 1 is the number of bytes of -arguments pushed (in mode @code{SImode}), and operand 0 is the -function to call. Operand 0 should be a @samp{mem} RTX whose address -is the address of the function. +Subroutine call instruction returning no value. Operand 0 is the +function to call; operand 1 is the number of bytes of arguments pushed +(in mode @code{SImode}, except it is normally a @samp{const_int}); +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 @samp{mem} RTX whose address is the address of +the function. + +@item @samp{call_value} +Subroutine call instruction returning a value. Operand 0 is the hard +register in which the value is returned. There are three more +operands, the same as the three operands of the @samp{call} +instruction (but with numbers increased by one). + +Subroutines that return @code{BLKmode} objects use the @samp{call} +insn. @item @samp{return} Subroutine return instruction. This instruction pattern name should be defined only if a single instruction can do all the work of returning from a function. +@item @samp{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 upper bound for indices in the table, an integer constant. + +@item +A label to jump to if the index has a value outside the bounds. +(If the machine-description macro @code{CASE_DROPS_THROUGH} is defined, +then an out-of-bounds index drops through to the code following +the jump table instead of jumping to this label. In that case, +this label is not actually used by the @samp{casesi} instruction, +but it is always provided as an operand.) + +@item +A label that precedes the table itself. +@end enumerate + +The table is a @samp{addr_vec} or @samp{addr_diff_vec} inside of a +@samp{jump_insn}. The number of elements in the table is one plus the +difference between the upper bound and the lower bound. + @item @samp{tablejump} -@item @samp{case@var{m}} +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 +absolute address to jump to; otherwise, it is an offset which counts +from the address of the table. + +The @samp{tablejump} insn is always the last insn before the jump +table it uses. Its assembler code normally has no need to use the +second operand, but you should incorporate it in the RTL pattern so +that the jump optimizer will not delete the table as unreachable code. @end table @node Pattern Ordering, Dependent Patterns, Standard Names, Machine Desc @@ -5415,8 +5821,10 @@ compiler source files include @file{conf @table @code @item CPP_PREDEFINES -Define this to be a string constant containing @samp{-D} options -to define the predefined macros that identify this machine and system. +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. For example, on the Sun, one can use the value @@ -5424,6 +5832,20 @@ For example, on the Sun, one can use the "-Dmc68000 -Dsun -Dunix" @end example +@item CPP_SPEC +A C string constant that tells the GNU CC driver program options to +pass to CPP. It can also specify how to translate options you +give to GNU CC into options for GNU CC to pass to the CPP. + +Do not define this macro if it does not need to do anything. + +@item CC1_SPEC +A C string constant that tells the GNU CC driver program options to +pass to CC1. It can also specify how to translate options you +give to GNU CC into options for GNU CC to pass to the CC1. + +Do not define this macro if it does not need to do anything. + @item extern int target_flags; This declaration should be present. @@ -5473,12 +5895,14 @@ with opposite meanings, and picks the la @{ "68000", -1@}, \ @{ "", 1@}@} @end example -@end table -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. +@item OVERRIDE_OPTIONS +Sometimes certain combinations of command options do not make sense on +a particular target machine. You can define a macro +@code{OVERRIDE_OPTIONS} to take account of this. This macro, if +defined, is executed once just after all the command options have been +parsed. +@end table @node Storage Layout, Registers, Run-time Target, Machine Macros @section Storage Layout @@ -5515,6 +5939,9 @@ Number of storage units in a word; norma @item POINTER_SIZE Width of a pointer, in bits. +@item POINTER_BOUNDARY +Alignment required for pointers stored in memory, in bits. + @item PARM_BOUNDARY Alignment required for function parameters on the stack, in bits. @@ -5529,7 +5956,7 @@ Alignment required for a function entry @item BIGGEST_ALIGNMENT Biggest alignment that any data type can require on this machine, in bits. -@item EMPTY_FIELD_ALIGNMENT +@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;}. @@ -5544,6 +5971,31 @@ If you do not define this macro, the def Define this if instructions will fail to work if given data not on the nominal alignment. If instructions will merely go slower in that case, do not define this macro. + +@item PCC_BITFIELD_TYPE_MATTERS +Define this if you wish to imitate a certain bizarre behavior pattern +of some instances of PCC: a bit field whose declared type is +@code{int} has the same effect on the size and alignment of a +structure as an actual @code{int} would have. + +Just what effect that is in GNU CC depends on other parameters, but on +most machines it would force the structure's alignment and size to a +multiple of 32 or @code{BIGGEST_ALIGNMENT} bits. + +@item CHECK_FLOAT_VALUE (@var{mode}, @var{value}) +A C statement to validate the value @var{value} (or type +@code{double}) for mode @var{mode}. This means that you check whether +@var{value} fits within the possible range of values for mode +@var{mode} on this target machine. The mode @var{mode} is always +@code{SFmode} or @code{DFmode}. + +If @var{value} is not valid, you should call @code{error} to print an +error message and then assign some valid value to @var{value}. +Allowing an invalid value to go through the compiler can produce +incorrect assembler code which may even cause Unix assemblers to +crash. + +This macro need not be defined if there is no work for it to do. @end table @node Registers, Register Classes, Storage Layout, Machine Macros @@ -5560,9 +6012,10 @@ pseudo register's number really is assig 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, the program counter on machines where that is considered one -of the addressable registers, and any other numbered register with a -standard use. +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 @@ -5595,6 +6048,60 @@ on target flags. You need not define this macro if it has no work to do. +If the usage of an entire class of registers depends on the target +flags, you may indicate this to gcc by using this macro to modify +@code{fixed_regs} and @code{call_used_regs} to 1 for each of the +registers in the classes which should not be used by gcc. Also define +the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it +is called with a letter for a class that shouldn't be used. + +(However, if this class is not included in @code{GENERAL_REGS} and all +of the insn patterns whose constraints permit this class are +controlled by target switches, then GCC will automatically avoid using +these registers when the target switches are opposed to them.) + +@item OVERLAPPING_REGNO_P (@var{regno}) +If defined, this is a C expression whose value is @var{regno} is +nonzero if hard register number @var{regno} is an overlapping +register. This means a hard register which overlaps a hard register +with a different number. (Such overlap is undesirable, but +occasionally it allows a machine to be supported which otherwise could +not be.) This macro must return nonzero for @emph{all} the registers +which overlap each other. GNU CC can use an overlapping register only +in certain limited ways. It can be used for allocation within a basic +block, and may be spilled for reloading; that is all. + +If this macro is not defined, it means that none of the hard registers +overlap each other. This is the usual situation. + +@item INSN_CLOBBERS_REGNO_P (@var{insn}, @var{regno}) +If defined, this is a C expression whose value should be nonzero if +the insn @var{insn} has the effect of mysteriously clobbering the +contents of hard register number @var{regno}. By ``mysterious'' we +mean that the insn's RTL expression doesn't describe such an effect. + +If this macro is not defined, it means that no insn clobbers registers +mysteriously. This is the usual situation; all else being equal, +it is best for the RTL expression to show all the activity. + +@item PRESERVE_DEATH_INFO_REGNO_P (@var{regno}) +If defined, this is a C expression whose value is nonzero if accurate +@code{REG_DEAD} notes are needed for hard register number @var{regno} +at the time of outputting the assembler code. When this is so, a few +optimizations that take place after register allocation and could +invalidate the death notes are not done when this register is +involved. + +You would arrange to preserve death info for a register when some +of the code in the machine description which is executed to write +the assembler code looks at the the death notes. This is +necessary only when the actual hardware feature which GNU CC +thinks of as a register is not actually a register of the usual sort. +(It might, for example, be a hardware stack.) + +If this macro is not defined, it means that no death notes need to be +preserved. This is the usual situation. + @item HARD_REGNO_REGS (@var{regno}, @var{mode}) A C expression for the number of consecutive hard registers, starting at register number @var{regno}, required to hold a value of mode @@ -5691,16 +6198,16 @@ the function a frame pointer regardless them.@refill In a function that does not require a frame pointer, the frame pointer -register can be allocated for ordinary usage, provided it is not -marked as a fixed register. See @code{FIXED_REGISTERS} for more -information. +register can be allocated for ordinary usage, unless you mark it as a +fixed register. See @code{FIXED_REGISTERS} for more information. @item ARG_POINTER_REGNUM The register number of the arg pointer register, which is used to access the function's argument list. On some machines, this is the same as the frame pointer register. On some machines, the hardware determines which register this is. On other machines, you can choose -any register you wish for this purpose. It must in any case be a +any register you wish for this purpose. If this is not the same +register as the frame pointer register, then you must mark it as a fixed register according to @code{FIXED_REGISTERS}. @item STATIC_CHAIN_REGNUM @@ -5708,7 +6215,7 @@ The register number used for passing a f pointer. This is needed for languages such as Pascal and Algol where functions defined within other functions can access the local variables of the outer functions; it is not currently used because C -does not provide this feature. +does not provide this feature, but you must define the macro. The static chain register need not be a fixed register. @@ -5716,8 +6223,48 @@ The static chain register need not be a When a function's value's mode is @code{BLKmode}, the value is not returned according to @code{FUNCTION_VALUE}. Instead, the caller passes the address of a block of memory in which the value should be -stored. @code{STRUCT_VALUE_REGNUM} is the register in which this -address is passed. +stored. + +If this value is passed in a register, then @code{STRUCT_VALUE_REGNUM} +should be the number of that register. + +@item STRUCT_VALUE +If the structure value address is not passed in a register, define +@code{STRUCT_VALUE} as an expression returning an RTX for the place +where the address is passed. If it returns a @samp{mem} RTX, the +address is passed as an ``invisible'' first argument. + +@item STRUCT_VALUE_INCOMING_REGNUM +On some architectures the place where the structure value address +is found by the called function is not the same place that the +caller put it. This can be due to register windows, or it could +be because the function prologue moves it to a different place. + +If the incoming location of the structure value address is in a +register, define this macro as the register number. + +@item STRUCT_VALUE_INCOMING +If the incoming location is not a register, define +@code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the +called function should find the value. If it should find the value on +the stack, define this to create a @samp{mem} which refers to the +frame pointer. If the value is a @samp{mem}, the compiler assumes it +is for an invisible first argument, and leaves space for it when +finding the first real argument. + +@item REG_ALLOC_ORDER +If defined, an initializer for a vector of integers, containing the +numbers of hard registers in the order in which the GNU CC should +prefer to use them (from most preferred to least). + +If this macro is not defined, registers are used lowest numbered first +(all else being equal). + +One use of this macro is on the 360, where the highest numbered +registers must always be saved and the save-multiple-registers +instruction supports only sequences of consecutive registers. This +macro is defined to cause the highest numbered allocatable registers +to be used first. @end table @node Register Classes, Stack Layout, Registers, Machine Macros @@ -5759,6 +6306,16 @@ classes: for each class, which classes c contained in it; for each pair of classes, the largest class contained in their union. +Register classes used for input-operands of bitwise-and or shift +instructions have a special requirement: each such class must have, for +each fixed-point machine mode, a subclass whose registers can transfer that +mode to or from memory. For example, on some machines, the operations for +single-byte values (@code{QImode}) are limited to certain registers. When +this is so, each register class that is used in a bitwise-and or shift +instruction must have a subclass consisting of registers from which +single-byte values can be loaded or stored. This is so that +@code{PREFERRED_RELOAD_CLASS} can always have a possible value to return. + @table @code @item enum reg_class An enumeral type that must be defined with all the register class names @@ -5771,6 +6328,13 @@ Each register class has a number, which the class name to type @code{int}. The number serves as an index in many of the tables described below. +@item N_REG_CLASSES +The number of distinct register classes, defined as follows: + +@example +#define N_REG_CLASSES (int) LIM_REG_CLASSES +@end example + @item REG_CLASS_NAMES An initializer containing the names of the register classes as C string constants. These names are used in writing some of the debugging dumps. @@ -5792,15 +6356,22 @@ A C expression whose value is a register which is @dfn{minimal}, meaning that no smaller class also contains the register. +@item BASE_REG_CLASS +A macro whose definition is the name of the class to which a valid +base register must belong. A base register is one used in an address +which is the register value plus a displacement. + @item INDEX_REG_CLASS -A macro whose definition is the name of the class to which a valid index -register must belong. +A macro whose definition is the name of the class to which a valid +index register must belong. An index register is one used in an +address where its value is either multiplied by a scale factor or +added to another register (as well as added to a displacement). @item REG_CLASS_FROM_LETTER (@var{char}) A C expression which defines the machine-dependent operand constraint -letters for register classes. If @var{char} is such a letter, the value -should be the register class corresponding to it. Otherwise, the value -should be @code{NO_REGS}. +letters for register classes. If @var{char} is such a letter, the +value should be the register class corresponding to it. Otherwise, +the value should be @code{NO_REGS}. @item REGNO_OK_FOR_BASE_P (@var{num}) A C expression which is nonzero if register number @var{num} is @@ -5820,27 +6391,49 @@ two registers, neither one of them scale 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 reload one or both registers only -if neither labeling works. +looking for one that is valid, and will reload one or both registers +only if neither labeling works. @item PREFERRED_RELOAD_CLASS (@var{x}, @var{class}) A C expression that places additional restrictions on the register class to use when it is necessary to copy value @var{x} into a register in class @var{class}. The value is a register class; perhaps @var{class}, or perhaps -another, smaller class. @var{class} is always safe as a value. In fact, -the definition +another, smaller class. On many machines, the definition @example #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS @end example @noindent -is always safe. However, 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. +is safe. + +Sometimes returning a more restrictive class makes better code. For +example, on the 68000, when @var{x} is an integer constant that is in range +for a @samp{moveq} instruction, the value of this macro is always +@code{DATA_REGS} as long as @var{class} includes the data registers. +Requiring a data register guarantees that a @samp{moveq} will be used. + +If @var{x} is a @samp{const_double}, by returning @code{NO_REGS} +you can force @var{x} into a memory constant. This is useful on +certain machines where immediate floating values cannot be loaded into +certain kinds of registers. + +In a shift instruction or a bitwise-and instruction, the mode of @var{x}, +the value being reloaded, may not be the same as the mode of the +instruction's operand. (They will both be fixed-point modes, however.) In +such a case, @var{class} may not be a safe value to return. @var{class} is +certainly valid for the instruction, but it may not be valid for reloading +@var{x}. This problem can occur on machines such as the 68000 and 80386 +where some registers can handle full-word values but cannot handle +single-byte values. + +On such machines, this macro must examine the mode of @var{x} and return a +subclass of @var{class} which can handle loads and stores of that mode. On +the 68000, where address registers cannot handle @code{QImode}, if @var{x} +has @code{QImode} then you must return @code{DATA_REGS}. If @var{class} is +@code{ADDR_REGS}, then there is no correct value to return; but the shift +and bitwise-and instructions don't use @code{ADDR_REGS}, so this fatal case +never arises. @item CLASS_MAX_NREGS (@var{class}, @var{mode}) A C expression for the maximum number of consecutive registers @@ -5923,8 +6516,11 @@ alignment. Then the definition should b #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1) @end example -@item FIRST_PARM_OFFSET -Offset from the argument pointer register to the first argument's address. +@item FIRST_PARM_OFFSET (@var{fundecl}) +Offset from the argument pointer register to the first argument's +address. On some machines it may depend on the data type of the +function. (In the next version of GNU CC, the argument will be +changed to the function data type rather than its declaration.) @item RETURN_POPS_ARGS (@var{funtype}) A C expression that should be 1 if a function pops its own arguments @@ -5998,7 +6594,7 @@ compiled. @item FUNCTION_VALUE_REGNO_P (@var{regno}) A C expression that is nonzero if @var{regno} is the number of a hard -register in which function values are sometimes returned. +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 @@ -6009,6 +6605,10 @@ suffices: #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0) @end example +If the machine has register windows, so that the caller and the called +function use different registers for the return value, this macro +should recognize only the caller's register numbers. + @item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named}) A C expression that controls whether a function argument is passed in a register, and which register. @@ -6066,10 +6666,12 @@ of @code{FUNCTION_ARG} and other related machines, the type @code{int} suffices and can hold the number of bytes of argument so far. -@item INIT_CUMULATIVE_ARGS (@var{cum}) +@item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}) A C statement (sans semicolon) for initializing the variable @var{cum} for the state at the beginning of the argument list. The variable has -type @code{CUMULATIVE_ARGS}. +type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node +for the data type of the function which will receive the args, or 0 +if the args are to a compiler support library function. @item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named}) Update the summarizer variable @var{cum} to advance past an argument @@ -6086,6 +6688,24 @@ the structure-value address. On many ma used for this purpose since all function arguments are pushed on the stack. +@item FUNCTION_ARG_PADDING (@var{mode}, @var{size}) +If defined, a C expression which determines whether, and in which direction, +to pad out an argument with extra space. The value should be of type +@code{enum direction}: either @code{upward} to pad above the argument, +@code{downward} to pad below, or @code{none} to inhibit padding. + +The argument @var{size} is an RTX which describes the size of the +argument, in bytes. It should be used only if @var{mode} is +@code{BLKmode}. Otherwise, @var{size} is 0. + +This macro does not control the @emph{amount} of padding; that is +always just enough to reach the next multiple of @code{PARM_BOUNDARY}. + +This macro has a default definition which is right for most systems. +For little-endian machines, the default is to pad upward. For +big-endian machines, the default is to pad downward for an argument of +constant size shorter than an @code{int}, and upward otherwise. + @item FUNCTION_PROLOGUE (@var{file}, @var{size}) A C compound statement that outputs the assembler code for entry to a function. The prologue is responsible for setting up the stack frame, @@ -6150,6 +6770,13 @@ of returning from the function. On thes 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 @@ -6267,6 +6894,28 @@ for index registers, and so on). Then o need have two variants; the higher levels of macros may be the same whether strict or not.@refill +@item REG_OK_FOR_BASE_P (@var{x}) +A C expression that is nonzero if @var{x} (asumed to be a @code{reg} +RTX) is valid for use as a base register. For hard registers, it +should always accept those which the hardware permits and reject the +others. Whether the macro accepts or rejects pseudo registers must be +controlled by @code{REG_OK_STRICT} as described above. This usually +requires two variant definitions, of which @code{REG_OK_STRICT} +controls the one actually used. + +@item REG_OK_FOR_INDEX_P (@var{x}) +A C expression that is nonzero if @var{x} (asumed to be a @code{reg} +RTX) is valid for use as an index register. + +The difference between an index register and a base register is that +the index register may be scaled. If an address involves the sum of +two registers, neither one of them scaled, then either one may be +labeled the ``base'' and the other the ``index''; but whichever +labeling is used must fit the machine's constraints of which registers +may serve in each capacity. The compiler will try both labelings, +looking for one that is valid, and will reload one or both registers +only if neither labeling works. + @item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win}) A C compound statement that attempts to replace @var{x} with a valid memory address for an operand of mode @var{mode}. @var{win} will be a @@ -6357,7 +7006,11 @@ and @samp{-funsigned-char}. @item SCCS_DIRECTIVE Define this if the preprocessor should ignore @code{#sccs} directives -with no error message. +and print no error message. + +@item IDENT_DIRECTIVE +Define this if the preprocessor should ignore @code{#ident} directives +and print no error message. @item MOVE_MAX The maximum number of bytes that a single instruction can move quickly @@ -6404,6 +7057,12 @@ On many machines, this expression can be Define this macro if it is as good or better to call a constant function address than to call an address kept in a register. +@item PROMOTE_PROTOTYPES +Define this macro if an argument declared as @code{char} or +@code{short} in a prototype should actually be passed as an +@code{int}. In addition to avoiding errors in certain cases of +mismatch, it also makes for better code on certain machines. + @item STORE_FLAG_VALUE A C expression for the value stored by a store-flag instruction (@code{s@var{cond}}) when the condition is true. This is usually 1 or @@ -6425,7 +7084,7 @@ An alias for the machine mode used for m being called, in @samp{call} RTL expressions. On most machines this should be @code{QImode}. -@item CONST_COST (@var{x}, @var{code}) +@item CONST_COSTS (@var{x}, @var{code}) A part of a C @code{switch} statement that describes the relative costs of constant RTL expressions. It must contain @code{case} labels for expression codes @samp{const_int}, @samp{const}, @samp{symbol_ref}, @samp{label_ref} @@ -6439,8 +7098,8 @@ precise value of the constant, which is obtained with @code{GET_CODE (@var{x})}. @item DOLLARS_IN_IDENTIFIERS -Define this if the character @samp{$} should be allowed in identifier -names. +Define this to be nonzero if the character @samp{$} should be allowed +by default in identifier names. @end table @node Condition Code, Assembler Format, Misc, Machine Macros @@ -6485,6 +7144,14 @@ this, it will no longer be true that it @samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter @code{cc_status} in this case to say that nothing is known about the condition code value. + +The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal +with the results of peephole optimization: insns whose patterns are +@samp{parallel} RTXs containing various @samp{reg}, @samp{mem} or +constants which are just the operands. The RTL structure of these +insns is not sufficient to indicate what the insns actually do. What +@code{NOTICE_UPDATE_CC} should do when it sees one is just to run +@code{CC_STATUS_INIT}. @end table @node Assembler Format,, Condition Code, Machine Macros @@ -6506,12 +7173,33 @@ give to GNU CC into options for GNU CC t Do not define this macro if it does not need to do anything. -@item ASM_FILE_START -A C string constant for text to be output at the start of each -assembler output file. Normally this is @code{"#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. +@item LIB_SPEC +Another C string constant used much like @code{LINK_SPEC}. The difference +between the two is that @code{LIBS_SPEC} is used at the end of the +command given to the linker. + +If this macro is not defined, a default is provided that +loads the standard C library from the usual place. See @file{gcc.c}. + +@item STARTFILE_SPEC +Another C string constant used much like @code{LINK_SPEC}. The +difference between the two is that @code{STARTFILE_SPEC} is used at +the very beginning of the command given to the linker. + +If this macro is not defined, a default is provided that loads the +standard C startup file from the usual place. See @file{gcc.c}. + +@item ASM_FILE_START (@var{stream}) +A C expression which outputs to the stdio stream @var{stream} +some appropriate text to go at the start of an assembler file. + +Normally this macro is defined to output a line containing +@samp{#NO_APP}, which is a comment that has no effect on most +assemblers but tells the GNU assembler that it can save time by not +checking for certain assembler constructs. + +On systems that use SDB, it is necessary to output certain commands; +see @file{tm-attasm.h}. @item ASM_APP_ON A C string constant for text to be output before each @code{asm} @@ -6548,6 +7236,25 @@ registers that the compiler knows about versa. In such cases, some register may need to have one number in the compiler and another for DBX. +@item DBX_DEBUGGING_INFO +Define this macro if GNU CC should produce debugging output for DBX +in response to the @samp{-g} option. + +@item SDB_DEBUGGING_INFO +Define this macro if GNU CC should produce debugging output for SDB +in response to the @samp{-g} option. + +@item PUT_SDB_@var{op} +Define these macros to override the assembler syntax for the special +SDB assembler directives. See @file{sdbout.c} for a list of these +macros and their arguments. If the standard syntax is used, you need +not define them yourself. + +@item SDB_GENERATE_FAKE +Define this macro to override the usual method of constructing a dummy +name for anonymous structure and union types. See @file{sdbout.c} for +more infomation. + @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 @@ -6570,47 +7277,59 @@ a different character instead, define th constant for the character you want to use. Do not define this macro if backslash is correct for your system. -@item ASM_OUTPUT_LABEL (@var{file}, @var{name}) +@item ASM_OUTPUT_LABEL (@var{stream}, @var{name}) A C statement (sans semicolon) to output to the stdio stream -@var{file} the assembler definition of a label named @var{name}. Use -the expression @code{assemble_name (@var{file}, @var{name})} to output +@var{stream} the assembler definition of a label named @var{name}. Use +the expression @code{assemble_name (@var{stream}, @var{name})} to output the name itself; before and after that, output the additional assembler syntax for defining the name, and a newline. -@item ASM_DECLARE_FUNCTION_NAME (@var{file}, @var{name}) +@item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl}) A C statement (sans semicolon) to output to the stdio stream -@var{file} any text necessary for declaring the name of a function -which is being defined. This macro is responsible for outputting -the label definition (perhaps using @code{ASM_OUTPUT_LABEL}). +@var{stream} any text necessary for declaring the name @var{name} of a +function which is being defined. This macro is responsible for +outputting the label definition (perhaps using +@code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the +@code{FUNCTION_DECL} tree node representing the function. If this macro is not defined, then the function name is defined in the usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}). -@item ASM_GLOBALIZE_LABEL (@var{file}, @var{name}) +@item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name}) A C statement (sans semicolon) to output to the stdio stream -@var{file} some commands that will make the label @var{name} global; +@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{file}, @var{name})} to output the name +@code{assemble_name (@var{stream}, @var{name})} to output the name itself; before and after that, output the additional assembler syntax for making that name global, and a newline. -@item ASM_OUTPUT_EXTERNAL (@var{file}, @var{name}) +@item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{name}, @var{decl}) A C statement (sans semicolon) to output to the stdio stream -@var{file} any text necessary for declaring the name of an external -symbol which is referenced in this compilation but not defined. +@var{stream} any text necessary for declaring the name of an external +symbol named @var{name} which is referenced in this compilation but +not defined. The value of @var{decl} is the tree node for the +declaration. This macro need not be defined if it does not need to output anything. The GNU assembler and most Unix assemblers don't require anything. -@item ASM_OUTPUT_LABELREF (@var{file}, @var{name}) -A C statement to output to the stdio stream @var{file} a reference in +@item ASM_OUTPUT_LABELREF (@var{stream}, @var{name}) +A C statement to output to the stdio stream @var{stream} a reference in assembler syntax to a label named @var{name}. The character @samp{_} should be added to the front of the name, if that is customary on your operating system, as it is in most Berkeley Unix systems. This macro is used in @code{assemble_name}. -@item ASM_OUTPUT_INTERNAL_LABEL (@var{file}, @var{prefix}, @var{num}) -A C statement to output to the stdio stream @var{file} a label whose +@item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num}) +A C statement to store into the string @var{string} a label whose +name is made from the string @var{prefix} and the number @var{num}. + +This string, when output subsequently by @code{ASM_OUTPUT_LABELREF}, +should produce the same output that @code{ASM_OUTPUT_INTERNAL_LABEL} +would produce with the same @var{prefix} and @var{num}. + +@item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num}) +A C statement to output to the stdio stream @var{stream} a label whose name is made from the string @var{prefix} and the number @var{num}. These labels are used for internal purposes, and there is no reason for them to appear in the symbol table of the object file. On many @@ -6618,10 +7337,10 @@ systems, the letter @samp{L} at the begi effect. The usual definition of this macro is as follows: @example -fprintf (@var{file}, "L%s%d:\n", @var{prefix}, @var{num}) +fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num}) @end example -@item ASM_OUTPUT_CASE_LABEL (@var{file}, @var{prefix}, @var{num}, @var{table}) +@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 @@ -6634,6 +7353,16 @@ for the table. If this macro is not defined, these labels are output with @code{ASM_OUTPUT_INTERNAL_LABEL}. +@item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table}) +Define this if something special must be output at the end of a jump-table. +The definition should be a C statement to be executed after the assembler +code for the table is written. It should write the appropriate code to +stdio stream @var{stream}. The argument @var{table} is the jump-table +insn, and @var{num} is the label-number of the preceding label. + +If this macro is not defined, nothing special is output at the end of +the jump-table. + @item ASM_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 @@ -6652,63 +7381,63 @@ conflict with the user's own symbols. M or percent signs in assembler symbols; putting at least one of these between the name and the number will suffice. -@item ASM_OUTPUT_ADDR_DIFF_ELT (@var{file}, @var{value}, @var{rel}) +@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{file} an assembler pseudo-instruction to generate a difference +@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{file}, "\t.word L%d-L%d\n", +fprintf (@var{stream}, "\t.word L%d-L%d\n", @var{value}, @var{rel}) @end example -@item ASM_OUTPUT_ADDR_VEC_ELT (@var{file}, @var{value}) +@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{file} an assembler pseudo-instruction to generate a reference to +@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{file}, "\t.word L%d\n", @var{value}) +fprintf (@var{stream}, "\t.word L%d\n", @var{value}) @end example -@item ASM_OUTPUT_DOUBLE (@var{file}, @var{value}) -A C statement to output to the stdio stream @var{file} an assembler +@item ASM_OUTPUT_DOUBLE (@var{stream}, @var{value}) +A C statement to output to the stdio stream @var{stream} an assembler instruction to assemble a @code{double} constant whose value is @var{value}. @var{value} will be a C expression of type @code{double}. -@item ASM_OUTPUT_FLOAT (@var{file}, @var{value}) -A C statement to output to the stdio stream @var{file} an assembler +@item ASM_OUTPUT_FLOAT (@var{stream}, @var{value}) +A C statement to output to the stdio stream @var{stream} an assembler instruction to assemble a @code{float} constant whose value is @var{value}. @var{value} will be a C expression of type @code{float}. -@item ASM_OUTPUT_INT (@var{file}, @var{exp}) -@itemx ASM_OUTPUT_SHORT (@var{file}, @var{exp}) -@itemx ASM_OUTPUT_CHAR (@var{file}, @var{exp}) -A C statement to output to the stdio stream @var{file} an assembler +@item ASM_OUTPUT_INT (@var{stream}, @var{exp}) +@itemx ASM_OUTPUT_SHORT (@var{stream}, @var{exp}) +@itemx ASM_OUTPUT_CHAR (@var{stream}, @var{exp}) +A C statement to output to the stdio stream @var{stream} an assembler instruction to assemble a @code{int}, @code{short} or @code{char} constant whose value is @var{value}. The argument @var{exp} will be an RTL expression which represents a constant value. Use @samp{output_addr_const (@var{exp})} to output this value as an assembler expression.@refill -@item ASM_OUTPUT_BYTE (@var{file}, @var{value}) -A C statement to output to the stdio stream @var{file} an assembler +@item ASM_OUTPUT_BYTE (@var{stream}, @var{value}) +A C statement to output to the stdio stream @var{stream} an assembler instruction to assemble a single byte containing the number @var{value}. -@item ASM_OUTPUT_ASCII (@var{file}, @var{ptr}, @var{len}) -A C statement to output to the stdio stream @var{file} an assembler +@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}. @@ -6717,38 +7446,46 @@ If the assembler has a @code{.ascii} pse Berkeley Unix assembler, do not define the macro @code{ASM_OUTPUT_ASCII}. -@item ASM_OUTPUT_SKIP (@var{file}, @var{nbytes}) -A C statement to output to the stdio stream @var{file} an assembler +@item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes}) +A C statement to output to the stdio stream @var{stream} an assembler instruction to advance the location counter by @var{nbytes} bytes. @var{nbytes} will be a C expression of type @code{int}. -@item ASM_OUTPUT_ALIGN (@var{file}, @var{power}) -A C statement to output to the stdio stream @var{file} an assembler +@item ASM_OUTPUT_ALIGN (@var{stream}, @var{power}) +A C statement to output to the stdio stream @var{stream} an assembler instruction to advance the location counter to a multiple of 2 to the @var{power} bytes. @var{power} will be a C expression of type @code{int}. -@item ASM_OUTPUT_COMMON (@var{file}, @var{name}, @var{size}) +@item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}) A C statement (sans semicolon) to output to the stdio stream -@var{file} the assembler definition of a common-label named @var{name} +@var{stream} the assembler definition of a common-label named @var{name} whose size is @var{size} bytes. Use the expression -@code{assemble_name (@var{file}, @var{name})} to output the name +@code{assemble_name (@var{stream}, @var{name})} to output the name itself; before and after that, output the additional assembler syntax for defining the name, and a newline. This macro controls how the assembler definitions of uninitialized global variables are output. -@item ASM_OUTPUT_LOCAL (@var{file}, @var{name}, @var{size}) +@item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}) A C statement (sans semicolon) to output to the stdio stream -@var{file} the assembler definition of a local-common-label named +@var{stream} the assembler definition of a local-common-label named @var{name} whose size is @var{size} bytes. Use the expression -@code{assemble_name (@var{file}, @var{name})} to output the name +@code{assemble_name (@var{stream}, @var{name})} to output the name itself; before and after that, output the additional assembler syntax for defining the name, and a newline. This macro controls how the assembler definitions of uninitialized static variables are output. +@item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line}) +A C statment to output DBX or SDB debugging information before code +for line number @var{line} of the current source file to the +stdio stream @var{stream}. + +This macro need not be defined if the standard form of debugging +information for the debugger in use is appropriate. + @item TARGET_BELL A C constant expression for the integer value for escape sequence @samp{\a}. @@ -6765,16 +7502,16 @@ C constant expressions for the integer v C constant expressions for the integer values for escape sequences @samp{\v}, @samp{\f} and @samp{\r}. -@item ASM_OUTPUT_OPCODE (@var{file}, @var{ptr}) +@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{file}. The +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{file}, performing any translation you desire, and +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. @@ -6787,8 +7524,29 @@ care of the substitution yourself. Just If the macro definition does nothing, the instruction is output in the usual way. -@item PRINT_OPERAND (@var{file}, @var{x}, @var{code}) -A C compound statement to output to stdio stream @var{file} the +@item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands}) +If defined, a C statement to be executed just prior to the output of +assembler code for @var{insn}, to modify the extracted operands so +they will be output differently. + +Here the argument @var{opvec} is the vector containing the operands +extracted from @var{insn}, and @var{noperands} is the number of +elements of the vector which contain meaningful data for this insn. +The contents of this vector are what will be used to convert the insn +template into assembler code, so you can change the assembler output +by changing the contents of the vector. + +This macro is useful when various assembler syntaxes share a single +file of instruction patterns; by defining this macro differently, you +can cause a large class of instructions to be output differently (such +as with rearranged operands). Naturally, variations in assembler +syntax affecting individual insn patterns ought to be handled by +writing conditional output routines in those patterns. + +If this macro is not defined, it is equivalent to a null statement. + +@item PRINT_OPERAND (@var{stream}, @var{x}, @var{code}) +A C compound statement to output to stdio stream @var{stream} the assembler syntax for an instruction operand @var{x}. @var{x} is an RTL expression. @@ -6810,8 +7568,8 @@ When the machine description has a speci with a null pointer for @var{x} and the punctuation character for @var{code}. -@item PRINT_OPERAND_ADDRESS (@var{file}, @var{x}) -A C compound statement to output to stdio stream @var{file} the +@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.