![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to internals.texinfo CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 1.x] / gcc|
Return to internals.texinfo CVS log | Up to [GCC 1.x] / gcc |
1.1 root 1: \input texinfo @c -*-texinfo-*-
2:
3: @settitle Internals of GNU CC
4: @setfilename internals
5:
6: @ifinfo
7: This file documents the internals of the GNU compiler.
8:
1.1.1.2 ! root 9: Copyright (C) 1988 Free Software Foundation, Inc.
1.1 root 10:
11: Permission is granted to make and distribute verbatim copies of
12: this manual provided the copyright notice and this permission notice
13: are preserved on all copies.
14:
15: @ignore
16: Permission is granted to process this file through Tex and print the
17: results, provided the printed document carries copying permission
18: notice identical to this one except for the removal of this paragraph
19: (this paragraph not being relevant to the printed manual).
20:
21: @end ignore
22: Permission is granted to copy and distribute modified versions of this
23: manual under the conditions for verbatim copying, provided also that the
24: section entitled ``GNU CC General Public License'' is included exactly as
25: in the original, and provided that the entire resulting derived work is
26: distributed under the terms of a permission notice identical to this one.
27:
28: Permission is granted to copy and distribute translations of this manual
29: into another language, under the above conditions for modified versions,
1.1.1.2 ! root 30: except that the section entitled ``GNU CC General Public License'' and
! 31: this permission notice may be included in translations approved by the
! 32: Free Software Foundation instead of in the original English.
1.1 root 33: @end ifinfo
34:
35: @setchapternewpage odd
36:
37: @titlepage
38: @center @titlefont{Internals of GNU CC}
39: @sp 2
40: @center Richard M. Stallman
1.1.1.2 ! root 41: @sp 3
! 42: @center last updated 24 April 1988
! 43: @sp 1
! 44: @center for version 1.21
1.1 root 45: @page
46: @vskip 0pt plus 1filll
1.1.1.2 ! root 47: Copyright @copyright{} 1988 Free Software Foundation, Inc.
1.1 root 48:
49: Permission is granted to make and distribute verbatim copies of
50: this manual provided the copyright notice and this permission notice
51: are preserved on all copies.
52:
53: Permission is granted to copy and distribute modified versions of this
54: manual under the conditions for verbatim copying, provided also that the
55: section entitled ``GNU CC General Public License'' is included exactly as
56: in the original, and provided that the entire resulting derived work is
57: distributed under the terms of a permission notice identical to this one.
58:
59: Permission is granted to copy and distribute translations of this manual
60: into another language, under the above conditions for modified versions,
61: except that the section entitled ``GNU CC General Public License'' may be
62: included in a translation approved by the author instead of in the original
63: English.
64: @end titlepage
65: @page
66:
67: @ifinfo
1.1.1.2 ! root 68: @node Top, Copying,, (DIR)
! 69: @ichapter Introduction
1.1 root 70:
1.1.1.2 ! root 71: This manual documents how to run, install and port the GNU C compiler, as
! 72: well as its new features and incompatibilities, and how to report bugs.
1.1 root 73:
74: @end ifinfo
75: @menu
76: * Copying:: GNU CC General Public License says
77: how you can copy and share GNU CC.
1.1.1.2 ! root 78: * Contributors:: People who have contributed to GNU CC.
! 79: * Options:: Command options supported by @samp{gcc}.
1.1 root 80: * Installation:: How to configure, compile and install GNU CC.
1.1.1.2 ! root 81: * Incompatibilities:: Incompatibilities of GNU CC.
! 82: * Extensions:: GNU extensions to the C language.
! 83: * Bugs:: How to report bugs (if you want to get them fixed).
1.1 root 84: * Portability:: Goals of GNU CC's portability features.
1.1.1.2 ! root 85: * Interface:: Function-call interface of GNU CC output.
1.1 root 86: * Passes:: Order of passes, what they do, and what each file is for.
87: * RTL:: The intermediate representation that most passes work on.
88: * Machine Desc:: How to write machine description instruction patterns.
89: * Machine Macros:: How to write the machine description C macros.
90: @end menu
91:
1.1.1.2 ! root 92: @node Copying, Contributors, Top, Top
1.1 root 93: @unnumbered GNU CC GENERAL PUBLIC LICENSE
1.1.1.2 ! root 94: @center (Clarified 11 Feb 1988)
1.1 root 95:
96: The license agreements of most software companies keep you at the
97: mercy of those companies. By contrast, our general public license is
98: intended to give everyone the right to share GNU CC. To make sure that
99: you get the rights we want you to have, we need to make restrictions
100: that forbid anyone to deny you these rights or to ask you to surrender
101: the rights. Hence this license agreement.
102:
1.1.1.2 ! root 103: Specifically, we want to make sure that you have the right to give
! 104: away copies of GNU CC, that you receive source code or else can get it
! 105: if you want it, that you can change GNU CC or use pieces of it in new
! 106: free programs, and that you know you can do these things.
! 107:
! 108: To make sure that everyone has such rights, we have to forbid you to
! 109: deprive anyone else of these rights. For example, if you distribute
! 110: copies of GNU CC, you must give the recipients all the rights that you
! 111: have. You must make sure that they, too, receive or can get the
! 112: source code. And you must tell them their rights.
! 113:
! 114: Also, for our own protection, we must make certain that everyone
! 115: finds out that there is no warranty for GNU CC. If GNU CC is modified by
! 116: someone else and passed on, we want its recipients to know that what
! 117: they have is not what we distributed, so that any problems introduced
! 118: by others will not reflect on our reputation.
! 119:
! 120: Therefore we (Richard Stallman and the Free Software Foundation,
! 121: Inc.) make the following terms which say what you must do to be
! 122: allowed to distribute or change GNU CC.
! 123:
! 124: @unnumberedsec COPYING POLICIES
! 125:
! 126: @enumerate
! 127: @item
! 128: You may copy and distribute verbatim copies of GNU CC source code as
! 129: you receive it, in any medium, provided that you conspicuously and
! 130: appropriately publish on each copy a valid copyright notice
! 131: ``Copyright @copyright{} 1988 Free Software Foundation, Inc.'' (or
! 132: with whatever year is appropriate); keep intact the notices on all
! 133: files that refer to this License Agreement and to the absence of any
! 134: warranty; and give any other recipients of the GNU CC program a copy
! 135: of this License Agreement along with the program. You may charge a
! 136: distribution fee for the physical act of transferring a copy.
! 137:
! 138: @item
! 139: You may modify your copy or copies of GNU CC or any portion of it,
! 140: and copy and distribute such modifications under the terms of
! 141: Paragraph 1 above, provided that you also do the following:
! 142:
! 143: @itemize @bullet
! 144: @item
! 145: cause the modified files to carry prominent notices stating
! 146: that you changed the files and the date of any change; and
! 147:
! 148: @item
! 149: cause the whole of any work that you distribute or publish, that
! 150: in whole or in part contains or is a derivative of GNU CC or any
! 151: part thereof, to be licensed at no charge to all third parties on
! 152: terms identical to those contained in this License Agreement
! 153: (except that you may choose to grant more extensive warranty
! 154: protection to some or all third parties, at your option).
! 155:
! 156: @item
! 157: You may charge a distribution fee for the physical act of
! 158: transferring a copy, and you may at your option offer warranty
! 159: protection in exchange for a fee.
! 160: @end itemize
! 161:
! 162: Mere aggregation of another unrelated program with this program (or its
! 163: derivative) on a volume of a storage or distribution medium does not bring
! 164: the other program under the scope of these terms.
! 165:
! 166: @item
! 167: You may copy and distribute GNU CC (or a portion or derivative of it,
! 168: under Paragraph 2) in object code or executable form under the terms
! 169: of Paragraphs 1 and 2 above provided that you also do one of the
! 170: following:
! 171:
! 172: @itemize @bullet
! 173: @item
! 174: accompany it with the complete corresponding machine-readable
! 175: source code, which must be distributed under the terms of
! 176: Paragraphs 1 and 2 above; or,
! 177:
! 178: @item
! 179: accompany it with a written offer, valid for at least three
! 180: years, to give any third party free (except for a nominal
! 181: shipping charge) a complete machine-readable copy of the
! 182: corresponding source code, to be distributed under the terms of
! 183: Paragraphs 1 and 2 above; or,
! 184:
! 185: @item
! 186: accompany it with the information you received as to where the
! 187: corresponding source code may be obtained. (This alternative is
! 188: allowed only for noncommercial distribution and only if you
! 189: received the program in object code or executable form alone.)
! 190: @end itemize
! 191:
! 192: For an executable file, complete source code means all the source code
! 193: for all modules it contains; but, as a special exception, it need not
! 194: include source code for modules which are standard libraries that
! 195: accompany the operating system on which the executable file runs.
! 196:
! 197: @item
! 198: You may not copy, sublicense, distribute or transfer GNU CC except as
! 199: expressly provided under this License Agreement. Any attempt
! 200: otherwise to copy, sublicense, distribute or transfer GNU CC is void
! 201: and your rights to use the program under this License agreement shall
! 202: be automatically terminated. However, parties who have received
! 203: computer software programs from you with this License Agreement will
! 204: not have their licenses terminated so long as such parties remain in
! 205: full compliance.
! 206:
! 207: @item
! 208: If you wish to incorporate parts of GNU CC into other free programs
! 209: whose distribution conditions are different, write to the Free Software
! 210: Foundation at 675 Mass Ave, Cambridge, MA 02139. We have not yet worked
! 211: out a simple rule that can be stated here, but we will often permit this.
! 212: We will be guided by the two goals of preserving the free status of all
! 213: derivatives of our free software and of promoting the sharing and reuse of
! 214: software.
! 215: @end enumerate
! 216:
! 217: Your comments and suggestions about our licensing policies and our
! 218: software are welcome! Please contact the Free Software Foundation, Inc.,
! 219: 675 Mass Ave, Cambridge, MA 02139, or call (617) 876-3296.
! 220:
! 221: @unnumberedsec NO WARRANTY
! 222:
! 223: BECAUSE GNU CC IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO
! 224: WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT
! 225: WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC,
! 226: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU CC "AS IS" WITHOUT
! 227: WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
! 228: LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
! 229: A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
! 230: PERFORMANCE OF GNU CC IS WITH YOU. SHOULD GNU CC PROVE DEFECTIVE, YOU
! 231: ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
! 232:
! 233: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL RICHARD M.
! 234: STALLMAN, THE FREE SOFTWARE FOUNDATION, INC., AND/OR ANY OTHER PARTY
! 235: WHO MAY MODIFY AND REDISTRIBUTE GNU CC AS PERMITTED ABOVE, BE LIABLE TO
! 236: YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
! 237: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
! 238: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
! 239: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
! 240: FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) GNU CC, EVEN
! 241: IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR
! 242: ANY CLAIM BY ANY OTHER PARTY.
! 243:
! 244: @node Contributors, Options, Copying, Top
! 245: @unnumbered Contributors to GNU CC
! 246:
! 247: In addition to Richard Stallman, several people have written parts
! 248: of GNU CC.
! 249:
! 250: @itemize @bullet
! 251: @item
! 252: The idea of using RTL and some of the optimization ideas came from the
! 253: U. of Arizona Portable Optimizer, written by Jack Davidson and
! 254: Christopher Fraser. See ``Register Allocation and Exhaustive Peephole
! 255: Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
! 256: 857-866.
! 257:
! 258: @item
! 259: Paul Rubin wrote most of the preprocessor.
! 260:
! 261: @item
! 262: Leonard Tower wrote parts of the parser, RTL generator, RTL
! 263: definitions, and of the Vax machine description.
! 264:
! 265: @item
! 266: Ted Lemon wrote parts of the RTL reader and printer.
! 267:
! 268: @item
! 269: Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
! 270: the support for the SONY NEWS machine.
! 271:
! 272: @item
! 273: Charles LaBrec contributed the support for the Integrated Solutions
! 274: 68020 system.
! 275:
! 276: @item
! 277: Michael Tiemann of MCC wrote the description of the National
! 278: Semiconductor 32000 series cpu, with some contributions from Jan Stein
! 279: of the Chalmers Computer Club. Tiemann also wrote the code for inline
! 280: function integration.
! 281:
! 282: @item
! 283: Michael Kashtan of SRI adapted GNU CC to the Vomit-Making System.
! 284:
! 285: @item
! 286: Alex Crain provided changes for the 3b1.
! 287:
! 288: @item
! 289: Chris Hanson and another person who should remind me of his name
! 290: assisted in making GNU CC work on HP-UX for the 9000 series 300.
! 291: @end itemize
! 292:
! 293: @node Options, Installation, Contributors, Top
! 294: @chapter GNU CC Command Options
! 295:
! 296: The GNU C compiler uses a command syntax much like the Unix C compiler.
! 297: The @code{gcc} program accepts options and file names as operands.
! 298: Multiple single-letter options may @emph{not} be grouped: @samp{-dr} is
! 299: very different from @samp{-d -r}.
! 300:
! 301: When you invoke GNU CC, it normally does preprocessing, compilation,
! 302: assembly and linking. File names which end in @samp{.c} are taken as C
! 303: source to be preprocessed and compiled; compiler output files plus any
! 304: input files with names ending in @samp{.s} are assembled; then the
! 305: resulting object files, plus any other input files, are linked together to
! 306: produce an executable.
! 307:
! 308: Command options allow you to stop this process at an intermediate stage.
! 309: For example, the @samp{-c} option says not to run the linker. Then the
! 310: output consists of object files output by the assembler.
! 311:
! 312: Other command options are passed on to one stage. Some options control
! 313: the preprocessor and others the compiler itself. Yet other options
! 314: control the assembler and linker; these are not documented here because the
! 315: GNU assembler and linker are not yet released.
! 316:
! 317: Here are the options to control the overall compilation process, including
! 318: those that say whether to link, whether to assemble, and so on.
! 319:
! 320: @table @samp
! 321: @item -o @var{file}
! 322: Place output in file @var{file}. This applies regardless to whatever
! 323: sort of output is being produced, whether it be an executable file,
! 324: an object file, an assembler file or preprocessed C code.
! 325:
! 326: If @samp{-o} is not specified, the default is to put an excutable file
! 327: in @file{a.out}, the object file @file{@var{source}.c} in
! 328: @file{@var{source}.o}, an assembler file in @file{@var{source}.s}, and
! 329: preprocessed C on standard output.@refill
! 330:
! 331: @item -c
! 332: Compile or assemble the source files, but do not link. Produce object
! 333: files with names made by replacing @samp{.c} or @samp{.s} with
! 334: @samp{.o} at the end of the input file names. Do nothing at all for
! 335: object files specified as input.
! 336:
! 337: @item -S
! 338: Compile into assembler code but do not assemble. The assembler output
! 339: file name is made by replacing @samp{.c} with @samp{.s} at the end of
! 340: the input file name. Do nothing at all for assembler source files or
! 341: object files specified as input.
! 342:
! 343: @item -E
! 344: Run only the C preprocessor. Preprocess all the C source files
! 345: specified and output the results to standard output.
! 346:
! 347: @item -v
! 348: Compiler driver program prints the commands it executes as it runs
! 349: the preprocessor, compiler proper, assembler and linker. Some of
! 350: these are directed to print their own version numbers.
! 351:
! 352: @item -B@var{prefix}
! 353: Compiler driver program tries @var{prefix} as a prefix for each
! 354: program it tries to run. These programs are @file{cpp}, @file{cc1},
! 355: @file{as} and @file{ld}.
! 356:
! 357: For each subprogram to be run, the compiler driver first tries the
! 358: @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
! 359: was not specified, the driver tries two standard prefixes, which are
! 360: @file{/usr/lib/gcc-} and @file{/usr/local/lib/gcc-}. If neither of
! 361: those results in a file name that is found, the unmodified program
! 362: name is searched for using the directories specified in your
! 363: @samp{PATH} environment variable.
! 364:
! 365: The run-time support file @file{gnulib} is also searched for using
! 366: the @samp{-B} prefix, if needed. If it is not found there, the two
! 367: standard prefixes above are tried, and that is all. The file is left
! 368: out of the link if it is not found by those means. Most of the time,
! 369: on most machines, you can do without it.
! 370: @end table
! 371:
! 372: These options control the details of C compilation itself.
! 373:
! 374: @table @samp
! 375: @item -ansi
! 376: Support all ANSI standard C programs.
! 377:
! 378: This turns off certain features of GNU C that are incompatible with
! 379: ANSI C, such as the @code{asm}, @code{inline} and @code{typeof}
! 380: keywords, and predefined macros such as @code{unix} and @code{vax}
! 381: that identify the type of system you are using. It also enables the
! 382: undesirable and rarely used ANSI trigraph feature.
! 383:
! 384: The @samp{-ansi} option does not cause non-ANSI programs to be
! 385: rejected gratuitously. For that, @samp{-pedantic} is required in
! 386: addition to @samp{-ansi}.
! 387:
! 388: The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
! 389: option is used. Some header files may notice this macro and refrain
! 390: from declaring certain functions or defining certain macros that the
! 391: ANSI standard doesn't call for; this is to avoid interfering with
! 392: any programs that might use these names for other things.
! 393:
! 394: @item -traditional
! 395: Attempt to support some aspects of traditional C compilers.
! 396: Specifically:
! 397:
! 398: @itemize @bullet
! 399: @item
! 400: All @code{extern} declarations take effect globally even if they
! 401: are written inside of a function definition. This includes implicit
! 402: declarations of functions.
! 403:
! 404: @item
! 405: The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
! 406: and @code{volatile} are not recognized.@refill
! 407:
! 408: @item
! 409: Comparisons between pointers and integers are always allowed.
! 410:
! 411: @item
! 412: Integer types @code{unsigned short} and @code{unsigned char} promote
! 413: to @code{unsigned int}.
! 414:
! 415: @item
! 416: In the preprocessor, comments convert to nothing at all, rather than to
! 417: a space. This allows traditional token concatenation.
! 418:
! 419: @item
! 420: In the preprocessor, single and double quote characters are ignored
! 421: when scanning macro definitions, so that macro arguments can be replaced
! 422: even within a string or character constant. Quote characters are also
! 423: ignored when skipping text inside a failing conditional directive.
! 424: @end itemize
! 425:
! 426: @item -O
! 427: Optimize. Optimizing compilation takes somewhat more time, and a lot
! 428: more memory for a large function.
! 429:
! 430: Without @samp{-O}, the compiler's goal is to reduce the cost of
! 431: compilation and to make debugging produce the expected results.
! 432: Statements are independent: if you stop the program with a breakpoint
! 433: between statements, you can then assign a new value to any variable or
! 434: change the program counter to any other statement in the function and
! 435: get exactly the results you would expect from the source code.
! 436:
! 437: Without @samp{-O}, only variables declared @code{register} are
! 438: allocated in registers. The resulting compiled code is a little worse
! 439: than produced by PCC without @samp{-O}.
! 440:
! 441: With @samp{-O}, the compiler tries to reduce code size and execution
! 442: time.
! 443:
! 444: Some of the @samp{-f} options described below turn specific kinds of
! 445: optimization on or off.
! 446:
! 447: @item -g
! 448: Produce debugging information in DBX format.
! 449:
! 450: Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
! 451: @samp{-O}. The shortcuts taken by optimized code may occasionally
! 452: produce surprising results: some variables you declared may not exist
! 453: at all; flow of control may briefly move where you did not expect it;
! 454: some statements may not be executed because they compute constant
! 455: results or their values were already at hand; some statements may
! 456: execute in different places because they were moved out of loops.
! 457: Nevertheless it proves possible to debug optimized output. This makes
! 458: it reasonable to use the optimizer for programs that might have bugs.
! 459:
! 460: @item -gg
! 461: Produce debugging information in GDB's own format. This requires
! 462: the GNU assembler and linker in order to work.
! 463:
! 464: @item -w
! 465: Inhibit all warning messages.
! 466:
! 467: @item -W
! 468: Print extra warning messages for these events:
! 469:
! 470: @itemize @bullet
! 471: @item
! 472: An automatic variable is used without first being initialized.
! 473:
! 474: These warnings are possible only in optimizing compilation,
! 475: because they require data flow information that is computed only
! 476: when optimizing. They occur only for variables that are
! 477: candidates for register allocation. Therefore, they do not occur
! 478: for a variable that is declared @code{volatile}, or whose address
! 479: is taken, or whose size is other than 1, 2, 4 or 8 bytes. Also,
! 480: they do not occur for structures, unions or arrays, even when
! 481: they are in registers.
! 482:
! 483: Note that there may be no warning about a variable that is used
! 484: only to compute a value that itself is never used, because such
! 485: computations may be deleted by the flow analysis pass before the
! 486: warnings are printed.
! 487:
! 488: These warnings are made optional because GNU CC is not smart
! 489: enough to see all the reasons why the code might be correct
! 490: despite appearing to have an error. Here is one example of how
! 491: this can happen:
! 492:
! 493: @example
! 494: @{
! 495: int x;
! 496: switch (y)
! 497: @{
! 498: case 1: x = 1;
! 499: break;
! 500: case 2: x = 4;
! 501: break;
! 502: case 3: x = 5;
! 503: @}
! 504: foo (x);
! 505: @}
! 506: @end example
! 507:
! 508: @noindent
! 509: If the value of @code{y} is always 1, 2 or 3, then @code{x} is
! 510: always initialized, but GNU CC doesn't know this. Here is
! 511: another common case:
! 512:
! 513: @example
! 514: @{
! 515: int save_y;
! 516: if (change_y) save_y = y, y = new_y;
! 517: @dots{}
! 518: if (change_y) y = save_y;
! 519: @}
! 520: @end example
! 521:
! 522: @noindent
! 523: This has no bug because @code{x} is used only if it is set.
! 524:
! 525: @item
! 526: A nonvolatile automatic variable might be changed by a call to
! 527: @code{longjmp}. These warnings as well are possible only in
! 528: optimizing compilation.
! 529:
! 530: The compiler sees only the calls to @code{setjmp}. It cannot know
! 531: where @code{longjmp} will be called; in fact, a signal handler could
! 532: call it at any point in the code. As a result, you may get a warning
! 533: even when there is in fact no problem because @code{longjmp} cannot
! 534: in fact be called at the place which would cause a problem.
! 535:
! 536: @item
! 537: A function can return either with or without a value. (Falling
! 538: off the end of the function body is considered returning without
! 539: a value.) For example, this function would inspire such a
! 540: warning:
! 541:
! 542: @example
! 543: foo (a)
! 544: @{
! 545: if (a > 0)
! 546: return a;
! 547: @}
! 548: @end example
! 549:
! 550: Spurious warnings can occur because GNU CC does not realize that
! 551: certain functions (including @code{abort} and @code{longjmp})
! 552: will never return.
! 553: @end itemize
! 554:
! 555: In the future, other useful warnings may also be enabled by this
! 556: option.
! 557:
! 558: @item -Wimplicit
! 559: Warn whenever a function is implicitly declared.
! 560:
! 561: @item -Wreturn-type
! 562: Warn whenever a function is defined with a return-type that defaults
! 563: to @code{int}. Also warn about any @code{return} statement with no
! 564: return-value in a function whose return-type is not @code{void}.
! 565:
! 566: @item -Wcomment
! 567: Warn whenever a comment-start sequence @samp{/*} appears in a comment.
! 568:
! 569: @item -p
! 570: Generate extra code to write profile information suitable for the
! 571: analysis program @code{prof}.
! 572:
! 573: @item -pg
! 574: Generate extra code to write profile information suitable for the
! 575: analysis program @code{gprof}.
! 576:
! 577: @item -nostdinc
! 578: Don't search the standard directories for include files. Only the
! 579: directories you specify explicitly with the @samp{-I} option will be
! 580: searched.
! 581:
! 582: @item -nostdlib
! 583: Don't use the standard system libraries and startup files when
! 584: linking. Only the files you specify (plus @file{gnulib}) will be
! 585: passed to the linker.
! 586:
! 587: @item -m@var{machinespec}
! 588: Machine-dependent option specifying something about the type of target
! 589: machine. These options are defined by the macro
! 590: @code{TARGET_SWITCHES} in the machine description. The default for
! 591: the options is also defined by that macro, which enables you to change
! 592: the defaults.@refill
! 593:
! 594: These are the @samp{-m} options defined in the 68000 machine
! 595: description:
! 596:
! 597: @table @samp
! 598: @item -m68020
! 599: Generate output for a 68020 (rather than a 68000). This is the
! 600: default if you use the unmodified sources.
! 601:
! 602: @item -m68000
! 603: Generate output for a 68000 (rather than a 68020).
! 604:
! 605: @item -m68881
! 606: Generate output containing 68881 instructions for floating point.
! 607: This is the default if you use the unmodified sources.
! 608:
! 609: @item -msoft-float
! 610: Generate output containing library calls for floating point.
! 611:
! 612: @item -mshort
! 613: Consider type @code{int} to be 16 bits wide, like @code{short int}.
! 614:
! 615: @item -mnobitfield
! 616: Do not use the bit-field instructions. @samp{-m68000} implies
! 617: @samp{-mnobitfield}.
! 618:
! 619: @item -mbitfield
! 620: Do use the bit-field instructions. @samp{-m68020} implies
! 621: @samp{-mbitfield}. This is the default if you use the unmodified
! 622: sources.
! 623:
! 624: @item -mrtd
! 625: Use a different function-calling convention, in which functions
! 626: that take a fixed number of arguments return with the @code{rtd}
! 627: instruction, which pops their arguments while returning. This
! 628: saves one instruction in the caller since there is no need to pop
! 629: the arguments there.
! 630:
! 631: This calling convention is incompatible with the one normally
! 632: used on Unix, so you cannot use it if you need to call libraries
! 633: compiled with the Unix compiler.
! 634:
! 635: Also, you must provide function prototypes for all functions that
! 636: take variable numbers of arguments (including @code{printf});
! 637: otherwise incorrect code will be generated for calls to those
! 638: functions.
! 639:
! 640: In addition, seriously incorrect code will result if you call a
! 641: function with too many arguments. (Normally, extra arguments are
! 642: harmlessly ignored.)
! 643:
! 644: The @code{rtd} instruction is supported by the 68010 and 68020
! 645: processors, but not by the 68000.
! 646: @end table
! 647:
! 648: These @samp{-m} options are defined in the Vax machine description:
! 649:
! 650: @table @samp
! 651: @item -munix
! 652: Do not output certain jump instructions (@code{aobleq} and so on)
! 653: that the Unix assembler for the Vax cannot handle across long
! 654: ranges.
! 655:
! 656: @item -mgnu
! 657: Do output those jump instructions, on the assumption that you
! 658: will assemble with the GNU assembler.
! 659: @end table
! 660:
! 661: @item -f@var{flag}
! 662: Specify machine-independent flags. These are the flags:
! 663:
! 664: @table @samp
! 665: @item -ffloat-store
! 666: Do not store floating-point variables in registers. This
! 667: prevents undesirable excess precision on machines such as the
! 668: 68000 where the floating registers (of the 68881) keep more
! 669: precision than a @code{double} is supposed to have.
! 670:
! 671: For most programs, the excess precision does only good, but a few
! 672: programs rely on the precise definition of IEEE floating point.
! 673: Use @samp{-ffloat-store} for such programs.
! 674:
! 675: @item -fno-asm
! 676: Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
! 677: keyword. These words may then be used as identifiers.
! 678:
! 679: @item -fno-defer-pop
! 680: Always pop the arguments to each function call as soon as that
! 681: function returns. Normally the compiler (when optimizing) lets
! 682: arguments accumulate on the stack for several function calls and
! 683: pops them all at once.
! 684:
! 685: @item -fcombine-regs
! 686: Allow the combine pass to combine an instruction that copies one
! 687: register into another. This might or might not produce better
! 688: code when used in addition to @samp{-O}. I am interested in
! 689: hearing about the difference this makes.
! 690:
! 691: @item -fforce-mem
! 692: Force memory operands to be copied into registers before doing
! 693: arithmetic on them. This may produce better code by making all
! 694: memory references potential common subexpressions. When they are
! 695: not common subexpressions, instruction combination should
! 696: eliminate the separate register-load. I am interested in hearing
! 697: about the difference this makes.
! 698:
! 699: @item -fforce-addr
! 700: Force memory address constants to be copied into registers before
! 701: doing arithmetic on them. This may produce better code just as
! 702: @samp{-fforce-mem} may. I am interested in hearing about the
! 703: difference this makes.
! 704:
! 705: @item -fomit-frame-pointer
! 706: Don't keep the frame pointer in a register for functions that
! 707: don't need one. This avoids the instructions to save, set up and
! 708: restore frame pointers; it also makes an extra register available
! 709: in many functions. @strong{It also makes debugging impossible.}
! 710:
! 711: On some machines, such as the Vax, this flag has no effect,
! 712: because the standard calling sequence automatically handles the
! 713: frame pointer and nothing is saved by pretending it doesn't
! 714: exist. The machine-description macro
! 715: @code{FRAME_POINTER_REQUIRED} controls whether a target machine
! 716: supports this flag. @xref{Registers}.@refill
! 717:
! 718: @item -finline-functions
! 719: Integrate all simple functions into their callers. The compiler
! 720: heuristically decides which functions are simple enough to be
! 721: worth integrating in this way.
! 722:
! 723: If all calls to a given function are integrated, and the function
! 724: is declared @code{static}, then the function is normally not
! 725: output as assembler code in its own right.
! 726:
! 727: @item -fkeep-inline-functions
! 728: Even if all calls to a given function are integrated, and the
! 729: function is declared @code{static}, nevertheless output a
! 730: separate run-time callable version of the function.
! 731:
! 732: @item -fwritable-strings
! 733: Store string constants in the writable data segment and don't
! 734: uniquize them. This is for compatibility with old programs which
! 735: assume they can write into string constants. Writing into string
! 736: constants is a very bad idea; ``constants'' should be constant.
! 737:
! 738: @item -fno-function-cse
! 739: Do not put function addresses in registers; make each instruction
! 740: that calls a constant function contain the function's address
! 741: explicitly.
! 742:
! 743: This option results in less efficient code, but some strange
! 744: hacks that alter the assembler output may be confused by the
! 745: optimizations performed when this option is not used.
! 746:
! 747: @item -fvolatile
! 748: Consider all memory references through pointers to be volatile.
! 749:
! 750: @item -funsigned-char
! 751: Let the type @code{char} be the unsigned, like @code{unsigned
! 752: char}.
! 753:
! 754: Each kind of machine has a default for what @code{char} should
! 755: be. It is either like @code{unsigned char} by default or like
! 756: @code{signed char} by default. (Actually, at present, the
! 757: default is always signed.)
! 758:
! 759: The type @code{char} is always a distinct type from either
! 760: @code{signed char} or @code{unsigned char}, even though its
! 761: behavior is always just like one of those two.
! 762:
! 763: @item -fsigned-char
! 764: Let the type @code{char} be signed, like @code{signed char}.
! 765:
! 766: @item -ffixed-@var{reg}
! 767: Treat the register named @var{reg} as a fixed register; generated
! 768: code should never refer to it (except perhaps as a stack pointer,
! 769: frame pointer or in some other fixed role).
! 770:
! 771: @var{reg} must be the name of a register. The register names
! 772: accepted are machine-specific and are defined in the
! 773: @code{REGISTER_NAMES} macro in the machine description macro
! 774: file.
! 775:
! 776: @item -fcall-used-@var{reg}
! 777: Treat the register named @var{reg} as an allocatable register
! 778: that is clobbered by function calls. It may be allocated for
! 779: temporaries or variables that do not live across a call.
! 780: Functions compiled this way will not save and restore the
! 781: register @var{reg}.
! 782:
! 783: Use of this flag for a register that has a fixed pervasive role
! 784: in the machine's execution model, such as the stack pointer or
! 785: frame pointer, will produce disastrous results.
! 786:
! 787: @item -fcall-saved-@var{reg}
! 788: Treat the register named @var{reg} as an allocatable register
! 789: saved by functions. It may be allocated even for temporaries or
! 790: variables that live across a call. Functions compiled this way
! 791: will save and restore the register @var{reg} if they use it.
! 792:
! 793: Use of this flag for a register that has a fixed pervasive role
! 794: in the machine's execution model, such as the stack pointer or
! 795: frame pointer, will produce disastrous results.
! 796:
! 797: A different sort of disaster will result from the use of this
! 798: flag for a register in which function values are may be returned.
! 799: @end table
! 800:
! 801: @item -d@var{letters}
! 802: Says to make debugging dumps at times specified by @var{letters}.
! 803: Here are the possible letters:
! 804:
! 805: @table @samp
! 806: @item r
! 807: Dump after RTL generation.
! 808: @item j
! 809: Dump after first jump optimization.
! 810: @item J
! 811: Dump after last jump optimization.
! 812: @item s
! 813: Dump after CSE (including the jump optimization that sometimes
! 814: follows CSE).
! 815: @item L
! 816: Dump after loop optimization.
! 817: @item f
! 818: Dump after flow analysis.
! 819: @item c
! 820: Dump after instruction combination.
! 821: @item l
! 822: Dump after local register allocation.
! 823: @item g
! 824: Dump after global register allocation.
! 825: @item m
! 826: Print statistics on memory usage, at the end of the run.
! 827: @end table
! 828:
! 829: @item -pedantic
! 830: Issue all the warnings demanded by strict ANSI standard C; reject
! 831: all programs that use forbidden extensions.
! 832:
! 833: Valid ANSI standard C programs should compile properly with or without
! 834: this option (though a rare few will require @samp{-ansi}). However,
! 835: without this option, certain GNU extensions and traditional C features
! 836: are supported as well. With this option, they are rejected. There is
! 837: no reason to @i{use} this option; it exists only to satisfy pedants.
! 838: @end table
! 839:
! 840: These options control the C preprocessor, which is run on each C source
! 841: file before actual compilation. If you use the @samp{-E} option, nothing
! 842: is done except C preprocessing. Some of these options make sense only
! 843: together with @samp{-E} because they request preprocessor output that is
! 844: not suitable for actual compilation.
! 845:
! 846: @table @samp
! 847: @item -C
! 848: Tell the preprocessor not to discard comments. Used with the
! 849: @samp{-E} option.
! 850:
! 851: @item -I@var{dir}
! 852: Search directory @var{dir} for include files.
! 853:
! 854: @item -M
! 855: Tell the preprocessor to output a rule suitable for @code{make}
! 856: describing the dependencies of each source file. For each source
! 857: file, the preprocessor outputs one @code{make}-rule whose target is
! 858: the object file name for that source file and whose dependencies are
! 859: all the files @samp{#include}d in it. This rule may be a single line
! 860: or may be continued with @samp{\}-newline if it is long.
! 861:
! 862: @samp{-M} implies @samp{-E}.
! 863:
! 864: @item -MM
! 865: Like @samp{-M} but the output mentions only the user-header files
! 866: included with @samp{#include "@var{file}"}. System header files
! 867: included with @samp{#include <@var{file}>} are omitted.
! 868:
! 869: @samp{-MM} implies @samp{-E}.
! 870:
! 871: @item -D@var{macro}
! 872: Define macro @var{macro} with the empty string as its definition.
! 873:
! 874: @item -D@var{macro}=@var{defn}
! 875: Define macro @var{macro} as @var{defn}.
! 876:
! 877: @item -U@var{macro}
! 878: Undefine macro @var{macro}.
! 879:
! 880: @item -T
! 881: Support ANSI C trigraphs. You don't want to know about this
! 882: brain-damage. The @samp{-ansi} option also has this effect.
! 883: @end table
! 884:
! 885: @node Installation, Incompatibilities, Options, Top
! 886: @chapter Installing GNU CC
! 887:
! 888: Here is the procedure for installing GNU CC on a Unix system.
! 889: @menu
! 890: * VMS Install:: See below for installation on VMS.
! 891: @end menu
! 892: @iftex
! 893: (See below for VMS.)
! 894: @end iftex
! 895:
! 896: @enumerate
! 897: @item
! 898: Edit @file{Makefile}. If you are using HPUX, you must make a few
! 899: changes described in comments at the beginning of the file.
! 900:
! 901: @item
! 902: Choose configuration files.
! 903:
! 904: @itemize @bullet
! 905: @item
! 906: Make a symbolic link named @file{config.h} to the top-level
! 907: config file for the machine you are using (@pxref{Config}). This
! 908: file is responsible for defining information about the host
! 909: machine. It includes @file{tm.h}.
! 910:
! 911: The file's name should be @file{config-@var{machine}.h}. On VMS,
! 912: use @file{config-vms.h} rather than @file{config-vax.h}. On the
! 913: HP 9000 series 300, use @file{config-hp9k3.h} rather than
! 914: @file{config-m68k.h}.@refill
! 915:
! 916: If your system does not support symbolic links, you might want to
! 917: set up @file{config.h} to contain a @samp{#include} command which
! 918: refers to the appropriate file.
! 919:
! 920: @item
! 921: Make a symbolic link named @file{tm.h} to the machine-description
! 922: macro file for your machine (its name should be
! 923: @file{tm-@var{machine}.h}).
! 924:
! 925: For the 68000/68020, do not use @file{tm-m68k.h} directly;
! 926: instead use one of the files @file{tm-sun3.h}, @file{tm-sun2.h},
! 927: @file{tm-isi68.h}, @file{tm-news800.h} or @file{tm-3b1.h}. Each
! 928: of those files includes @file{tm-m68k.h} but sets up a few things
! 929: differently as appropriate to the specific model of
! 930: machine.@refill
! 931:
! 932: There are two files you can use for a 680x0 running HPUX:
! 933: @file{tm-hp9k320.h} and @file{tm-hp9k320g.h}. Use the former if
! 934: you are installing GNU CC alone. The latter is for another option
! 935: where GNU CC together with the GNU assembler, linker, debugger
! 936: and other utilities are used to replace all of HPUX that deals
! 937: with compilation. Not all of the pieces of GNU software needed for
! 938: this mode of operation are as yet in distribution; full instructions
! 939: will appear here in the future.@refill
! 940:
! 941: For the 32000, use @file{tm-sequent.h} if you are using a Sequent
! 942: machine; otherwise, use @file{tm-ns32k.h}.
! 943:
! 944: For the vax, use @file{tm-vax.h} on BSD Unix, @file{tm-ultrix.h}
! 945: on Ultrix, or @file{tm-vms.h} on VMS.@refill
! 946:
! 947: @item
! 948: Make a symbolic link named @file{md} to the machine description
! 949: pattern file (its name should be @file{@var{machine}.md}).
! 950:
! 951: @item
! 952: Make a symbolic link named @file{aux-output.c} to the output
! 953: subroutine file for your machine (its name should be
! 954: @file{output-@var{machine}.c}).
! 955: @end itemize
! 956:
! 957: @item
! 958: Make sure the Bison parser generator is installed. (This is
! 959: unnecessary if the Bison output file @file{parse.tab.c} is more recent
! 960: than @file{parse.y} and you do not plan to change @file{parse.y}.)
! 961:
! 962: Note that if you have an old version of Bison you may get an error
! 963: from the line with the @samp{%expect} directive. If so, simply remove
! 964: that line from @file{parse.y} and proceed.
! 965:
! 966: @item
! 967: If you are using a Sun, make sure the environment variable
! 968: @code{FLOAT_OPTION} is not set. If this option were set to
! 969: @code{f68881} when @file{gnulib} is compiled, the resulting code would
! 970: demand to be linked with a special startup file and will not link
! 971: properly without special pains.
! 972:
! 973: @item
! 974: Build the compiler. Just type @samp{make} in the compiler directory.
! 975:
! 976: @item
! 977: Move the first-stage object files and executables into a subdirectory
! 978: with this command:
! 979:
! 980: @example
! 981: make stage1
! 982: @end example
! 983:
! 984: The files are moved into a subdirectory named @file{stage1}.
! 985: Once installation is complete, you may wish to delete these files
! 986: with @code{rm -r stage1}.
! 987:
! 988: @item
! 989: Recompile the compiler with itself, with this command:
! 990:
! 991: @example
! 992: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/"
! 993: @end example
! 994:
! 995: On a 68000 or 68020 system lacking floating point hardware,
! 996: unless you have selected a @file{tm.h} file that expects by default
! 997: that there is no such hardware, do this instead:
! 998:
! 999: @example
! 1000: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -msoft-float"
! 1001: @end example
! 1002:
! 1003: @item
! 1004: If you wish to test the compiler by compiling it with itself one more
! 1005: time, do this:
! 1006:
! 1007: @example
! 1008: make stage2
! 1009: make CC=stage2/gcc CFLAGS="-g -O -Bstage2/"
! 1010: foreach file (*.o)
! 1011: cmp $file stage2/$file
! 1012: end
! 1013: @end example
! 1014:
! 1015: This will notify you if any of these stage 3 object files differs from
! 1016: those of stage 2. Any difference, no matter how innocuous, indicates
! 1017: that the stage 2 compiler has compiled GNU CC incorrectly, and is
! 1018: therefore a potentially serious bug which you should investigate and
! 1019: report (@pxref{Bugs}).
! 1020:
! 1021: @item
! 1022: Install the compiler driver, the compiler's passes and run-time support.
! 1023: You can use the following command:
! 1024:
! 1025: @example
! 1026: make install
! 1027: @end example
! 1028:
! 1029: @noindent
! 1030: This copies the files @file{cc1}, @file{cpp} and @file{gnulib} to
! 1031: files @file{gcc-cc1}, @file{gcc-cpp} and @file{gcc-gnulib} in
! 1032: directory @file{/usr/local/lib}, which is where the compiler driver
! 1033: program looks for them. It also copies the driver program @file{gcc}
! 1034: into the directory @file{/usr/local}, so that it appears in typical
! 1035: execution search paths.@refill
! 1036:
! 1037: @strong{Warning: the GNU CPP may not work for @file{ioctl.h},
! 1038: @file{ttychars.h} and other system header files unless the
! 1039: @samp{-traditional} option is used.} The bug is in the header files:
! 1040: at least on some machines, they rely on behavior that is incompatible
! 1041: with ANSI C. This behavior consists of substituting for macro
! 1042: argument names when they appear inside of character constants. The
! 1043: @samp{-traditional} option tells GNU CC to behave the way these
! 1044: headers expect.
! 1045:
! 1046: Because of this problem, you might prefer to configure GNU CC to use
! 1047: the system's own C preprocessor. To do so, make the file
! 1048: @file{/usr/local/lib/gcc-cpp} a link to @file{/lib/cpp}.
! 1049:
! 1050: Alternatively, on Sun systems and 4.3BSD at least, you can correct the
! 1051: include files by running the shell script @file{fixincludes}. This
! 1052: installs modified, corrected copies of the files @file{ioctl.h} and
! 1053: @file{ttychars.h} in a special directory where only GNU CC will
! 1054: normally look for them.
! 1055:
! 1056: The file @file{/usr/include/vaxuba/qvioctl.h} used in the X window
! 1057: system needs a similar correction.
! 1058: @end enumerate
! 1059:
! 1060: If you cannot install the compiler's passes and run-time support in
! 1061: @file{/usr/local/lib}, you can alternatively use the @samp{-B} option to
! 1062: specify a prefix by which they may be found. The compiler concatenates
! 1063: the prefix with the names @file{cpp}, @file{cc1} and @file{gnulib}.
! 1064: Thus, you can put the files in a directory @file{/usr/foo/gcc} and
! 1065: specify @samp{-B/usr/foo/gcc/} when you run GNU CC.
! 1066:
! 1067: @node VMS Install,, Installation, Installation
! 1068: @section Installing GNU CC on VMS
! 1069:
! 1070: The VMS version of GNU CC is normally distributed as a Backup
! 1071: saveset, so the only installation required is to copy the files.
! 1072: But here is how to rebuild GNU CC if you change it:
! 1073:
! 1074: @enumerate
! 1075: @item
! 1076: Copy the file @file{tm-vms.h} to @file{tm.h}, @file{config-vms.h} to
! 1077: @file{config.h}, @file{vax.md} to @file{md.} and @file{output-vax.c}
! 1078: to @file{aux-output.c}.@refill
! 1079:
! 1080: @item
! 1081: Type @samp{@@make} to do recompile everything.
! 1082: @end enumerate
! 1083:
! 1084: @node Incompatibilities, Extensions, Installation, Top
! 1085: @chapter Incompatibilities of GNU CC
! 1086:
! 1087: There are several noteworthy incompatibilities between GNU C and most
! 1088: existing (non-ANSI) versions of C.
! 1089:
! 1090: Ultimately our intention is that the @samp{-traditional} option will
! 1091: eliminate most of these incompatibilities by telling GNU C to behave
! 1092: like the other C compilers.
! 1093:
! 1094: @itemize @bullet
! 1095: @item
! 1096: GNU CC normally makes string constants read-only. If several
! 1097: identical-looking string constants are used, GNU CC stores only one
! 1098: copy of the string.
! 1099:
! 1100: One consequence is that you cannot call @code{mktemp} with a string
! 1101: constant argument. The function @code{mktemp} always alters the
! 1102: string its argument points to.
! 1103:
! 1104: Another consequence is that @code{sscanf} does not work on some
! 1105: systems when passed a string constant as its format control string.
! 1106: This is because @code{sscanf} incorrectly tries to write into the
! 1107: string constant.
! 1108:
! 1109: The best solution to these problems is to change the program to use
! 1110: @code{char}-array variables with initialization strings for these
! 1111: purposes instead of string constants. But if this is not possible,
! 1112: you can use the @samp{-fwritable-strings} flag, which directs GNU CC
! 1113: to handle string constants the same way most C compilers do.
! 1114:
! 1115: @item
! 1116: GNU CC does not substitute macro arguments when they appear inside of
! 1117: string constants. For example, the following macro in GNU CC
! 1118:
! 1119: @example
! 1120: #define foo(a) "a"
! 1121: @end example
! 1122:
! 1123: @noindent
! 1124: will produce output @samp{"a"} regardless of what the argument @var{a} is.
! 1125:
! 1126: The @samp{-traditional} option directs GNU CC to handle such cases
! 1127: (among others) in the old-fashioned (non-ANSI) fashion.
! 1128:
! 1129: @item
! 1130: When you use @code{setjmp} and @code{longjmp}, the only automatic
! 1131: variables guaranteed to remain valid are those declared
! 1132: @code{volatile}. This is a consequence of automatic register
! 1133: allocation. Consider this function:
! 1134:
! 1135: @example
! 1136: jmp_buf j;
! 1137:
! 1138: foo ()
! 1139: @{
! 1140: int a, b;
! 1141:
! 1142: a = fun1 ();
! 1143: if (setjmp (j))
! 1144: return a;
! 1145:
! 1146: a = fun2 ();
! 1147: /* @r{@code{longjmp (j)} may be occur in @code{fun3}.} */
! 1148: return a + fun3 ();
! 1149: @}
! 1150: @end example
! 1151:
! 1152: Here @code{a} may or may not be restored to its first value when the
! 1153: @code{longjmp} occurs. If @code{a} is allocated in a register, then
! 1154: its first value is restored; otherwise, it keeps the last value stored
! 1155: in it.
! 1156:
! 1157: If you use the @samp{-W} option with the @samp{-O} option, you will
! 1158: get a warning when GNU CC thinks such a problem might be possible.
! 1159:
! 1160: @item
! 1161: Declarations of external variables and functions within a block apply
! 1162: only to the block containing the declaration. In other words, they
! 1163: have the same scope as any other declaration in the same place.
! 1164:
! 1165: In some other C compilers, a @code{extern} declaration affects all the
! 1166: rest of the file even if it happens within a block.
! 1167:
! 1168: The @samp{-traditional} option directs GNU C to treat all @code{extern}
! 1169: declarations as global, like traditional compilers.
! 1170:
! 1171: @item
! 1172: In traditional C, you can combine @code{long}, etc., with a typedef name,
! 1173: as shown here:
! 1174:
! 1175: @example
! 1176: typedef int foo;
! 1177: typedef long foo bar;
! 1178: @end example
! 1179:
! 1180: In ANSI C, this is not allowed: @code{long} and other type modifiers
! 1181: require an explicit @code{int}. Because this criterion is expressed
! 1182: by Bison grammar rules rather than C code, the @samp{-traditional}
! 1183: flag cannot alter it.
! 1184:
! 1185: @item
! 1186: When compiling functions that return structures or unions, GNU CC
! 1187: output code uses a method different from that used on most versions of
! 1188: Unix. As a result, code compiled with GNU CC cannot call a
! 1189: structure-returning function compiled with PCC, and vice versa.
! 1190:
! 1191: The method used by GCC is as follows: a structure or union which is 1,
! 1192: 2, 4 or 8 bytes long is returned like a scalar. A structure or union
! 1193: with any other size is stored into an address supplied by the caller
! 1194: in a special, fixed register.
! 1195:
! 1196: PCC usually handles all sizes of structures and unions by returning
! 1197: the address of a block of static storage containing the value. This
! 1198: method is not used in GCC because it is slower and nonreentrant.
! 1199:
! 1200: On systems where PCC works this way, you may be able to make GCC-compiled
! 1201: code call such functions that were compiled with PCC by declaring them
! 1202: to return a pointer to the structure or union instead of the structure
! 1203: or union itself. For example, instead of this:
! 1204:
! 1205: @example
! 1206: struct foo nextfoo ();
! 1207: @end example
! 1208:
! 1209: @noindent
! 1210: write this:
! 1211:
! 1212: @example
! 1213: struct foo *nextfoo ();
! 1214: #define nextfoo *nextfoo
! 1215: @end example
! 1216:
! 1217: @noindent
! 1218: (Note that this assumes you are using the GNU preprocessor, so that
! 1219: the ANSI antirecursion rules for macro expansions are effective.)
! 1220: @end itemize
! 1221:
! 1222: @node Extensions, Bugs, Incompatibilities, Top
! 1223: @chapter GNU Extensions to the C Language
! 1224:
! 1225: GNU C provides several language features not found in ANSI standard C.
! 1226: (The @samp{-pedantic} option directs GNU CC to print a warning message if
! 1227: any of these features is used.) To test for the availability of these
! 1228: features in conditional compilation, check for a predefined macro
! 1229: @code{__GNUC__}, which is always defined under GNU CC.
! 1230:
! 1231: @menu
! 1232: * Statement Exprs:: Putting statements and declarations inside expressions.
! 1233: * Naming Types:: Giving a name to the type of some expression.
! 1234: * Typeof:: @code{typeof}: referring to the type of an expression.
! 1235: * Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues.
! 1236: * Conditionals:: Omitting the middle operand of a @samp{?:} expression.
! 1237: * Zero-Length:: Zero-length arrays.
! 1238: * Variable-Length:: Arrays whose length is computed at run time.
! 1239: * Subscripting:: Any array can be subscripted, even if not an lvalue.
! 1240: * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
! 1241: * Constructors:: Constructor expressions give structures, unions
! 1242: or arrays as values.
! 1243: * Dollar Signs:: Dollar sign is allowed in identifiers.
! 1244: * Alignment:: Inquiring about the alignment of a type or variable.
! 1245: * Inline:: Defining inline functions (as fast as macros).
! 1246: * Extended Asm:: Assembler instructions with C expressions as operands.
! 1247: (With them you can define ``built-in'' functions.)
! 1248: * Asm Labels:: Specifying the assembler name to use for a C symbol.
! 1249: @end menu
! 1250:
! 1251: @node Statement Exprs, Naming Types, Extensions, Extensions
! 1252: @section Statements and Declarations inside of Expressions
! 1253:
! 1254: A compound statement in parentheses may appear inside an expression in GNU
! 1255: C. This allows you to declare variables within an expression. For
! 1256: example:
! 1257:
! 1258: @example
! 1259: (@{ int y = foo (); int z;
! 1260: if (y > 0) z = y;
! 1261: else z = - y;
! 1262: z; @})
! 1263: @end example
! 1264:
! 1265: @noindent
! 1266: is a valid (though slightly more complex than necessary) expression
! 1267: for the absolute value of @code{foo ()}.
! 1268:
! 1269: This feature is especially useful in making macro definitions ``safe'' (so
! 1270: that they evaluate each operand exactly once). For example, the
! 1271: ``maximum'' function is commonly defined as a macro in standard C as
! 1272: follows:
! 1273:
! 1274: @example
! 1275: #define max(a,b) ((a) > (b) ? (a) : (b))
! 1276: @end example
! 1277:
! 1278: @noindent
! 1279: But this definition computes either @var{a} or @var{b} twice, with bad
! 1280: results if the operand has side effects. In GNU C, if you know the
! 1281: type of the operands (here let's assume @code{int}), you can define
! 1282: the macro safely as follows:
! 1283:
! 1284: @example
! 1285: #define maxint(a,b) \
! 1286: (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
! 1287: @end example
! 1288:
! 1289: Embedded statements are not allowed in constant expressions, such as
! 1290: the value of an enumeration constant, the width of a bit field, or
! 1291: the initial value of a static variable.
! 1292:
! 1293: If you don't know the type of the operand, you can still do this, but you
! 1294: must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming
! 1295: Types}).
! 1296:
! 1297: @node Naming Types, Typeof, Statement Exprs, Extensions
! 1298: @section Naming an Expression's Type
! 1299:
! 1300: You can give a name to the type of an expression using a @code{typedef}
! 1301: declaration with an initializer. Here is how to define @var{name} as a
! 1302: type name for the type of @var{exp}:
! 1303:
! 1304: @example
! 1305: typedef @var{name} = @var{exp};
! 1306: @end example
! 1307:
! 1308: This is useful in conjunction with the statements-within-expressions
! 1309: feature. Here is how the two together can be used to define a safe
! 1310: ``maximum'' macro that operates on any arithmetic type:
! 1311:
! 1312: @example
! 1313: #define max(a,b) \
! 1314: (@{typedef _ta = (a), _tb = (b); \
! 1315: _ta _a = (a); _tb _b = (b); \
! 1316: _a > _b ? _a : _b; @})
! 1317: @end example
! 1318:
! 1319: The reason for using names that start with underscores for the local
! 1320: variables is to avoid conflicts with variable names that occur within the
! 1321: expressions that are substituted for @code{a} and @code{b}. Eventually we
! 1322: hope to design a new form of declaration syntax that allows you to declare
! 1323: variables whose scopes start only after their initializers; this will be a
! 1324: more reliable way to prevent such conflicts.
! 1325:
! 1326: @node Typeof, Lvalues, Naming Types, Extensions
! 1327: @section Referring to a Type with @code{typeof}
! 1328:
! 1329: Another way to refer to the type of an expression is with @code{typeof}.
! 1330: The syntax of using of this keyword looks like @code{sizeof}, but the
! 1331: construct acts semantically like a type name defined with @code{typedef}.
! 1332:
! 1333: There are two ways of writing the argument to @code{typeof}: with an
! 1334: expression or with a type. Here is an example with an expression:
! 1335:
! 1336: @example
! 1337: typeof (x[0](1))
! 1338: @end example
! 1339:
! 1340: @noindent
! 1341: This assumes that @code{x} is an array of functions; the type described
! 1342: is that of the values of the functions.
! 1343:
! 1344: Here is an example with a typename as the argument:
! 1345:
! 1346: @example
! 1347: typeof (int *)
! 1348: @end example
! 1349:
! 1350: @noindent
! 1351: Here the type described is that of pointers to @code{int}.
! 1352:
! 1353: A @code{typeof}-construct can be used anywhere a typedef name could be
! 1354: used. For example, you can use it in a declaration, in a cast, or inside
! 1355: of @code{sizeof} or @code{typeof}.
! 1356:
! 1357: @itemize @bullet
! 1358: @item
! 1359: This declares @code{y} with the type of what @code{x} points to.
! 1360:
! 1361: @example
! 1362: typeof (*x) y;
! 1363: @end example
! 1364:
! 1365: @item
! 1366: This declares @code{y} as an array of such values.
! 1367:
! 1368: @example
! 1369: typeof (*x) y[4];
! 1370: @end example
! 1371:
! 1372: @item
! 1373: This declares @code{y} as an array of pointers to characters:
! 1374:
! 1375: @example
! 1376: typeof (typeof (char *)[4]) y;
! 1377: @end example
! 1378:
! 1379: @noindent
! 1380: It is equivalent to the following traditional C declaration:
! 1381:
! 1382: @example
! 1383: char *y[4];
! 1384: @end example
! 1385:
! 1386: To see the meaning of the declaration using @code{typeof}, and why it
! 1387: might be a useful way to write, let's rewrite it with these macros:
! 1388:
! 1389: @example
! 1390: #define pointer(T) typeof(T *)
! 1391: #define array(T, N) typeof(T [N])
! 1392: @end example
! 1393:
! 1394: @noindent
! 1395: Now the declaration can be rewritten this way:
! 1396:
! 1397: @example
! 1398: array (pointer (char), 4) y;
! 1399: @end example
! 1400:
! 1401: @noindent
! 1402: Thus, @samp{array (pointer (char), 4)} is the type of arrays of 4
! 1403: pointers to @code{char}.
! 1404: @end itemize
! 1405:
! 1406: @node Lvalues, Conditionals, Typeof, Extensions
! 1407: @section Generalized Lvalues
! 1408:
! 1409: Compound expressions, conditional expressions and casts are allowed as
! 1410: lvalues provided their operands are lvalues. This means that you can take
! 1411: their addresses or store values into them.
! 1412:
! 1413: For example, a compound expression can be assigned, provided the last
! 1414: expression in the sequence is an lvalue. These two expressions are
! 1415: equivalent:
! 1416:
! 1417: @example
! 1418: (a, b) += 5
! 1419: a, (b += 5)
! 1420: @end example
! 1421:
! 1422: Similarly, the address of the compound expression can be taken. These two
! 1423: expressions are equivalent:
! 1424:
! 1425: @example
! 1426: &(a, b)
! 1427: a, &b
! 1428: @end example
! 1429:
! 1430: A conditional expression is a valid lvalue if its type is not void and the
! 1431: true and false branches are both valid lvalues. For example, these two
! 1432: expressions are equivalent:
! 1433:
! 1434: @example
! 1435: (a ? b : c) = 5
! 1436: (a ? b = 5 : (c = 5))
! 1437: @end example
! 1438:
! 1439: A cast is a valid lvalue if its operand is valid. Taking the address of
! 1440: the cast is the same as taking the address without a cast, except for the
! 1441: type of the result. For example, these two expressions are equivalent (but
! 1442: the second may be valid when the type of @samp{a} does not permit a cast to
! 1443: @samp{int *}).
! 1444:
! 1445: @example
! 1446: &(int *)a
! 1447: (int **)&a
! 1448: @end example
! 1449:
! 1450: A simple assignment whose left-hand side is a cast works by converting the
! 1451: right-hand side first to the specified type, then to the type of the inner
! 1452: left-hand side expression. After this is stored, the value is converter
! 1453: back to the specified type to become the value of the assignment. Thus, if
! 1454: @samp{a} has type @samp{char *}, the following two expressions are
! 1455: equivalent:
! 1456:
! 1457: @example
! 1458: (int)a = 5
! 1459: (int)(a = (char *)5)
! 1460: @end example
! 1461:
! 1462: An assignment-with-arithmetic operation such as @samp{+=} applied to a cast
! 1463: performs the arithmetic using the type resulting from the cast, and then
! 1464: continues as in the previous case. Therefore, these two expressions are
! 1465: equivalent:
! 1466:
! 1467: @example
! 1468: (int)a += 5
! 1469: (int)(a = (char *) ((int)a + 5))
! 1470: @end example
! 1471:
! 1472: @node Conditionals, Zero-Length, Lvalues, Extensions
! 1473: @section Conditional Expressions with Omitted Middle-Operands
! 1474:
! 1475: The middle operand in a conditional expression may be omitted. Then
! 1476: if the first operand is nonzero, its value is the value of the conditional
! 1477: expression.
! 1478:
! 1479: Therefore, the expression
! 1480:
! 1481: @example
! 1482: x ? : y
! 1483: @end example
! 1484:
! 1485: @noindent
! 1486: has the value of @code{x} if that is nonzero; otherwise, the value of
! 1487: @code{y}.
! 1488:
! 1489: This example is perfectly equivalent to
! 1490:
! 1491: @example
! 1492: x ? x : y
! 1493: @end example
! 1494:
! 1495: @noindent
! 1496: In this simple case, the ability to omit the middle operand is not
! 1497: especially useful. When it becomes useful is when the first operand does,
! 1498: or may (if it is a macro argument), contain a side effect. Then repeating
! 1499: the operand in the middle would perform the side effect twice. Omitting
! 1500: the middle operand uses the value already computed without the undesirable
! 1501: effects of recomputing it.
! 1502:
! 1503: @node Zero-Length, Variable-Length, Conditionals, Extensions
! 1504: @section Arrays of Length Zero
! 1505:
! 1506: Zero-length arrays are allowed in GNU C. They are very useful as the last
! 1507: element of a structure which is really a header for a variable-length
! 1508: object:
! 1509:
! 1510: @example
! 1511: struct line @{
! 1512: int length;
! 1513: char contents[0];
! 1514: @};
! 1515:
! 1516: @{
! 1517: struct line *thisline
! 1518: = (struct line *) malloc (sizeof (struct line) + this_length);
! 1519: thisline->length = thislength;
! 1520: @}
! 1521: @end example
! 1522:
! 1523: In standard C, you would have to give @code{contents} a length of 1, which
! 1524: means either you waste space or complicate the argument to @code{malloc}.
! 1525:
! 1526: @node Variable-Length, Subscripting, Zero-Length, Extensions
! 1527: @section Arrays of Variable Length
! 1528:
! 1529: Variable-length automatic arrays are allowed in GNU C. These arrays are
! 1530: declared like any other automatic arrays, but with a length that is not a
! 1531: constant expression. The storage is allocated at that time and
! 1532: deallocated when the brace-level is exited. For example:
! 1533:
! 1534: @example
! 1535: FILE *concat_fopen (char *s1, char *s2, char *mode)
! 1536: @{
! 1537: char str[strlen (s1) + strlen (s2) + 1];
! 1538: strcpy (str, s1);
! 1539: strcat (str, s2);
! 1540: return fopen (str, mode);
! 1541: @}
! 1542: @end example
! 1543:
! 1544: You can also define structure types containing variable-length arrays, and
! 1545: use them even for arguments or function values, as shown here:
! 1546:
! 1547: @example
! 1548: int foo;
! 1549:
! 1550: struct entry
! 1551: @{
! 1552: char data[foo];
! 1553: @};
! 1554:
! 1555: struct entry
! 1556: tester (struct entry arg)
! 1557: @{
! 1558: struct entry new;
! 1559: int i;
! 1560: for (i = 0; i < foo; i++)
! 1561: new.data[i] = arg.data[i] + 1;
! 1562: return new;
! 1563: @}
! 1564: @end example
! 1565:
! 1566: @noindent
! 1567: (Eventually there will be a way to say that the size of the array is
! 1568: another member of the same structure.)
! 1569:
! 1570: The length of an array is computed on entry to the brace-level where the
! 1571: array is declared and is remembered for the scope of the array in case you
! 1572: access it with @code{sizeof}.
! 1573:
! 1574: Jumping or breaking out of the scope of the array name will also deallocate
! 1575: the storage. Jumping into the scope is not allowed; you will get an error
! 1576: message for it.
! 1577:
! 1578: You can use the function @code{alloca} to get an effect much like
! 1579: variable-length arrays. The function @code{alloca} is available in
! 1580: many other C implementations (but not in all). On the other hand,
! 1581: variable-length arrays are more elegant.
! 1582:
! 1583: There are other differences between these two methods. Space allocated
! 1584: with @code{alloca} exists until the containing @emph{function} returns.
! 1585: The space for a variable-length array is deallocated as soon as the array
! 1586: name's scope ends. (If you use both variable-length arrays and
! 1587: @code{alloca} in the same function, deallocation of a variable-length array
! 1588: will also deallocate anything more recently allocated with @code{alloca}.)
! 1589:
! 1590: @node Subscripting, Pointer Arith, Variable-Length, Extensions
! 1591: @section Non-Lvalue Arrays May Have Subscripts
! 1592:
! 1593: Subscripting is allowed on arrays that are not lvalues, even though the
! 1594: unary @samp{&} operator is not. For example, this is valid in GNU C though
! 1595: not valid in other C dialects:
! 1596:
! 1597: @example
! 1598: struct foo @{int a[4];@};
! 1599:
! 1600: struct foo f();
! 1601:
! 1602: bar (int index)
! 1603: @{
! 1604: return f().a[index];
! 1605: @}
! 1606: @end example
! 1607:
! 1608: @node Pointer Arith, Initializers, Subscripting, Extensions
! 1609: @section Arithmetic on @code{void}-Pointers and Function Pointers
! 1610:
! 1611: In GNU C, addition and subtraction operations are supported on pointers to
! 1612: @code{void} and on pointers to functions. This is done by treating the
! 1613: size of a @code{void} or of a function as 1.
! 1614:
! 1615: A consequence of this is that @code{sizeof} is also allowed on @code{void}
! 1616: and on function types, and returns 1.
! 1617:
! 1618: @node Initializers, Constructors, Pointer Arith, Extensions
! 1619: @section Non-Constant Initializers
! 1620:
! 1621: The elements of an aggregate initializer are not required to be constant
! 1622: expressions in GNU C. Here is an example of an initializer with run-time
! 1623: varying elements:
! 1624:
! 1625: @example
! 1626: foo (float f, float g)
! 1627: @{
! 1628: float beat_freqs[2] = @{ f-g, f+g @};
! 1629: @dots{}
! 1630: @}
! 1631: @end example
! 1632:
! 1633: @node Constructors, Dollar Signs, Initializers, Extensions
! 1634: @section Constructor Expressions
! 1635:
! 1636: GNU C supports constructor expressions. A constructor looks like a cast
! 1637: containing an initializer. Its value is an object of the type specified in
! 1638: the cast, containing the elements specified in the initializer. The type
! 1639: must be a structure, union or array type.
! 1640:
! 1641: Assume that @code{struct foo} and @code{structure} are declared as shown:
! 1642:
! 1643: @example
! 1644: struct foo @{int a; char b[2];@} structure;
! 1645: @end example
! 1646:
! 1647: @noindent
! 1648: Here is an example of constructing a @samp{struct foo} with a constructor:
! 1649:
! 1650: @example
! 1651: structure = ((struct foo) @{x + y, 'a', 0@});
! 1652: @end example
! 1653:
! 1654: @noindent
! 1655: This is equivalent to writing the following:
! 1656:
! 1657: @example
! 1658: @{
! 1659: struct foo temp = @{x + y, 'a', 0@};
! 1660: structure = temp;
! 1661: @}
! 1662: @end example
! 1663:
! 1664: You can also construct an array. If all the elements of the constructor
! 1665: are (made up of) simple constant expressions, suitable for use in
! 1666: initializers, then the constructor is an lvalue and can be coerced to a
! 1667: pointer to its first element, as shown here:
! 1668:
! 1669: @example
! 1670: char **foo = (char *[]) @{ "x", "y", "z" @};
! 1671: @end example
! 1672:
! 1673: Array constructors whose elements are not simple constants are not very
! 1674: useful, because the constructor is not an lvalue. There are only two valid
! 1675: ways to use it: to subscript it, or initialize an array variable with it.
! 1676: The former is probably slower than a @code{switch} statement, while the
! 1677: latter does the same thing an ordinary C initializer would do.
! 1678:
! 1679: @example
! 1680: output = ((int[]) @{ 2, x, 28 @}) [input];
! 1681: @end example
! 1682:
! 1683: @node Dollar Signs, Alignment, Constructors, Extensions
! 1684: @section Dollar Signs in Identifier Names
! 1685:
! 1686: In GNU C, you may use dollar signs in identifier names. This is because
! 1687: many traditional C implementations allow such identifiers.
! 1688:
! 1689: @node Alignment, Inline, Dollar Signs, Extensions
! 1690: @section Inquiring about the Alignment of a Type or Variable
! 1691:
! 1692: The keyword @code{__alignof} allows you to inquire about how an object
! 1693: is aligned, or the minimum alignment usually required by a type. Its
! 1694: syntax is just like @code{sizeof}.
! 1695:
! 1696: For example, if the target machine requires a @code{double} value to be
! 1697: aligned on an 8-byte boundary, then @code{__alignof (double)} is 8. This
! 1698: is true on many RISC machines. On more traditional machine designs,
! 1699: @code{__alignof (double)} is 4 or even 2.
! 1700:
! 1701: Some machines never actually require alignment; they allow reference to any
! 1702: data type even at an odd addresses. For these machines, @code{__alignof}
! 1703: reports the @emph{recommended} alignment of a type.
! 1704:
! 1705: When the operand of @code{__alignof} is an lvalue rather than a type, the
! 1706: value is the largest alignment that the lvalue is known to have. It may
! 1707: have this alignment as a result of its data type, or because it is part of
! 1708: a structure and inherits alignment from that structure. For example, after
! 1709: this declaration:
! 1710:
! 1711: @example
! 1712: struct foo @{ int x; char y; @} foo1;
! 1713: @end example
! 1714:
! 1715: @noindent
! 1716: the value of @code{__alignof (foo1.y)} is probably 2 or 4, the same as
! 1717: @code{__alignof (int)}, even though the data type of @code{foo1.y} does not
! 1718: itself demand any alignment.@refill
! 1719:
! 1720: @node Inline, Extended Asm, Alignment, Extensions
! 1721: @section An Inline Function is As Fast As a Macro
! 1722:
! 1723: By declaring a function @code{inline}, you can direct GNU CC to integrate
! 1724: that function's code into the code for its callers. This makes execution
! 1725: faster by eliminating the function-call overhead; in addition, if any of
! 1726: the actual argument values are constant, their known values may permit
! 1727: simplifications at compile time so that not all of the inline function's
! 1728: code needs to be included.
! 1729:
! 1730: To declare a function inline, use the @code{inline} keyword in its
! 1731: declaration, like this:
! 1732:
! 1733: @example
! 1734: inline int
! 1735: inc (int *a)
! 1736: @{
! 1737: (*a)++;
! 1738: @}
! 1739: @end example
! 1740:
! 1741: You can also make all ``simple enough'' functions inline with the
! 1742: option @samp{-finline-functions}. Note that certain usages in a
! 1743: function definition can make it unsuitable for inline substitution.
! 1744:
! 1745: When a function is both inline and @code{static}, if all calls to the
! 1746: function are integrated into the caller, then the function's own assembler
! 1747: code is never referenced. In this case, GNU CC does not actually output
! 1748: assembler code for the function, unless you specify the option
! 1749: @samp{-fkeep-inline-functions}. Some calls cannot be integrated for
! 1750: various reasons (in particular, calls that precede the function's
! 1751: definition cannot be integrated, and neither can recursive calls within the
! 1752: definition). If there is a nonintegrated call, then the function is
! 1753: compiled to assembler code as usual.
! 1754:
! 1755: When an inline function is not @code{static}, then the compiler must assume
! 1756: that there may be calls from other source files; since a global symbol can
! 1757: be defined only once in any program, the function must not be defined in
! 1758: the other source files, so the calls therein cannot be integrated.
! 1759: Therefore, a non-@code{static} inline function is always compiled on its
! 1760: own in the usual fashion.
! 1761:
! 1762: @node Extended Asm, Asm Labels, Inline, Extensions
! 1763: @section Assembler Instructions with C Expression Operands
! 1764:
! 1765: In an assembler instruction using @code{asm}, you can now specify the
! 1766: operands of the instruction using C expressions. This means no more
! 1767: guessing which registers or memory locations will contain the data you want
! 1768: to use.
! 1769:
! 1770: You must specify an assembler instruction template much like what appears
! 1771: in a machine description, plus an operand constraint string for each
! 1772: operand.
! 1773:
! 1774: For example, here is how to use the 68881's @code{fsinx} instruction:
! 1775:
! 1776: @example
! 1777: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
! 1778: @end example
! 1779:
! 1780: @noindent
! 1781: Here @code{angle} is the C expression for the input operand while
! 1782: @code{result} is that of the output operand. Each has @samp{"f"} as its
! 1783: operand constraint, saying that a floating-point register is required. The
! 1784: constraints use the same language used in the machine description
! 1785: (@pxref{Constraints}).
! 1786:
! 1787: Each operand is described by an operand-constraint string followed by the C
! 1788: expression in parentheses. A colon separates the assembler template from
! 1789: the first output operand, and another separates the last output operand
! 1790: from the first input, if any. Commas separate output operands and separate
! 1791: inputs. The number of operands is limited to the maximum number of
! 1792: operands in any instruction pattern in the machine description.
! 1793:
! 1794: Output operand expressions must be lvalues, and there must be at least one
! 1795: of them. The compiler can check this. The input operands need not be
! 1796: lvalues, and there need not be any. The compiler cannot check whether the
! 1797: operands have data types that are reasonable for the instruction being
! 1798: executed.
! 1799:
! 1800: The output operands must be write-only; GNU CC will assume that the values
! 1801: in these operands before the instruction are dead and need not be
! 1802: generated. For an operand that is read-write, you must logically split its
! 1803: function into two separate operands, one input operand and one write-only
! 1804: output operand. The connection between them is expressed by constraints
! 1805: which say they need to be in the same location when the instruction
! 1806: executes. You can use the same C expression for both operands, or
! 1807: different expressions. For example, here we write the (fictitious)
! 1808: @samp{combine} instruction with @code{bar} as its read-only source operand
! 1809: and @code{foo} as its read-write destination:
! 1810:
! 1811: @example
! 1812: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
! 1813: @end example
! 1814:
! 1815: @noindent
! 1816: The constraint @samp{"0"} for operand 1 says that it must occupy the same
! 1817: location as operand 0. Therefore it is not necessary to substitute operand
! 1818: 1 into the assembler code output.
! 1819:
! 1820: Usually the most convenient way to use these @code{asm} instructions is to
! 1821: encapsulate them in macros that look like functions. For example,
! 1822:
! 1823: @example
! 1824: #define sin(x) \
! 1825: (@{ double __value, __arg = (x); \
! 1826: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
! 1827: __value; @})
! 1828: @end example
! 1829:
! 1830: @noindent
! 1831: Here the variable @code{__arg} is used to make sure that the instruction
! 1832: operates on a proper @code{double} value, and to accept only those
! 1833: arguments @code{x} which can convert automatically to a @code{double}.
! 1834:
! 1835: Another way to make sure the instruction operates on the correct data type
! 1836: is to use a cast in the @code{asm}. This is different from using a
! 1837: variable @code{__arg} in that it converts more different types. For
! 1838: example, if the desired type were @code{int}, casting the argument to
! 1839: @code{int} would accept a pointer with no complaint, while assigning the
! 1840: argument to an @code{int} variable named @code{__arg} would warn about
! 1841: using a pointer unless the caller explicitly casts it.
! 1842:
! 1843: GNU CC assumes for optimization purposes that these instructions have no
! 1844: side effects except to change the output operands. This does not mean that
! 1845: instructions with a side effect cannot be used, but you must be careful,
! 1846: because the compiler may eliminate them if the output operands aren't used,
! 1847: or move them out of loops, or replace two with one if they constitute a
! 1848: common subexpression. Also, if your instruction does have a side effect on
! 1849: a variable that otherwise appears not to change, the old value of the
! 1850: variable may be reused later if it happens to be found in a register.
! 1851:
! 1852: You can prevent an @code{asm} instruction from being deleted, moved or
! 1853: combined by writing the keyword @code{volatile} after the @code{asm}. For
! 1854: example:
1.1 root 1855:
1.1.1.2 ! root 1856: @example
! 1857: #define set_priority(x) \
! 1858: asm volatile ("set_priority %1": \
! 1859: "=m" (*(char *)0): "g" (x))
! 1860: @end example
1.1 root 1861:
1.1.1.2 ! root 1862: @noindent
! 1863: Note that we have supplied an output operand which is not actually used in
! 1864: the instruction. This is because @code{asm} requires at least one output
! 1865: operand. This requirement exists for internal implementation reasons and
! 1866: we might be able to relax it in the future.
! 1867:
! 1868: In this case output operand has the additional benefit effect of giving the
! 1869: appearance of writing in memory. As a result, GNU CC will assume that data
! 1870: previously fetched from memory must be fetched again if needed again later.
! 1871: This may be desirable if you have not employed the @code{volatile} keyword
! 1872: on all the variable declarations that ought to have it.
! 1873:
! 1874: @node Asm Labels,,Extended Asm, Extensions
! 1875: @section Controlling Names Used in Assembler Code
! 1876:
! 1877: You can specify the name to be used in the assembler code for a C function
! 1878: or variable by writing the @code{asm} keyword after the declarator as
! 1879: follows:
1.1 root 1880:
1.1.1.2 ! root 1881: @example
! 1882: int foo asm ("myfoo") = 2;
! 1883: @end example
1.1 root 1884:
1.1.1.2 ! root 1885: @noindent
! 1886: This specifies that the name to be used for the variable @code{foo} in
! 1887: the assembler code should be @samp{myfoo} rather than the usual
! 1888: @samp{_foo}.
! 1889:
! 1890: On systems where an underscore is normally prepended to the name of a C
! 1891: function or variable, this feature allows you to define names for the
! 1892: linker that do not start with an underscore.
! 1893:
! 1894: You cannot use @code{asm} in this way in a function @emph{definition}; but
! 1895: you can get the same effect by writing a declaration for the function
! 1896: before its definition and putting @code{asm} there, like this:
1.1 root 1897:
1.1.1.2 ! root 1898: @example
! 1899: extern func () asm ("FUNC");
1.1 root 1900:
1.1.1.2 ! root 1901: func (x, y)
! 1902: int x, y;
! 1903: @dots{}
! 1904: @end example
1.1 root 1905:
1.1.1.2 ! root 1906: It is up to you to make sure that the assembler names you choose do not
! 1907: conflict with any other assembler symbols. Also, you must not use a
! 1908: register name; that would produce completely invalid assembler code. GNU
! 1909: CC does not as yet have the ability to store static variables in registers.
! 1910: Perhaps that will be added.
! 1911:
! 1912: @node Bugs, Portability, Extensions, Top
! 1913: @chapter Reporting Bugs
! 1914:
! 1915: Your bug reports play an essential role in making GNU CC reliable.
! 1916:
! 1917: Reporting a bug may help you by bringing a solution to your problem, or it
! 1918: may not. But in any case the important function of a bug report is to help
! 1919: the entire community by making the next version of GNU CC work better. Bug
! 1920: reports are your contribution to the maintenance of GNU CC.
1.1 root 1921:
1.1.1.2 ! root 1922: In order for a bug report to serve its purpose, you must include the
! 1923: information that makes for fixing the bug.
1.1 root 1924:
1.1.1.2 ! root 1925: @menu
! 1926: * Criteria: Bug Criteria. Have you really found a bug?
! 1927: * Reporting: Bug Reporting. How to report a bug effectively.
! 1928: @end menu
1.1 root 1929:
1.1.1.2 ! root 1930: @node Bug Criteria, Bug Reporting, Bugs, Bugs
! 1931: @section Have You Found a Bug?
! 1932:
! 1933: If you are not sure whether you have found a bug, here are some guidelines:
1.1 root 1934:
1935: @itemize @bullet
1936: @item
1.1.1.2 ! root 1937: If the compiler gets a fatal signal, for any input whatever, that is a
! 1938: compiler bug. Reliable compilers never crash.
1.1 root 1939:
1940: @item
1.1.1.2 ! root 1941: If the compiler produces invalid assembly code, for any input whatever
! 1942: (except an @code{asm} statement), that is a compiler bug, unless the
! 1943: compiler reports errors (not just warnings) which would ordinarily
! 1944: prevent the assembler from being run.
1.1 root 1945:
1946: @item
1.1.1.2 ! root 1947: If the compiler produces valid assembly code that does not correctly
! 1948: execute the input source code, that is a compiler bug.
1.1 root 1949:
1.1.1.2 ! root 1950: However, you must double-check to make sure, because you may have run
! 1951: into an incompatibility between GNU C and traditional C
! 1952: (@pxref{Incompatibilities}). These incompatibilities might be considered
! 1953: bugs, but they are inescapable consequences of features valuable
! 1954: features.
1.1 root 1955:
1.1.1.2 ! root 1956: Or you may have a program whose behavior is undefined, which happened
! 1957: by chance to give the desired results with another C compiler.
1.1 root 1958:
1.1.1.2 ! root 1959: For example, in many nonoptimizing compilers, you can write @samp{x;}
! 1960: at the end of a function instead of @samp{return x;}, with the same
! 1961: results. But the value of the function is undefined if @samp{return}
! 1962: is omitted; it is not a bug when GNU CC produces different results.
1.1 root 1963:
1.1.1.2 ! root 1964: Problems often result from expressions with two increment operators,
! 1965: as in @samp{f (*p++, *p++)}. Your previous compiler might have
! 1966: interpreted that expression the way you intended; GNU CC might
! 1967: interpret it another way; neither compiler is wrong.
1.1 root 1968:
1.1.1.2 ! root 1969: After you have localized the error to a single source line, it should
! 1970: be easy to check for these things. If your program is correct and
! 1971: well defined, you have found a compiler bug.
1.1 root 1972:
1.1.1.2 ! root 1973: @item
! 1974: If the compiler produces an error message for valid input, that is a
! 1975: compiler bug.
1.1 root 1976:
1.1.1.2 ! root 1977: Note that the following is not valid input, and the error message for
! 1978: it is not a bug:
1.1 root 1979:
1.1.1.2 ! root 1980: @example
! 1981: int foo (char);
1.1 root 1982:
1.1.1.2 ! root 1983: int
! 1984: foo (x)
! 1985: char x;
! 1986: @{ @dots{} @}
! 1987: @end example
1.1 root 1988:
1.1.1.2 ! root 1989: @noindent
! 1990: The prototype says to pass a @code{char}, while the definition says to
! 1991: pass an @code{int} and treat the value as a @code{char}. This is what
! 1992: the ANSI standard says, and it makes sense.
1.1 root 1993:
1.1.1.2 ! root 1994: @item
! 1995: If the compiler does not produce an error message for invalid input,
! 1996: that is a compiler bug. However, you should note that your idea of
! 1997: ``invalid input'' might be my idea of ``an extension'' or ``support
! 1998: for traditional practice''.
1.1 root 1999:
1.1.1.2 ! root 2000: @item
! 2001: If you are an experienced user of C compilers, your suggestions
! 2002: for improvement of GNU CC are welcome in any case.
! 2003: @end itemize
1.1 root 2004:
1.1.1.2 ! root 2005: @node Bug Reporting,, Bug Criteria, Bugs
! 2006: @section How to Report Bugs
1.1 root 2007:
1.1.1.2 ! root 2008: Send bug reports for GNU C to one of these addresses:
1.1 root 2009:
1.1.1.2 ! root 2010: @example
! 2011: bug-gcc@@prep.ai.mit.edu
! 2012: @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gcc
! 2013: @end example
1.1 root 2014:
1.1.1.2 ! root 2015: As a last resort, snail them to:
1.1 root 2016:
1.1.1.2 ! root 2017: @example
! 2018: GNU Compiler Bugs
! 2019: 545 Tech Sq
! 2020: Cambridge, MA 02139
! 2021: @end example
1.1 root 2022:
1.1.1.2 ! root 2023: The fundamental principle of reporting bugs usefully is this:
! 2024: @strong{report all the facts}. If you are not sure whether to mention a
! 2025: fact or leave it out, mention it!
! 2026:
! 2027: Often people omit facts because they think they know what causes the
! 2028: problem and they conclude that some details don't matter. Thus, you might
! 2029: assume that the name of the variable you use in an example does not matter.
! 2030: Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
! 2031: stray memory reference which happens to fetch from the location where that
! 2032: name is stored in memory; perhaps, if the name were different, the contents
! 2033: of that location would fool the compiler into doing the right thing despite
! 2034: the bug. Play it safe and give an exact example.
1.1 root 2035:
1.1.1.2 ! root 2036: If you want to enable me to fix the bug, you should include all these
! 2037: things:
1.1 root 2038:
1.1.1.2 ! root 2039: @itemize @bullet
! 2040: @item
! 2041: The version of GNU CC. You can get this by running it with the
! 2042: @samp{-v} option.
1.1 root 2043:
1.1.1.2 ! root 2044: Without this, I won't know whether there is any point in looking for
! 2045: the bug in the current version of GNU CC.
1.1 root 2046:
1.1.1.2 ! root 2047: @item
! 2048: A complete input file that will reproduce the bug. If the bug is in
! 2049: the C preprocessor, send me a source file and any header files that it
! 2050: requires. If the bug is in the compiler proper (@file{cc1}), run your
! 2051: source file through the C preprocessor by doing @samp{gcc -E
! 2052: @var{sourcefile} > @var{outfile}}, then include the contents of
! 2053: @var{outfile} in the bug report. (Any @samp{-I}, @samp{-D} or
! 2054: @samp{-U} options that you used in actual compilation should also be
! 2055: used when doing this.)
1.1 root 2056:
1.1.1.2 ! root 2057: A single statement is not enough of an example. In order to compile
! 2058: it, it must be embedded in a function definition; and the bug might
! 2059: depend on the details of how this is done.
! 2060:
! 2061: Without a real example I can compile, all I can do about your bug
! 2062: report is wish you luck. It would be futile to try to guess how to
! 2063: provoke the bug. For example, bugs in register allocation and
! 2064: reloading frequently depend on every little detail of the function
! 2065: they happen in.
1.1 root 2066:
2067: @item
1.1.1.2 ! root 2068: The command arguments you gave GNU CC to compile that example and
! 2069: observe the bug. For example, did you use @samp{-O}? To guarantee
! 2070: you won't omit something important, list them all.
! 2071:
! 2072: If I were to try to guess the arguments, I would probably guess wrong
! 2073: and then I would not encounter the bug.
1.1 root 2074:
2075: @item
1.1.1.2 ! root 2076: The names of the files that you used for @file{tm.h} and @file{md}
! 2077: when you installed the compiler.
1.1 root 2078:
2079: @item
1.1.1.2 ! root 2080: The type of machine you are using, and the operating system name and
! 2081: version number.
1.1 root 2082:
2083: @item
1.1.1.2 ! root 2084: A description of what behavior you observe that you believe is
! 2085: incorrect. For example, ``It gets a fatal signal,'' or, ``There is an
! 2086: incorrect assembler instruction in the output.''
! 2087:
! 2088: Of course, if the bug is that the compiler gets a fatal signal, then I
! 2089: will certainly notice it. But if the bug is incorrect output, I might
! 2090: not notice unless it is glaringly wrong. I won't study all the
! 2091: assembler code from a 50-line C program just on the off chance that it
! 2092: might be wrong.
! 2093:
! 2094: Even if the problem you experience is a fatal signal, you should still
! 2095: say so explicitly. Suppose something strange is going on, such as,
! 2096: your copy of the compiler is out of synch, or you have encountered a
! 2097: bug in the C library on your system. (This has happened!) Your copy
! 2098: might crash and mine would not. If you @i{told} me to expect a crash,
! 2099: then when mine fails to crash, I would know that the bug was not
! 2100: happening for me. If you had not told me to expect a crash, then I
! 2101: would not be able to draw any conclusion from my observations.
! 2102:
! 2103: In cases where GNU CC generates incorrect code, if you send me a small
! 2104: complete sample program I will find the error myself by running the
! 2105: program under a debugger. If you send me a large example or a part of
! 2106: a larger program, I cannot do this; you must debug the compiled
! 2107: program and narrow the problem down to one source line. Tell me which
! 2108: source line it is, and what you believe is incorrect about the code
! 2109: generated for that line.
1.1 root 2110:
2111: @item
1.1.1.2 ! root 2112: If you send me examples of output from GNU CC, please use @samp{-g}
! 2113: when you make them. The debugging information includes source line
! 2114: numbers which are essential for correlating the output with the input.
1.1 root 2115: @end itemize
2116:
1.1.1.2 ! root 2117: Here are some things that are not necessary:
1.1 root 2118:
1.1.1.2 ! root 2119: @itemize @bullet
1.1 root 2120: @item
1.1.1.2 ! root 2121: A description of the envelope of the bug.
1.1 root 2122:
1.1.1.2 ! root 2123: Often people who encounter a bug spend a lot of time investigating
! 2124: which changes to the input file will make the bug go away and which
! 2125: changes will not affect it.
1.1 root 2126:
1.1.1.2 ! root 2127: This is often time consuming and not very useful, because the way I
! 2128: will find the bug is by running a single example under the debugger
! 2129: with breakpoints, not by pure deduction from a series of examples.
1.1 root 2130:
1.1.1.2 ! root 2131: Of course, it can't hurt if you can find a simpler example that
! 2132: triggers the same bug. Errors in the output will be easier to spot,
! 2133: running under the debugger will take less time, etc. An easy way
! 2134: to simplify an example is to delete all the function definitions
! 2135: except the one where the bug occurs. Those earlier in the file
! 2136: may be replaced by external declarations.
! 2137:
! 2138: However, simplification is not necessary; if you don't want to do
! 2139: this, report the bug anyway.
1.1 root 2140:
2141: @item
1.1.1.2 ! root 2142: A patch for the bug.
1.1 root 2143:
1.1.1.2 ! root 2144: A patch for the bug does help me if it is a good one. But don't omit
! 2145: the necessary information, such as the test case, because I might see
! 2146: problems with your patch and decide to fix the problem another way.
1.1 root 2147:
1.1.1.2 ! root 2148: Sometimes with a program as complicated as GNU CC it is very hard to
! 2149: construct an example that will make the program go through a certain
! 2150: point in the code. If you don't send me the example, I won't be able
! 2151: to verify that the bug is fixed.
1.1 root 2152:
2153: @item
1.1.1.2 ! root 2154: A guess about what the bug is or what it depends on.
! 2155:
! 2156: Such guesses are usually wrong. Even I can't guess right about such
! 2157: things without using the debugger to find the facts. They also don't
! 2158: serve a useful purpose.
! 2159: @end itemize
1.1 root 2160:
1.1.1.2 ! root 2161: @node Portability, Interface, Bugs, Top
1.1 root 2162: @chapter GNU CC and Portability
2163:
2164: The main goal of GNU CC was to make a good, fast compiler for machines in
2165: the class that the GNU system aims to run on: 32-bit machines that address
2166: 8-bit bytes and have several general registers. Elegance, theoretical
2167: power and simplicity are only secondary.
2168:
2169: GNU CC gets most of the information about the target machine from a machine
2170: description which gives an algebraic formula for each of the machine's
2171: instructions. This is a very clean way to describe the target. But when
2172: the compiler needs information that is difficult to express in this
2173: fashion, I have not hesitated to define an ad-hoc parameter to the machine
2174: description. The purpose of portability is to reduce the total work needed
2175: on the compiler; it was not of interest for its own sake.
2176:
2177: GNU CC does not contain machine dependent code, but it does contain code
2178: that depends on machine parameters such as endianness (whether the most
2179: significant byte has the highest or lowest address of the bytes in a word)
2180: and the availability of autoincrement addressing. In the RTL-generation
2181: pass, it is often necessary to have multiple strategies for generating code
2182: for a particular kind of syntax tree, strategies that are usable for different
2183: combinations of parameters. Often I have not tried to address all possible
2184: cases, but only the common ones or only the ones that I have encountered.
2185: As a result, a new target may require additional strategies. You will know
2186: if this happens because the compiler will call @code{abort}. Fortunately,
1.1.1.2 ! root 2187: the new strategies can be added in a machine-independent fashion, and will
! 2188: affect only the target machines that need them.
! 2189:
! 2190: @node Interface, Passes, Portability, Top
! 2191: @chapter Interfacing to GNU CC Output
! 2192:
! 2193: GNU CC is normally configured to use the same function calling convention
! 2194: normally in use on the target system. This is done with the
! 2195: machine-description macros described (@pxref{Machine Macros}).
! 2196:
! 2197: However, returning of structure and union values is done differently.
! 2198: As a result, functions compiled with PCC returning such types cannot
! 2199: be called from code compiled with GNU CC, and vice versa. This usually
! 2200: does not cause trouble because the Unix library routines don't return
! 2201: structures and unions.
! 2202:
! 2203: Structures and unions that are 1, 2, 4 or 8 bytes long are returned in the
! 2204: same registers used for @code{int} or @code{double} return values. (GNU CC
! 2205: typically allocates variables of such types in registers also.) Structures
! 2206: and unions of other sizes are returned by storing them into an address
! 2207: passed by the caller in a register. This method is faster than the one
! 2208: normally used by PCC and is also reentrant. The register used for passing
! 2209: the address is specified by the machine-description macro
! 2210: @code{STRUCT_VALUE_REGNUM}.
! 2211:
! 2212: GNU CC always passes arguments on the stack. At some point it will be
! 2213: extended to pass arguments in registers, for machines which use that as
! 2214: the standard calling convention. This will make it possible to use such
! 2215: a convention on other machines as well. However, that would render it
! 2216: completely incompatible with PCC. We will probably do this once we
! 2217: have a complete GNU system so we can compile the libraries with GNU CC.
! 2218:
! 2219: If you use @code{longjmp}, beware of automatic variables. ANSI C says that
! 2220: automatic variables that are not declared @code{volatile} have undefined
! 2221: values after a @code{longjmp}. And this is all GNU CC promises to do,
! 2222: because it is very difficult to restore register variables correctly, and
! 2223: one of GNU CC's features is that it can put variables in registers without
! 2224: your asking it to.
! 2225:
! 2226: If you want a variable to be unaltered by @code{longjmp}, and you don't
! 2227: want to write @code{volatile} because old C compilers don't accept it,
! 2228: just take the address of the variable. If a variable's address is ever
! 2229: taken, even if just to compute it and ignore it, then the variable cannot
! 2230: go in a register:
! 2231:
! 2232: @example
! 2233: @{
! 2234: int careful;
! 2235: &careful;
! 2236: @dots{}
! 2237: @}
! 2238: @end example
1.1 root 2239:
1.1.1.2 ! root 2240: Code compiled with GNU CC may call certain library routines. The routines
! 2241: needed on the Vax and 68000 are in the file @file{gnulib.c}. You must
! 2242: compile this file with the standard C compiler, not with GNU CC, and then
! 2243: link it with each program you compile with GNU CC. (In actuality, many
! 2244: programs will not need it.) The usual function call interface is used
! 2245: for calling the library routines. Some standard parts of the C library,
! 2246: such as @code{bcopy}, are also called automatically.
! 2247:
! 2248: @node Passes, RTL, Interface, Top
1.1 root 2249: @chapter Passes and Files of the Compiler
2250:
2251: The overall control structure of the compiler is in @file{toplev.c}. This
2252: file is responsible for initialization, decoding arguments, opening and
2253: closing files, and sequencing the passes.
2254:
1.1.1.2 ! root 2255: The parsing pass is invoked only once, to parse the entire input. The RTL
! 2256: intermediate code for a function is generated as the function is parsed, a
! 2257: statement at a time. Each statement is read in as a syntax tree and then
! 2258: converted to RTL; then the storage for the tree for the statement is
! 2259: reclaimed. Storage for types (and the expressions for their sizes),
! 2260: declarations, and a representation of the binding contours and how they nest,
! 2261: remains until the function is finished being compiled; these are all needed
! 2262: to output the debugging information.
! 2263:
! 2264: Each time the parsing pass reads a complete function definition or
! 2265: top-level declaration, it calls the function
! 2266: @code{rest_of_compilation} or @code{rest_of_decl_compilation} in
! 2267: @file{toplev.c}, which are responsible for all further processing
! 2268: necessary, ending with output of the assembler language. All other
! 2269: compiler passes run, in sequence, within @code{rest_of_compilation}.
! 2270: When that function returns from compiling a function definition, the
! 2271: storage used for that function definition's compilation is entirely
! 2272: freed, unless it is an inline function (@pxref{Inline}).
1.1 root 2273:
2274: Here is a list of all the passes of the compiler and their source files.
2275: Also included is a description of where debugging dumps can be requested
1.1.1.2 ! root 2276: with @samp{-d} options.
1.1 root 2277:
2278: @itemize @bullet
2279: @item
2280: Parsing. This pass reads the entire text of a function definition,
1.1.1.2 ! root 2281: constructing partial syntax trees. This and RTL generation are no longer
! 2282: truly separate passes (formerly they were), but it is easier to think
! 2283: of them as separate.
! 2284:
! 2285: The tree representation does not entirely follow C syntax, because it is
! 2286: intended to support other languages as well.
1.1 root 2287:
1.1.1.2 ! root 2288: C data type analysis is also done in this pass, and every tree node
! 2289: that represents an expression has a data type attached. Variables are
! 2290: represented as declaration nodes.
1.1 root 2291:
1.1.1.2 ! root 2292: Constant folding and associative-law simplifications are also done
! 2293: during this pass.
1.1 root 2294:
1.1.1.2 ! root 2295: The source files for parsing are @file{parse.y}, @file{decl.c},
1.1 root 2296: @file{typecheck.c}, @file{stor-layout.c}, @file{fold-const.c}, and
2297: @file{tree.c}. The last three are intended to be language-independent.
2298: There are also header files @file{parse.h}, @file{c-tree.h},
2299: @file{tree.h} and @file{tree.def}. The last two define the format of
1.1.1.2 ! root 2300: the tree representation.@refill
1.1 root 2301:
2302: @item
1.1.1.2 ! root 2303: RTL generation. This is the conversion of syntax tree into RTL code.
! 2304: It is actually done statement-by-statement during parsing, but for
! 2305: most purposes it can be thought of as a separate pass.
1.1 root 2306:
2307: This is where the bulk of target-parameter-dependent code is found,
2308: since often it is necessary for strategies to apply only when certain
2309: standard kinds of instructions are available. The purpose of named
2310: instruction patterns is to provide this information to the RTL
2311: generation pass.
2312:
2313: Optimization is done in this pass for @code{if}-conditions that are
2314: comparisons, boolean operations or conditional expressions. Tail
2315: recursion is detected at this time also. Decisions are made about how
2316: best to arrange loops and how to output @code{switch} statements.
2317:
1.1.1.2 ! root 2318: The source files for RTL generation are @file{stmt.c}, @file{expr.c},
1.1 root 2319: @file{explow.c}, @file{expmed.c}, @file{optabs.c} and @file{emit-rtl.c}.
2320: Also, the file @file{insn-emit.c}, generated from the machine description
2321: by the program @code{genemit}, is used in this pass. The header files
1.1.1.2 ! root 2322: @file{expr.h} is used for communication within this pass.@refill
1.1 root 2323:
1.1.1.2 ! root 2324: The header files @file{insn-flags.h} and @file{insn-codes.h},
! 2325: generated from the machine description by the programs @code{genflags}
! 2326: and @code{gencodes}, tell this pass which standard names are available
! 2327: for use and which patterns correspond to them.@refill
1.1 root 2328:
2329: Aside from debugging information output, none of the following passes
1.1.1.2 ! root 2330: refers to the tree structure representation of the function (only
! 2331: part of which is saved).
1.1 root 2332:
1.1.1.2 ! root 2333: The decision of whether the function can and should be expanded inline
! 2334: in its subsequent callers is made at the end of rtl generation. The
! 2335: function must meet certain criteria, currently related to the size of
! 2336: the function and the types and number of parameters it has. Note that
! 2337: this function may contain loops, recursive calls to itself
! 2338: (tail-recursive functions can be inlined!), gotos, in short, all
! 2339: constructs supported by GNU CC.
! 2340:
! 2341: The option @samp{-dr} causes a debugging dump of the RTL code after
! 2342: this pass. This dump file's name is made by appending @samp{.rtl} to
! 2343: the input file name.
1.1 root 2344:
2345: @item
1.1.1.2 ! root 2346: Jump optimization. This pass simplifies jumps to the following
! 2347: instruction, jumps across jumps, and jumps to jumps. It deletes
! 2348: unreferenced labels and unreachable code, except that unreachable code
! 2349: that contains a loop is not recognized as unreachable in this pass.
! 2350: (Such loops are deleted later in the basic block analysis.)
1.1 root 2351:
2352: Jump optimization is performed two or three times. The first time is
1.1.1.2 ! root 2353: immediately following RTL generation. The second time is after CSE,
! 2354: but only if CSE says repeated jump optimization is needed. The
! 2355: last time is right before the final pass. That time, cross-jumping
! 2356: and deletion of no-op move instructions are done together with the
! 2357: optimizations described above.
1.1 root 2358:
2359: The source file of this pass is @file{jump.c}.
2360:
1.1.1.2 ! root 2361: The option @samp{-dj} causes a debugging dump of the RTL code after
! 2362: this pass is run for the first time. This dump file's name is made by
! 2363: appending @samp{.jump} to the input file name.
1.1 root 2364:
2365: @item
2366: Register scan. This pass finds the first and last use of each
2367: register, as a guide for common subexpression elimination. Its source
2368: is in @file{regclass.c}.
2369:
2370: @item
2371: Common subexpression elimination. This pass also does constant
2372: propagation. Its source file is @file{cse.c}. If constant
2373: propagation causes conditional jumps to become unconditional or to
1.1.1.2 ! root 2374: become no-ops, jump optimization is run again when CSE is finished.
1.1 root 2375:
1.1.1.2 ! root 2376: The option @samp{-ds} causes a debugging dump of the RTL code after
1.1 root 2377: this pass. This dump file's name is made by appending @samp{.cse} to
2378: the input file name.
2379:
2380: @item
2381: Loop optimization. This pass moves constant expressions out of loops.
2382: Its source file is @file{loop.c}.
2383:
1.1.1.2 ! root 2384: The option @samp{-dL} causes a debugging dump of the RTL code after
1.1 root 2385: this pass. This dump file's name is made by appending @samp{.loop} to
2386: the input file name.
2387:
2388: @item
2389: Stupid register allocation is performed at this point in a
2390: nonoptimizing compilation. It does a little data flow analysis as
2391: well. When stupid register allocation is in use, the next pass
2392: executed is the reloading pass; the others in between are skipped.
1.1.1.2 ! root 2393: The source file is @file{stupid.c}.
1.1 root 2394:
2395: @item
2396: Data flow analysis (@file{flow.c}). This pass divides the program
2397: into basic blocks (and in the process deletes unreachable loops); then
2398: it computes which pseudo-registers are live at each point in the
2399: program, and makes the first instruction that uses a value point at
2400: the instruction that computed the value.
2401:
2402: This pass also deletes computations whose results are never used, and
2403: combines memory references with add or subtract instructions to make
2404: autoincrement or autodecrement addressing.
2405:
1.1.1.2 ! root 2406: The option @samp{-df} causes a debugging dump of the RTL code after
1.1 root 2407: this pass. This dump file's name is made by appending @samp{.flow} to
2408: the input file name. If stupid register allocation is in use, this
2409: dump file reflects the full results of such allocation.
2410:
2411: @item
2412: Instruction combination (@file{combine.c}). This pass attempts to
2413: combine groups of two or three instructions that are related by data
2414: flow into single instructions. It combines the RTL expressions for
2415: the instructions by substitution, simplifies the result using algebra,
2416: and then attempts to match the result against the machine description.
2417:
1.1.1.2 ! root 2418: The option @samp{-dc} causes a debugging dump of the RTL code after
1.1 root 2419: this pass. This dump file's name is made by appending @samp{.combine}
2420: to the input file name.
2421:
2422: @item
2423: Register class preferencing. The RTL code is scanned to find out
1.1.1.2 ! root 2424: which register class is best for each pseudo register. The source
! 2425: file is @file{regclass.c}.
1.1 root 2426:
2427: @item
2428: Local register allocation (@file{local-alloc.c}). This pass allocates
2429: hard registers to pseudo registers that are used only within one basic
1.1.1.2 ! root 2430: block. Because the basic block is linear, it can use fast and
! 2431: powerful techniques to do a very good job.
1.1 root 2432:
1.1.1.2 ! root 2433: The option @samp{-dl} causes a debugging dump of the RTL code after
1.1 root 2434: this pass. This dump file's name is made by appending @samp{.lreg} to
2435: the input file name.
2436:
2437: @item
2438: Global register allocation (@file{global-alloc.c}). This pass
2439: allocates hard registers for the remaining pseudo registers (those
2440: whose life spans are not contained in one basic block).
2441:
2442: @item
1.1.1.2 ! root 2443: Reloading. This pass renumbers pseudo registers with the hardware
! 2444: registers numbers they were allocated. Pseudo registers that did not
! 2445: get hard registers are replaced with stack slots. Then it finds
! 2446: instructions that are invalid because a value has failed to end up in
! 2447: a register, or has ended up in a register of the wrong kind. It fixes
! 2448: up these instructions by reloading the problematical values
! 2449: temporarily into registers. Additional instructions are generated to
! 2450: do the copying.
1.1 root 2451:
2452: Source files are @file{reload.c} and @file{reload1.c}, plus the header
2453: @file{reload.h} used for communication between them.
2454:
1.1.1.2 ! root 2455: The option @samp{-dg} causes a debugging dump of the RTL code after
1.1 root 2456: this pass. This dump file's name is made by appending @samp{.greg} to
2457: the input file name.
2458:
2459: @item
1.1.1.2 ! root 2460: Jump optimization is repeated, this time including cross-jumping
! 2461: and deletion of no-op move instructions. Machine-specific peephole
! 2462: optimizations are performed at the same time.
! 2463:
! 2464: The option @samp{-dJ} causes a debugging dump of the RTL code after
! 2465: this pass. This dump file's name is made by appending @samp{.jump2}
! 2466: to the input file name.
1.1 root 2467:
2468: @item
2469: Final. This pass outputs the assembler code for the function. It is
1.1.1.2 ! root 2470: also responsible for identifying spurious test and compare
! 2471: instructions. The function entry and exit sequences are generated
! 2472: directly as assembler code in this pass; they never exist as RTL.
1.1 root 2473:
2474: The source files are @file{final.c} plus @file{insn-output.c}; the
2475: latter is generated automatically from the machine description by the
2476: tool @file{genoutput}. The header file @file{conditions.h} is used
2477: for communication between these files.
2478:
2479: @item
2480: Debugging information output. This is run after final because it must
2481: output the stack slot offsets for pseudo registers that did not get
2482: hard registers. Source files are @file{dbxout.c} for DBX symbol table
2483: format and @file{symout.c} for GDB's own symbol table format.
2484: @end itemize
2485:
2486: Some additional files are used by all or many passes:
2487:
2488: @itemize @bullet
2489: @item
2490: Every pass uses @file{machmode.def}, which defines the machine modes.
2491:
2492: @item
2493: All the passes that work with RTL use the header files @file{rtl.h}
1.1.1.2 ! root 2494: and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
! 2495: @code{gen*} also use these files to read and work with the machine
! 2496: description RTL.
1.1 root 2497:
2498: @item
2499: Several passes refer to the header file @file{insn-config.h} which
2500: contains a few parameters (C macro definitions) generated
2501: automatically from the machine description RTL by the tool
2502: @code{genconfig}.
2503:
2504: @item
2505: Several passes use the instruction recognizer, which consists of
2506: @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
2507: and @file{insn-extract.c} that are generated automatically from the
1.1.1.2 ! root 2508: machine description by the tools @file{genrecog} and
! 2509: @file{genextract}.@refill
1.1 root 2510:
2511: @item
1.1.1.2 ! root 2512: Several passes use the header files @file{regs.h} which defines the
! 2513: information recorded about pseudo register usage, and @file{basic-block.h}
1.1 root 2514: which defines the information recorded about basic blocks.
2515:
2516: @item
2517: @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
2518: with a bit for each hard register, and some macros to manipulate it.
2519: This type is just @code{int} if the machine has few enough hard registers;
2520: otherwise it is an array of @code{int} and some of the macros expand
2521: into loops.
2522: @end itemize
2523:
2524: @node RTL, Machine Desc, Passes, Top
2525: @chapter RTL Representation
2526:
2527: Most of the work of the compiler is done on an intermediate representation
1.1.1.2 ! root 2528: called register transfer language. In this language, the instructions to be
1.1 root 2529: output are described, pretty much one by one, in an algebraic form that
2530: describes what the instruction does.
2531:
2532: RTL is inspired by Lisp lists. It has both an internal form, made up of
2533: structures that point at other structures, and a textual form that is used
2534: in the machine description and in printed debugging dumps. The textual
2535: form uses nested parentheses to indicate the pointers in the internal form.
2536:
2537: @menu
2538: * RTL Objects:: Expressions vs vectors vs strings vs integers.
2539: * Accessors:: Macros to access expression operands or vector elts.
1.1.1.2 ! root 2540: * Flags:: Other flags in an RTL expression.
1.1 root 2541: * Machine Modes:: Describing the size and format of a datum.
2542: * Constants:: Expressions with constant values.
2543: * Regs and Memory:: Expressions representing register contents or memory.
2544: * Arithmetic:: Expressions representing arithmetic on other expressions.
2545: * Comparisons:: Expressions representing comparison of expressions.
2546: * Bit Fields:: Expressions representing bit-fields in memory or reg.
2547: * Conversions:: Extending, truncating, floating or fixing.
2548: * RTL Declarations:: Declaring volatility, constancy, etc.
2549: * Side Effects:: Expressions for storing in registers, etc.
2550: * Incdec:: Embedded side-effects for autoincrement addressing.
1.1.1.2 ! root 2551: * Assembler:: Representing @code{asm} with operands.
1.1 root 2552: * Insns:: Expression types for entire insns.
1.1.1.2 ! root 2553: * Calls:: RTL representation of function call insns.
1.1 root 2554: * Sharing:: Some expressions are unique; others *must* be copied.
2555: @end menu
2556:
2557: @node RTL Objects, Accessors, RTL, RTL
2558: @section RTL Object Types
2559:
2560: RTL uses four kinds of objects: expressions, integers, strings and vectors.
1.1.1.2 ! root 2561: Expressions are the most important ones. An RTL expression (``RTX'', for
! 2562: short) is a C structure, but it is usually referred to with a pointer; a
! 2563: type that is given the typedef name @code{rtx}.
1.1 root 2564:
2565: An integer is simply an @code{int}, and a string is a @code{char *}.
1.1.1.2 ! root 2566: Within RTL code, strings appear only inside @samp{symbol_ref} expressions,
! 2567: but they appear in other contexts in the RTL expressions that make up
1.1 root 2568: machine descriptions. Their written form uses decimal digits.
2569:
2570: A string is a sequence of characters. In core it is represented as a
1.1.1.2 ! root 2571: @code{char *} in usual C fashion, and it is written in C syntax as well.
1.1 root 2572: However, strings in RTL may never be null. If you write an empty string in
2573: a machine description, it is represented in core as a null pointer rather
2574: than as a pointer to a null character. In certain contexts, these null
2575: pointers instead of strings are valid.
2576:
2577: A vector contains an arbitrary, specified number of pointers to
2578: expressions. The number of elements in the vector is explicitly present in
2579: the vector. The written form of a vector consists of square brackets
2580: (@samp{[@dots{}]}) surrounding the elements, in sequence and with
2581: whitespace separating them. Vectors of length zero are not created; null
2582: pointers are used instead.
2583:
1.1.1.2 ! root 2584: Expressions are classified by @dfn{expression codes} (also called RTX
! 2585: codes). The expression code is a name defined in @file{rtl.def}, which is
! 2586: also (in upper case) a C enumeration constant. The possible expression
! 2587: codes and their meanings are machine-independent. The code of an RTX can
! 2588: be extracted with the macro @code{GET_CODE (@var{x})} and altered with
! 2589: @code{PUT_CODE (@var{x}, @var{newcode})}.
1.1 root 2590:
2591: The expression code determines how many operands the expression contains,
2592: and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
2593: by looking at an operand what kind of object it is. Instead, you must know
2594: from its context---from the expression code of the containing expression.
1.1.1.2 ! root 2595: For example, in an expression of code @samp{subreg}, the first operand is
1.1 root 2596: to be regarded as an expression and the second operand as an integer. In
1.1.1.2 ! root 2597: an expression of code @samp{plus}, there are two operands, both of which
! 2598: are to be regarded as expressions. In a @samp{symbol_ref} expression,
1.1 root 2599: there is one operand, which is to be regarded as a string.
2600:
2601: Expressions are written as parentheses containing the name of the
2602: expression type, its flags and machine mode if any, and then the operands
2603: of the expression (separated by spaces).
2604:
1.1.1.2 ! root 2605: Expression code names in the @samp{md} file are written in lower case,
! 2606: but when they appear in C code they are written in upper case. In this
! 2607: manual, they are shown as follows: @samp{const_int}.
! 2608:
1.1 root 2609: In a few contexts a null pointer is valid where an expression is normally
2610: wanted. The written form of this is @samp{(nil)}.
2611:
1.1.1.2 ! root 2612: @node Accessors, Flags, RTL Objects, RTL
1.1 root 2613: @section Access to Operands
2614:
2615: For each expression type @file{rtl.def} specifies the number of contained
2616: objects and their kinds, with four possibilities: @samp{e} for expression
2617: (actually a pointer to an expression), @samp{i} for integer, @samp{s} for
2618: string, and @samp{E} for vector of expressions. The sequence of letters
2619: for an expression code is called its @dfn{format}. Thus, the format of
1.1.1.2 ! root 2620: @samp{subreg} is @samp{ei}.@refill
1.1 root 2621:
2622: Two other format characters are used occasionally: @samp{u} and @samp{0}.
2623: @samp{u} is equivalent to @samp{e} except that it is printed differently in
2624: debugging dumps, and @samp{0} means a slot whose contents do not fit any
2625: normal category. @samp{0} slots are not printed at all in dumps, and are
1.1.1.2 ! root 2626: often used in special ways by small parts of the compiler.@refill
1.1 root 2627:
2628: There are macros to get the number of operands and the format of an
2629: expression code:
2630:
2631: @table @code
2632: @item GET_RTX_LENGTH (@var{code})
1.1.1.2 ! root 2633: Number of operands of an RTX of code @var{code}.
1.1 root 2634:
2635: @item GET_RTX_FORMAT (@var{code})
1.1.1.2 ! root 2636: The format of an RTX of code @var{code}, as a C string.
1.1 root 2637: @end table
2638:
2639: Operands of expressions are accessed using the macros @code{XEXP},
2640: @code{XINT} and @code{XSTR}. Each of these macros takes two arguments: an
1.1.1.2 ! root 2641: expression-pointer (RTX) and an operand number (counting from zero).
! 2642: Thus,@refill
1.1 root 2643:
2644: @example
1.1.1.2 ! root 2645: XEXP (@var{x}, 2)
1.1 root 2646: @end example
2647:
2648: @noindent
2649: accesses operand 2 of expression @var{x}, as an expression.
2650:
2651: @example
1.1.1.2 ! root 2652: XINT (@var{x}, 2)
1.1 root 2653: @end example
2654:
2655: @noindent
2656: accesses the same operand as an integer. @code{XSTR}, used in the same
2657: fashion, would access it as a string.
2658:
2659: Any operand can be accessed as an integer, as an expression or as a string.
2660: You must choose the correct method of access for the kind of value actually
2661: stored in the operand. You would do this based on the expression code of
2662: the containing expression. That is also how you would know how many
2663: operands there are.
2664:
2665: For example, if @var{x} is a @samp{subreg} expression, you know that it has
1.1.1.2 ! root 2666: two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
! 2667: and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
! 2668: would get the address of the expression operand but cast as an integer;
! 2669: that might occasionally be useful, but it would be cleaner to write
! 2670: @code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
! 2671: compile without error, and would return the second, integer operand cast as
! 2672: an expression pointer, which would probably result in a crash when
! 2673: accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
! 2674: but this will access memory past the end of the expression with
! 2675: unpredictable results.@refill
1.1 root 2676:
2677: Access to operands which are vectors is more complicated. You can use the
2678: macro @code{XVEC} to get the vector-pointer itself, or the macros
2679: @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
2680: vector.
2681:
2682: @table @code
2683: @item XVEC (@var{exp}, @var{idx})
2684: Access the vector-pointer which is operand number @var{idx} in @var{exp}.
2685:
2686: @item XVECLEN (@var{exp}, @var{idx})
2687: Access the length (number of elements) in the vector which is
2688: in operand number @var{idx} in @var{exp}. This value is an @code{int}.
2689:
1.1.1.2 ! root 2690: @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
1.1 root 2691: Access element number @var{eltnum} in the vector which is
1.1.1.2 ! root 2692: in operand number @var{idx} in @var{exp}. This value is an RTX.
1.1 root 2693:
2694: It is up to you to make sure that @var{eltnum} is not negative
2695: and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
2696: @end table
2697:
2698: All the macros defined in this section expand into lvalues and therefore
2699: can be used to assign the operands, lengths and vector elements as well as
2700: to access them.
2701:
1.1.1.2 ! root 2702: @node Flags, Machine Modes, Accessors, RTL
! 2703: @section Flags in an RTL Expression
! 2704:
! 2705: RTL expressions contain several flags (one-bit bit-fields) that are used
! 2706: in certain types of expression.
! 2707:
! 2708: @table @code
! 2709: @item used
! 2710: This flag is used only momentarily, at the end of RTL generation for a
! 2711: function, to count the number of times an expression appears in insns.
! 2712: Expressions that appear more than once are copied, according to the
! 2713: rules for shared structure (@pxref{Sharing}).
! 2714:
! 2715: @item volatil
! 2716: This flag is used in @samp{mem} and @samp{reg} expressions and in insns.
! 2717: In RTL dump files, it is printed as @samp{/v}.
! 2718:
! 2719: In a @samp{mem} expression, it is 1 if the memory reference is volatile.
! 2720: Volatile memory references may not be deleted, reordered or combined.
! 2721:
! 2722: In a @samp{reg} expression, it is 1 if the value is a user-level variable.
! 2723: 0 indicates an internal compiler temporary.
! 2724:
! 2725: In an insn, 1 means the insn has been deleted.
! 2726:
! 2727: @item in_struct
! 2728: This flag is used in @samp{mem} expressions. It is 1 if the memory
! 2729: datum referred to is all or part of a structure or array; 0 if it is (or
! 2730: might be) a scalar variable. A reference through a C pointer has 0
! 2731: because the pointer might point to a scalar variable.
! 2732:
! 2733: This information allows the compiler to determine something about possible
! 2734: cases of aliasing.
! 2735:
! 2736: In an RTL dump, this flag is represented as @samp{/s}.
! 2737:
! 2738: @item unchanging
! 2739: This flag is used in @samp{reg} and @samp{mem} expressions. 1 means
! 2740: that the value of the expression never changes (at least within the
! 2741: current function).
! 2742:
! 2743: In an RTL dump, this flag is represented as @samp{/u}.
! 2744: @end table
! 2745:
! 2746: @node Machine Modes, Constants, Flags, RTL
1.1 root 2747: @section Machine Modes
2748:
2749: A machine mode describes a size of data object and the representation used
2750: for it. In the C code, machine modes are represented by an enumeration
1.1.1.2 ! root 2751: type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
! 2752: expression has room for a machine mode and so do certain kinds of tree
! 2753: expressions (declarations and types, to be precise).
1.1 root 2754:
2755: In debugging dumps and machine descriptions, the machine mode of an RTL
2756: expression is written after the expression code with a colon to separate
2757: them. The letters @samp{mode} which appear at the end of each machine mode
2758: name are omitted. For example, @code{(reg:SI 38)} is a @samp{reg}
2759: expression with machine mode @code{SImode}. If the mode is
2760: @code{VOIDmode}, it is not written at all.
2761:
2762: Here is a table of machine modes.
2763:
2764: @table @code
2765: @item QImode
2766: ``Quarter-Integer'' mode represents a single byte treated as an integer.
2767:
2768: @item HImode
2769: ``Half-Integer'' mode represents a two-byte integer.
2770:
2771: @item SImode
2772: ``Single Integer'' mode represents a four-byte integer.
2773:
2774: @item DImode
2775: ``Double Integer'' mode represents an eight-byte integer.
2776:
2777: @item TImode
2778: ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
2779:
2780: @item SFmode
2781: ``Single Floating'' mode represents a single-precision (four byte) floating
2782: point number.
2783:
2784: @item DFmode
2785: ``Double Floating'' mode represents a double-precision (eight byte) floating
2786: point number.
2787:
2788: @item TFmode
2789: ``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
2790: floating point number.
2791:
2792: @item BLKmode
2793: ``Block'' mode represents values that are aggregates to which none of
1.1.1.2 ! root 2794: the other modes apply. In RTL, only memory references can have this mode,
1.1 root 2795: and only if they appear in string-move or vector instructions. On machines
2796: which have no such instructions, @code{BLKmode} will not appear in RTL.
2797:
2798: @item VOIDmode
2799: Void mode means the absence of a mode or an unspecified mode.
1.1.1.2 ! root 2800: For example, RTL expressions of code @samp{const_int} have mode
1.1 root 2801: @code{VOIDmode} because they can be taken to have whatever mode the context
2802: requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
2803: the absence of any mode.
2804:
2805: @item EPmode
2806: ``Entry Pointer'' mode is intended to be used for function variables in
2807: Pascal and other block structured languages. Such values contain
2808: both a function address and a static chain pointer for access to
2809: automatic variables of outer levels. This mode is only partially
2810: implemented since C does not use it.
2811:
2812: @item CSImode@r{, @dots{}}
2813: ``Complex Single Integer'' mode stands for a complex number represented
2814: as a pair of @code{SImode} integers. Any of the integer and floating modes
2815: may have @samp{C} prefixed to its name to obtain a complex number mode.
2816: For example, there are @code{CQImode}, @code{CSFmode}, and @code{CDFmode}.
2817: Since C does not support complex numbers, these machine modes are only
2818: partially implemented.
2819:
2820: @item BImode
2821: This is the machine mode of a bit-field in a structure. It is used
2822: only in the syntax tree, never in RTL, and in the syntax tree it appears
2823: only in declaration nodes. In C, it appears only in @code{FIELD_DECL}
2824: nodes for structure fields defined with a bit size.
2825: @end table
2826:
2827: The machine description defines @code{Pmode} as a C macro which expands
2828: into the machine mode used for addresses. Normally this is @code{SImode}.
2829:
2830: The only modes which a machine description @i{must} support are
2831: @code{QImode}, @code{SImode}, @code{SFmode} and @code{DFmode}. The
2832: compiler will attempt to use @code{DImode} for two-word structures and
2833: unions, but it would not be hard to program it to avoid this. Likewise,
2834: you can arrange for the C type @code{short int} to avoid using
2835: @code{HImode}. In the long term it would be desirable to make the set of
2836: available machine modes machine-dependent and eliminate all assumptions
2837: about specific machine modes or their uses from the machine-independent
2838: code of the compiler.
2839:
2840: Here are some C macros that relate to machine modes:
2841:
2842: @table @code
2843: @item GET_MODE (@var{x})
1.1.1.2 ! root 2844: Returns the machine mode of the RTX @var{x}.
1.1 root 2845:
2846: @item PUT_MODE (@var{x}, @var{newmode})
1.1.1.2 ! root 2847: Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1.1 root 2848:
2849: @item GET_MODE_SIZE (@var{m})
2850: Returns the size in bytes of a datum of mode @var{m}.
2851:
2852: @item GET_MODE_BITSIZE (@var{m})
2853: Returns the size in bits of a datum of mode @var{m}.
2854:
2855: @item GET_MODE_UNIT_SIZE (@var{m})
2856: Returns the size in bits of the subunits of a datum of mode @var{m}.
2857: This is the same as @code{GET_MODE_SIZE} except in the case of
1.1.1.2 ! root 2858: complex modes and @code{EPmode}. For them, the unit size is the
1.1 root 2859: size of the real or imaginary part, or the size of the function
2860: pointer or the context pointer.
2861: @end table
2862:
2863: @node Constants, Regs and Memory, Machine Modes, RTL
2864: @section Constant Expression Types
2865:
2866: The simplest RTL expressions are those that represent constant values.
2867:
2868: @table @code
2869: @item (const_int @var{i})
2870: This type of expression represents the integer value @var{i}. @var{i}
2871: is customarily accessed with the macro @code{INTVAL} as in
1.1.1.2 ! root 2872: @code{INTVAL (@var{exp})}, which is equivalent to @code{XINT (@var{exp}, 0)}.
1.1 root 2873:
2874: There is only one expression object for the integer value zero;
2875: it is the value of the variable @code{const0_rtx}. Likewise, the
2876: only expression for integer value one is found in @code{const1_rtx}.
1.1.1.2 ! root 2877: Any attempt to create an expression of code @samp{const_int} and
1.1 root 2878: value zero or one will return @code{const0_rtx} or @code{const1_rtx}
2879: as appropriate.
2880:
2881: @item (const_double:@var{m} @var{i0} @var{i1})
2882: Represents a floating point constant value of mode @var{m}. The two
2883: integers @var{i0} and @var{i1} together contain the bits of a
2884: @code{double} value. To convert them to a @code{double}, do
2885:
2886: @example
1.1.1.2 ! root 2887: union @{ double d; int i[2];@} u;
1.1 root 2888: u.i[0] = XINT (x, 0);
2889: u.i[1] = XINT (x, 1);
2890: @end example
2891:
2892: @noindent
2893: and then refer to @code{u.d}. The value of the constant is
2894: represented as a double in this fashion even if the value represented
2895: is single-precision.
2896:
1.1.1.2 ! root 2897: The global variables @code{dconst0_rtx} and @code{fconst0_rtx} hold
! 2898: @samp{const_double} expressions with value 0, in modes @code{DFmode} and
! 2899: @code{SFmode}, respectively.
1.1 root 2900:
2901: @item (symbol_ref @var{symbol})
2902: Represents the value of an assembler label for data. @var{symbol} is
2903: a string that describes the name of the assembler label. If it starts
2904: with a @samp{*}, the label is the rest of @var{symbol} not including
2905: the @samp{*}. Otherwise, the label is @var{symbol}, prefixed with
2906: @samp{_}.
2907:
2908: @item (label_ref @var{label})
2909: Represents the value of an assembler label for code. It contains one
1.1.1.2 ! root 2910: operand, an expression, which must be a @samp{code_label} that appears
1.1 root 2911: in the instruction sequence to identify the place where the label
2912: should go.
2913:
2914: The reason for using a distinct expression type for code label
2915: references is so that jump optimization can distinguish them.
2916:
2917: @item (const @var{exp})
2918: Represents a constant that is the result of an assembly-time
2919: arithmetic computation. The operand, @var{exp}, is an expression that
2920: contains only constants (@samp{const_int}, @samp{symbol_ref} and
2921: @samp{label_ref} expressions) combined with @samp{plus} and
2922: @samp{minus}. However, not all combinations are valid, since the
2923: assembler cannot do arbitrary arithmetic on relocatable symbols.
2924: @end table
2925:
2926: @node Regs and Memory, Arithmetic, Constants, RTL
2927: @section Registers and Memory
2928:
2929: Here are the RTL expression types for describing access to machine
2930: registers and to main memory.
2931:
2932: @table @code
2933: @item (reg:@var{m} @var{n})
2934: For small values of the integer @var{n} (less than
2935: @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
2936: register number @var{n}: a @dfn{hard register}. For larger values of
2937: @var{n}, it stands for a temporary value or @dfn{pseudo register}.
2938: The compiler's strategy is to generate code assuming an unlimited
2939: number of such pseudo registers, and later convert them into hard
2940: registers or into memory references.
2941:
2942: The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
2943: description, since the number of hard registers on the machine is an
2944: invariant characteristic of the machine. Note, however, that not
2945: all of the machine registers must be general registers. All the
2946: machine registers that can be used for storage of data are given
2947: hard register numbers, even those that can be used only in certain
2948: instructions or can hold only certain types of data.
2949:
1.1.1.2 ! root 2950: Each pseudo register number used in a function's RTL code is
1.1 root 2951: represented by a unique @samp{reg} expression.
2952:
2953: @var{m} is the machine mode of the reference. It is necessary because
2954: machines can generally refer to each register in more than one mode.
2955: For example, a register may contain a full word but there may be
2956: instructions to refer to it as a half word or as a single byte, as
2957: well as instructions to refer to it as a floating point number of
2958: various precisions.
2959:
2960: Even for a register that the machine can access in only one mode,
2961: the mode must always be specified.
2962:
2963: A hard register may be accessed in various modes throughout one
2964: function, but each pseudo register is given a natural mode
2965: and is accessed only in that mode. When it is necessary to describe
2966: an access to a pseudo register using a nonnatural mode, a @samp{subreg}
2967: expression is used.
2968:
2969: A @samp{reg} expression with a machine mode that specifies more than
2970: one word of data may actually stand for several consecutive registers.
2971: If in addition the register number specifies a hardware register, then
2972: it actually represents several consecutive hardware registers starting
2973: with the specified one.
2974:
2975: Such multi-word hardware register @samp{reg} expressions may not be live
2976: across the boundary of a basic block. The lifetime analysis pass does not
2977: know how to record properly that several consecutive registers are
2978: actually live there, and therefore register allocation would be confused.
2979: The CSE pass must go out of its way to make sure the situation does
2980: not arise.
2981:
2982: @item (subreg:@var{m} @var{reg} @var{wordnum})
2983: @samp{subreg} expressions are used to refer to a register in a machine
2984: mode other than its natural one, or to refer to one register of
2985: a multi-word @samp{reg} that actually refers to several registers.
2986:
2987: Each pseudo-register has a natural mode. If it is necessary to
2988: operate on it in a different mode---for example, to perform a fullword
2989: move instruction on a pseudo-register that contains a single byte---
2990: the pseudo-register must be enclosed in a @samp{subreg}. In such
2991: a case, @var{wordnum} is zero.
2992:
2993: The other use of @samp{subreg} is to extract the individual registers
2994: of a multi-register value. Machine modes such as @code{DImode} and
2995: @code{EPmode} indicate values longer than a word, values which usually
2996: require two consecutive registers. To access one of the registers,
2997: use a @samp{subreg} with mode @code{SImode} and a @var{wordnum} that
2998: says which register.
2999:
3000: The compilation parameter @code{WORDS_BIG_ENDIAN}, if defined, says
3001: that word number zero is the most significant part; otherwise, it is
3002: the least significant part.
3003:
3004: Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
3005: using a @samp{subreg}. On some machines the most significant part of a
3006: @code{DFmode} value does not have the same format as a single-precision
3007: floating value.
3008:
3009: @item (cc0)
3010: This refers to the machine's condition code register. It has no
3011: operands and may not have a machine mode. It may be validly used in
3012: only two contexts: as the destination of an assignment (in test and
3013: compare instructions) and in comparison operators comparing against
1.1.1.2 ! root 3014: zero (@samp{const_int} with value zero; that is to say,
! 3015: @code{const0_rtx}).
1.1 root 3016:
1.1.1.2 ! root 3017: There is only one expression object of code @samp{cc0}; it is the
1.1 root 3018: value of the variable @code{cc0_rtx}. Any attempt to create an
1.1.1.2 ! root 3019: expression of code @samp{cc0} will return @code{cc0_rtx}.
1.1 root 3020:
1.1.1.2 ! root 3021: One special thing about the condition code register is that
! 3022: instructions can set it implicitly. On many machines, nearly all
! 3023: instructions set the condition code based on the value that they
! 3024: compute or store. It is not necessary to record these actions
! 3025: explicitly in the RTL because the machine description includes a
! 3026: prescription for recognizing the instructions that do so (by means of
! 3027: the macro @code{NOTICE_UPDATE_CC}). Only instructions whose sole
! 3028: purpose is to set the condition code, and instructions that use the
! 3029: condition code, need mention @code{(cc0)}.
1.1 root 3030:
3031: @item (pc)
3032: This represents the machine's program counter. It has no operands and
3033: may not have a machine mode. @code{(pc)} may be validly used only in
3034: certain specific contexts in jump instructions.
3035:
1.1.1.2 ! root 3036: There is only one expression object of code @samp{pc}; it is the value
! 3037: of the variable @code{pc_rtx}. Any attempt to create an expression of
! 3038: code @samp{pc} will return @code{pc_rtx}.
1.1 root 3039:
1.1.1.2 ! root 3040: All instructions that do not jump alter the program counter implicitly
! 3041: by incrementing it, but there is no need to mention this in the RTL.
1.1 root 3042:
3043: @item (mem:@var{m} @var{addr})
1.1.1.2 ! root 3044: This RTX represents a reference to main memory at an address
! 3045: represented by the expression @var{addr}. @var{m} specifies how large
! 3046: a unit of memory is accessed.
1.1 root 3047: @end table
3048:
3049: @node Arithmetic, Comparisons, Regs and Memory, RTL
3050: @section RTL Expressions for Arithmetic
3051:
3052: @table @code
3053: @item (plus:@var{m} @var{x} @var{y})
3054: Represents the sum of the values represented by @var{x} and @var{y}
3055: carried out in machine mode @var{m}. This is valid only if
3056: @var{x} and @var{y} both are valid for mode @var{m}.
3057:
3058: @item (minus:@var{m} @var{x} @var{y})
3059: Like @samp{plus} but represents subtraction.
3060:
3061: @item (minus @var{x} @var{y})
3062: Represents the result of subtracting @var{y} from @var{x}
3063: for purposes of comparison. The absence of a machine mode
3064: in the @samp{minus} expression indicates that the result is
3065: computed without overflow, as if with infinite precision.
3066:
3067: Of course, machines can't really subtract with infinite precision.
3068: However, they can pretend to do so when only the sign of the
3069: result will be used, which is the case when the result is stored
1.1.1.2 ! root 3070: in @code{(cc0)}. And that is the only way this kind of expression
1.1 root 3071: may validly be used: as a value to be stored in the condition codes.
3072:
3073: @item (neg:@var{m} @var{x})
3074: Represents the negation (subtraction from zero) of the value
3075: represented by @var{x}, carried out in mode @var{m}. @var{x} must be
3076: valid for mode @var{m}.
3077:
3078: @item (mult:@var{m} @var{x} @var{y})
3079: Represents the signed product of the values represented by @var{x} and
3080: @var{y} carried out in machine mode @var{m}. If
3081: @var{x} and @var{y} are both valid for mode @var{m}, this is ordinary
1.1.1.2 ! root 3082: size-preserving multiplication. Alternatively, both @var{x} and @var{y}
1.1 root 3083: may be valid for a different, narrower mode. This represents the
3084: kind of multiplication that generates a product wider than the operands.
3085: Widening multiplication and same-size multiplication are completely
3086: distinct and supported by different machine instructions; machines may
1.1.1.2 ! root 3087: support one but not the other.@refill
1.1 root 3088:
3089: @samp{mult} may be used for floating point division as well.
3090: Then @var{m} is a floating point machine mode.
3091:
3092: @item (umult:@var{m} @var{x} @var{y})
3093: Like @samp{mult} but represents unsigned multiplication. It may be
3094: used in both same-size and widening forms, like @samp{mult}.
1.1.1.2 ! root 3095: @samp{umult} is used only for fixed-point multiplication.
1.1 root 3096:
3097: @item (div:@var{m} @var{x} @var{y})
3098: Represents the quotient in signed division of @var{x} by @var{y},
3099: carried out in machine mode @var{m}. If @var{m} is a floating-point
3100: mode, it represents the exact quotient; otherwise, the integerized
3101: quotient. If @var{x} and @var{y} are both valid for mode @var{m},
3102: this is ordinary size-preserving division. Some machines have
3103: division instructions in which the operands and quotient widths are
3104: not all the same; such instructions are represented by @samp{div}
3105: expressions in which the machine modes are not all the same.
3106:
3107: @item (udiv:@var{m} @var{x} @var{y})
3108: Like @samp{div} but represents unsigned division.
3109:
3110: @item (mod:@var{m} @var{x} @var{y})
3111: @itemx (umod:@var{m} @var{x} @var{y})
3112: Like @samp{div} and @samp{udiv} but represent the remainder instead of
3113: the quotient.
3114:
3115: @item (not:@var{m} @var{x})
3116: Represents the bitwise complement of the value represented by @var{x},
3117: carried out in mode @var{m}, which must be a fixed-point machine mode.
3118: @var{x} must be valid for mode @var{m}, which must be a fixed-point mode.
3119:
3120: @item (and:@var{m} @var{x} @var{y})
3121: Represents the bitwise logical-and of the values represented by
3122: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
3123: valid only if @var{x} and @var{y} both are valid for mode @var{m},
3124: which must be a fixed-point mode.
3125:
3126: @item (ior:@var{m} @var{x} @var{y})
3127: Represents the bitwise inclusive-or of the values represented by
3128: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
3129: valid only if @var{x} and @var{y} both are valid for mode @var{m},
3130: which must be a fixed-point mode.
3131:
3132: @item (xor:@var{m} @var{x} @var{y})
3133: Represents the bitwise exclusive-or of the values represented by
3134: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
3135: valid only if @var{x} and @var{y} both are valid for mode @var{m},
3136: which must be a fixed-point mode.
3137:
3138: @item (lshift:@var{m} @var{x} @var{c})
3139: Represents the result of logically shifting @var{x} left by @var{c}
3140: places. @var{x} must be valid for the mode @var{m}, a fixed-point
3141: machine mode. @var{c} must be valid for a fixed-point mode;
3142: which mode is determined by the mode called for in the machine
3143: description entry for the left-shift instruction. For example,
3144: on the Vax, the mode of @var{c} is @code{QImode} regardless of @var{m}.
3145:
3146: On some machines, negative values of @var{c} may be meaningful; this
1.1.1.2 ! root 3147: is why logical left shift and arithmetic left shift are distinguished.
1.1 root 3148: For example, Vaxes have no right-shift instructions, and right shifts
3149: are represented as left-shift instructions whose counts happen
3150: to be negative constants or else computed (in a previous instruction)
3151: by negation.
3152:
3153: @item (ashift:@var{m} @var{x} @var{c})
3154: Like @samp{lshift} but for arithmetic left shift.
3155:
3156: @item (lshiftrt:@var{m} @var{x} @var{c})
3157: @itemx (ashiftrt:@var{m} @var{x} @var{c})
3158: Like @samp{lshift} and @samp{ashift} but for right shift.
3159:
3160: @item (rotate:@var{m} @var{x} @var{c})
3161: @itemx (rotatert:@var{m} @var{x} @var{c})
3162: Similar but represent left and right rotate.
3163:
3164: @item (abs:@var{m} @var{x})
3165: Represents the absolute value of @var{x}, computed in mode @var{m}.
3166: @var{x} must be valid for @var{m}.
3167:
3168: @item (sqrt:@var{m} @var{x})
3169: Represents the square root of @var{x}, computed in mode @var{m}.
3170: @var{x} must be valid for @var{m}. Most often @var{m} will be
3171: a floating point mode.
1.1.1.2 ! root 3172:
! 3173: @item (ffs:@var{m} @var{x})
! 3174: Represents the one plus the index of the least significant 1-bit in
! 3175: @var{x}, represented as an integer of mode @var{m}. (The value is
! 3176: zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
! 3177: depending on the target machine, various mode combinations may be
! 3178: valid.
1.1 root 3179: @end table
3180:
3181: @node Comparisons, Bit Fields, Arithmetic, RTL
3182: @section Comparison Operations
3183:
3184: Comparison operators test a relation on two operands and are considered to
3185: represent the value 1 if the relation holds, or zero if it does not. The
3186: mode of the comparison is determined by the operands; they must both be
3187: valid for a common machine mode. A comparison with both operands constant
3188: would be invalid as the machine mode could not be deduced from it, but such
1.1.1.2 ! root 3189: a comparison should never exist in RTL due to constant folding.
1.1 root 3190:
3191: Inequality comparisons come in two flavors, signed and unsigned. Thus,
1.1.1.2 ! root 3192: there are distinct expression codes @samp{gt} and @samp{gtu} for signed and
1.1 root 3193: unsigned greater-than. These can produce different results for the same
3194: pair of integer values: for example, 1 is signed greater-than -1 but not
3195: unsigned greater-than, because -1 when regarded as unsigned is actually
1.1.1.2 ! root 3196: @code{0xffffffff} which is greater than 1.
1.1 root 3197:
3198: The signed comparisons are also used for floating point values. Floating
3199: point comparisons are distinguished by the machine modes of the operands.
3200:
3201: The comparison operators may be used to compare the condition codes
1.1.1.2 ! root 3202: @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such a
! 3203: construct actually refers to the result of the preceding instruction in
! 3204: which the condition codes were set. The above example stands for 1 if the
! 3205: condition codes were set to say ``zero'' or ``equal'', 0 otherwise.
! 3206: Although the same comparison operators are used for this as may be used in
! 3207: other contexts on actual data, no confusion can result since the machine
! 3208: description would never allow both kinds of uses in the same context.
1.1 root 3209:
3210: @table @code
3211: @item (eq @var{x} @var{y})
3212: 1 if the values represented by @var{x} and @var{y} are equal,
3213: otherwise 0.
3214:
3215: @item (ne @var{x} @var{y})
3216: 1 if the values represented by @var{x} and @var{y} are not equal,
3217: otherwise 0.
3218:
3219: @item (gt @var{x} @var{y})
3220: 1 if the @var{x} is greater than @var{y}. If they are fixed-point,
3221: the comparison is done in a signed sense.
3222:
3223: @item (gtu @var{x} @var{y})
3224: Like @samp{gt} but does unsigned comparison, on fixed-point numbers only.
3225:
3226: @item (lt @var{x} @var{y})
3227: @item (ltu @var{x} @var{y})
3228: Like @samp{gt} and @samp{gtu} but test for ``less than''.
3229:
3230: @item (ge @var{x} @var{y})
3231: @item (geu @var{x} @var{y})
3232: Like @samp{gt} and @samp{gtu} but test for ``greater than or equal''.
3233:
3234: @item (le @var{x} @var{y})
3235: @item (leu @var{x} @var{y})
3236: Like @samp{gt} and @samp{gtu} but test for ``less than or equal''.
3237:
3238: @item (if_then_else @var{cond} @var{then} @var{else})
3239: This is not a comparison operation but is listed here because it is
3240: always used in conjunction with a comparison operation. To be
3241: precise, @var{cond} is a comparison expression. This expression
3242: represents a choice, according to @var{cond}, between the value
3243: represented by @var{then} and the one represented by @var{else}.
3244:
3245: On most machines, @samp{if_then_else} expressions are valid only
3246: to express conditional jumps.
3247: @end table
3248:
3249: @node Bit Fields, Conversions, Comparisons, RTL
3250: @section Bit-fields
3251:
3252: Special expression codes exist to represent bit-field instructions.
1.1.1.2 ! root 3253: These types of expressions are lvalues in RTL; they may appear
1.1 root 3254: on the left side of a assignment, indicating insertion of a value
3255: into the specified bit field.
3256:
3257: @table @code
3258: @item (sign_extract:SI @var{loc} @var{size} @var{pos})
3259: This represents a reference to a sign-extended bit-field contained or
3260: starting in @var{loc} (a memory or register reference). The bit field
3261: is @var{size} bits wide and starts at bit @var{pos}. The compilation
1.1.1.2 ! root 3262: option @code{BITS_BIG_ENDIAN} says which end of the memory unit
1.1 root 3263: @var{pos} counts from.
3264:
3265: Which machine modes are valid for @var{loc} depends on the machine,
3266: but typically @var{loc} should be a single byte when in memory
3267: or a full word in a register.
3268:
1.1.1.2 ! root 3269: @item (zero_extract:SI @var{loc} @var{size} @var{pos})
1.1 root 3270: Like @samp{sign_extract} but refers to an unsigned or zero-extended
3271: bit field. The same sequence of bits are extracted, but they
3272: are filled to an entire word with zeros instead of by sign-extension.
3273: @end table
3274:
3275: @node Conversions, RTL Declarations, Bit Fields, RTL
3276: @section Conversions
3277:
3278: All conversions between machine modes must be represented by
3279: explicit conversion operations. For example, an expression
1.1.1.2 ! root 3280: which is the sum of a byte and a full word cannot be written as
1.1 root 3281: @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @samp{plus}
3282: operation requires two operands of the same machine mode.
3283: Therefore, the byte-sized operand is enclosed in a conversion
3284: operation, as in
3285:
3286: @example
3287: (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
3288: @end example
3289:
3290: The conversion operation is not a mere placeholder, because there
3291: may be more than one way of converting from a given starting mode
3292: to the desired final mode. The conversion operation code says how
3293: to do it.
3294:
3295: @table @code
3296: @item (sign_extend:@var{m} @var{x})
3297: Represents the result of sign-extending the value @var{x}
3298: to machine mode @var{m}. @var{m} must be a fixed-point mode
3299: and @var{x} a fixed-point value of a mode narrower than @var{m}.
3300:
3301: @item (zero_extend:@var{m} @var{x})
3302: Represents the result of zero-extending the value @var{x}
3303: to machine mode @var{m}. @var{m} must be a fixed-point mode
3304: and @var{x} a fixed-point value of a mode narrower than @var{m}.
3305:
3306: @item (float_extend:@var{m} @var{x})
3307: Represents the result of extending the value @var{x}
3308: to machine mode @var{m}. @var{m} must be a floating point mode
3309: and @var{x} a floating point value of a mode narrower than @var{m}.
3310:
3311: @item (truncate:@var{m} @var{x})
3312: Represents the result of truncating the value @var{x}
3313: to machine mode @var{m}. @var{m} must be a fixed-point mode
3314: and @var{x} a fixed-point value of a mode wider than @var{m}.
3315:
3316: @item (float_truncate:@var{m} @var{x})
3317: Represents the result of truncating the value @var{x}
3318: to machine mode @var{m}. @var{m} must be a floating point mode
3319: and @var{x} a floating point value of a mode wider than @var{m}.
3320:
3321: @item (float:@var{m} @var{x})
1.1.1.2 ! root 3322: Represents the result of converting fixed point value @var{x},
! 3323: regarded as signed, to floating point mode @var{m}.
! 3324:
! 3325: @item (unsigned_float:@var{m} @var{x})
! 3326: Represents the result of converting fixed point value @var{x},
! 3327: regarded as unsigned, to floating point mode @var{m}.
1.1 root 3328:
3329: @item (fix:@var{m} @var{x})
1.1.1.2 ! root 3330: When @var{m} is a fixed point mode, represents the result of
! 3331: converting floating point value @var{x} to mode @var{m}, regarded as
! 3332: signed. How rounding is done is not specified, so this operation may
! 3333: be used validly in compiling C code only for integer-valued operands.
! 3334:
! 3335: @item (unsigned_fix:@var{m} @var{x})
! 3336: Represents the result of converting floating point value @var{x} to
! 3337: fixed point mode @var{m}, regarded as unsigned. How rounding is done
! 3338: is not specified.
1.1 root 3339:
1.1.1.2 ! root 3340: @item (fix:@var{m} @var{x})
! 3341: When @var{m} is a floating point mode, represents the result of
! 3342: converting floating point value @var{x} (valid for mode @var{m}) to an
! 3343: integer, still represented in floating point mode @var{m}, by rounding
! 3344: towards zero.
1.1 root 3345: @end table
3346:
3347: @node RTL Declarations, Side Effects, Conversions, RTL
3348: @section Declarations
3349:
3350: Declaration expression codes do not represent arithmetic operations
3351: but rather state assertions about their operands.
3352:
3353: @table @code
3354: @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
3355: This expression code is used in only one context: operand 0 of a
3356: @samp{set} expression. In addition, the operand of this expression
3357: must be a @samp{subreg} expression.
3358:
3359: The presence of @samp{strict_low_part} says that the part of the
1.1.1.2 ! root 3360: register which is meaningful in mode @var{n}, but is not part of
! 3361: mode @var{m}, is not to be altered. Normally, an assignment to such
1.1 root 3362: a subreg is allowed to have undefined effects on the rest of the
3363: register when @var{m} is less than a word.
3364: @end table
3365:
3366: @node Side Effects, Incdec, RTL Declarations, RTL
3367: @section Side Effect Expressions
3368:
3369: The expression codes described so far represent values, not actions.
3370: But machine instructions never produce values; they are meaningful
3371: only for their side effects on the state of the machine. Special
3372: expression codes are used to represent side effects.
3373:
3374: The body of an instruction is always one of these side effect codes;
3375: the codes described above, which represent values, appear only as
3376: the operands of these.
3377:
3378: @table @code
3379: @item (set @var{lval} @var{x})
3380: Represents the action of storing the value of @var{x} into the place
3381: represented by @var{lval}. @var{lval} must be an expression
3382: representing a place that can be stored in: @samp{reg} (or
3383: @samp{subreg} or @samp{strict_low_part}), @samp{mem}, @samp{pc} or
1.1.1.2 ! root 3384: @samp{cc0}.@refill
1.1 root 3385:
3386: If @var{lval} is a @samp{reg}, @samp{subreg} or @samp{mem}, it has a
1.1.1.2 ! root 3387: machine mode; then @var{x} must be valid for that mode.@refill
1.1 root 3388:
3389: If @var{lval} is a @samp{reg} whose machine mode is less than the full
3390: width of the register, then it means that the part of the register
3391: specified by the machine mode is given the specified value and the
3392: rest of the register receives an undefined value. Likewise, if
3393: @var{lval} is a @samp{subreg} whose machine mode is narrower than
3394: @code{SImode}, the rest of the register can be changed in an undefined way.
3395:
3396: If @var{lval} is a @samp{strict_low_part} of a @samp{subreg}, then the
3397: part of the register specified by the machine mode of the
3398: @samp{subreg} is given the value @var{x} and the rest of the register
1.1.1.2 ! root 3399: is not changed.@refill
1.1 root 3400:
3401: If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
1.1.1.2 ! root 3402: have any mode. This represents a ``test'' or ``compare'' instruction.@refill
1.1 root 3403:
3404: If @var{lval} is @code{(pc)}, we have a jump instruction, and the
3405: possibilities for @var{x} are very limited. It may be a
3406: @samp{label_ref} expression (unconditional jump). It may be an
3407: @samp{if_then_else} (conditional jump), in which case either the
3408: second or the third operand must be @code{(pc)} (for the case which
3409: does not jump) and the other of the two must be a @samp{label_ref}
3410: (for the case which does jump). @var{x} may also be a @samp{mem} or
3411: @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @samp{reg} or a
3412: @samp{mem}; these unusual patterns are used to represent jumps through
1.1.1.2 ! root 3413: branch tables.@refill
1.1 root 3414:
3415: @item (return)
1.1.1.2 ! root 3416: Represents a return from the current function, on machines where this
! 3417: can be done with one instruction, such as Vaxes. On machines where a
! 3418: multi-instruction ``epilogue'' must be executed in order to return
! 3419: from the function, returning is done by jumping to a label which
! 3420: precedes the epilogue, and the @samp{return} expression code is never
! 3421: used.
1.1 root 3422:
3423: @item (call @var{function} @var{nargs})
3424: Represents a function call. @var{function} is a @samp{mem} expression
3425: whose address is the address of the function to be called. @var{nargs}
3426: is an expression representing the number of words of argument.
3427:
3428: Each machine has a standard machine mode which @var{function} must
1.1.1.2 ! root 3429: have. The machine description defines macro @code{FUNCTION_MODE} to
1.1 root 3430: expand into the requisite mode name. The purpose of this mode is to
3431: specify what kind of addressing is allowed, on machines where the
3432: allowed kinds of addressing depend on the machine mode being
3433: addressed.
3434:
3435: @item (clobber @var{x})
3436: Represents the storing or possible storing of an unpredictable,
3437: undescribed value into @var{x}, which must be a @samp{reg} or
3438: @samp{mem} expression.
3439:
3440: One place this is used is in string instructions that store standard
3441: values into particular hard registers. It may not be worth the
1.1.1.2 ! root 3442: trouble to describe the values that are stored, but it is essential to
! 3443: inform the compiler that the registers will be altered, lest it
1.1 root 3444: attempt to keep data in them across the string instruction.
3445:
3446: @var{x} may also be null---a null C pointer, no expression at all.
3447: Such a @code{(clobber (null))} expression means that all memory
3448: locations must be presumed clobbered.
3449:
3450: Note that the machine description classifies certain hard registers as
3451: ``call-clobbered''. All function call instructions are assumed by
3452: default to clobber these registers, so there is no need to use
3453: @samp{clobber} expressions to indicate this fact. Also, each function
3454: call is assumed to have the potential to alter any memory location.
3455:
3456: @item (use @var{x})
1.1.1.2 ! root 3457: Represents the use of the value of @var{x}. It indicates that the
! 3458: value in @var{x} at this point in the program is needed, even though
! 3459: it may not be apparent why this is so. Therefore, the compiler will
! 3460: not attempt to delete instructions whose only effect is to store a
! 3461: value in @var{x}. @var{x} must be a @samp{reg} expression.
1.1 root 3462:
3463: @item (parallel [@var{x0} @var{x1} @dots{}])
3464: Represents several side effects performed in parallel. The square
3465: brackets stand for a vector; the operand of @samp{parallel} is a
3466: vector of expressions. @var{x0}, @var{x1} and so on are individual
3467: side effects---expressions of code @samp{set}, @samp{call},
1.1.1.2 ! root 3468: @samp{return}, @samp{clobber} or @samp{use}.@refill
1.1 root 3469:
1.1.1.2 ! root 3470: ``In parallel'' means that first all the values used in the individual
! 3471: side-effects are computed, and second all the actual side-effects are
! 3472: performed. For example,
1.1 root 3473:
3474: @example
3475: (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
3476: (set (mem:SI (reg:SI 1)) (reg:SI 1))])
3477: @end example
3478:
3479: @noindent
3480: says unambiguously that the values of hard register 1 and the memory
3481: location addressed by it are interchanged. In both places where
3482: @code{(reg:SI 1)} appears as a memory address it refers to the value
1.1.1.2 ! root 3483: in register 1 @emph{before} the execution of the instruction.
! 3484:
! 3485: @item (sequence [@var{insns} @dots{}])
! 3486: Represents a sequence of insns. Each of the @var{insns} that appears
! 3487: in the vector is suitable for appearing in the chain of insns, so it
! 3488: must be an @samp{insn}, @samp{jump_insn}, @samp{call_insn},
! 3489: @samp{code_label}, @samp{barrier} or @samp{note}.
! 3490:
! 3491: A @samp{sequence} RTX never appears in an actual insn. It represents
! 3492: the sequence of insns that result from a @samp{define_expand}
! 3493: @emph{before} those insns are passed to @code{emit_insn} to insert
! 3494: them in the chain of insns. When actually inserted, the individual
! 3495: sub-insns are separated out and the @samp{sequence} is forgotten.
1.1 root 3496: @end table
3497:
1.1.1.2 ! root 3498: Three expression codes appear in place of a side effect, as the body of an
! 3499: insn, though strictly speaking they do not describe side effects as such:
1.1 root 3500:
3501: @table @code
3502: @item (asm_input @var{s})
3503: Represents literal assembler code as described by the string @var{s}.
3504:
3505: @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
1.1.1.2 ! root 3506: Represents a table of jump addresses. The vector elements @var{lr0},
! 3507: etc., are @samp{label_ref} expressions. The mode @var{m} specifies
! 3508: how much space is given to each address; normally @var{m} would be
1.1 root 3509: @code{Pmode}.
3510:
3511: @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
3512: Represents a table of jump addresses expressed as offsets from
1.1.1.2 ! root 3513: @var{base}. The vector elements @var{lr0}, etc., are @samp{label_ref}
! 3514: expressions and so is @var{base}. The mode @var{m} specifies how much
! 3515: space is given to each address-difference.@refill
1.1 root 3516: @end table
3517:
1.1.1.2 ! root 3518: @node Incdec, Assembler, Side Effects, RTL
1.1 root 3519: @section Embedded Side-Effects on Addresses
3520:
3521: Four special side-effect expression codes appear as memory addresses.
3522:
3523: @table @code
3524: @item (pre_dec:@var{m} @var{x})
3525: Represents the side effect of decrementing @var{x} by a standard
3526: amount and represents also the value that @var{x} has after being
3527: decremented. @var{x} must be a @samp{reg} or @samp{mem}, but most
3528: machines allow only a @samp{reg}. @var{m} must be the machine mode
1.1.1.2 ! root 3529: for pointers on the machine in use. The amount @var{x} is decremented
1.1 root 3530: by is the length in bytes of the machine mode of the containing memory
3531: reference of which this expression serves as the address. Here is an
1.1.1.2 ! root 3532: example of its use:@refill
1.1 root 3533:
3534: @example
3535: (mem:DF (pre_dec:SI (reg:SI 39)))
3536: @end example
3537:
3538: @noindent
3539: This says to decrement pseudo register 39 by the length of a @code{DFmode}
3540: value and use the result to address a @code{DFmode} value.
3541:
3542: @item (pre_inc:@var{m} @var{x})
3543: Similar, but specifies incrementing @var{x} instead of decrementing it.
3544:
3545: @item (post_dec:@var{m} @var{x})
3546: Represents the same side effect as @samp{pre_decrement} but a different
3547: value. The value represented here is the value @var{x} has @i{before}
3548: being decremented.
3549:
3550: @item (post_inc:@var{m} @var{x})
3551: Similar, but specifies incrementing @var{x} instead of decrementing it.
3552: @end table
3553:
3554: These embedded side effect expressions must be used with care. Instruction
3555: patterns may not use them. Until the @samp{flow} pass of the compiler,
3556: they may occur only to represent pushes onto the stack. The @samp{flow}
3557: pass finds cases where registers are incremented or decremented in one
3558: instruction and used as an address shortly before or after; these cases are
3559: then transformed to use pre- or post-increment or -decrement.
3560:
3561: Explicit popping of the stack could be represented with these embedded
3562: side effect operators, but that would not be safe; the instruction
3563: combination pass could move the popping past pushes, thus changing
3564: the meaning of the code.
3565:
3566: An instruction that can be represented with an embedded side effect
3567: could also be represented using @samp{parallel} containing an additional
3568: @samp{set} to describe how the address register is altered. This is not
3569: done because machines that allow these operations at all typically
3570: allow them wherever a memory address is called for. Describing them as
3571: additional parallel stores would require doubling the number of entries
3572: in the machine description.
3573:
1.1.1.2 ! root 3574: @node Assembler, Insns, IncDec, RTL
! 3575: @section Assembler Instructions as Expressions
! 3576:
! 3577: The RTX code @samp{asm_operands} represents a value produced by a
! 3578: user-specified assembler instruction. It is used to represent
! 3579: an @code{asm} statement with arguments. An @code{asm} statement with
! 3580: a single output operand, like this:
! 3581:
! 3582: @example
! 3583: asm ("foo %1,%2,%0" : "a" (outputvar) : "g" (x + y), "di" (*z));
! 3584: @end example
! 3585:
! 3586: @noindent
! 3587: is represented using a single @samp{asm_operands} RTX which represents
! 3588: the value that is stored in @code{outputvar}:
! 3589:
! 3590: @example
! 3591: (set @var{rtx-for-outputvar}
! 3592: (asm_operands "foo %1,%2,%0" "a" 0
! 3593: [@var{rtx-for-addition-result} @var{rtx-for-*z}]
! 3594: [(asm_input:@var{m1} "g")
! 3595: (asm_input:@var{m2} "di")]))
! 3596: @end example
! 3597:
! 3598: @noindent
! 3599: Here the operands of the @samp{asm_operands} RTX are the assembler
! 3600: template string, the output-operand's constraint, the index-number of the
! 3601: output operand among the output operands specified, a vector of input
! 3602: operand RTX's, and a vector of input-operand modes and constraints. The
! 3603: mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
! 3604: @code{*z}.
! 3605:
! 3606: When an @code{asm} statement has multiple output values, its insn has
! 3607: several such @samp{set} RTX's inside of a @samp{parallel}. Each @samp{set}
! 3608: contains a @samp{asm_operands}; all of these share the same assembler
! 3609: template and vectors, but each contains the constraint for the respective
! 3610: output operand. They are also distinguished by the output-operand index
! 3611: number, which is 0, 1, @dots{} for successive output operands.
! 3612:
! 3613: @node Insns, Calls, Assembler, RTL
1.1 root 3614: @section Insns
3615:
3616: The RTL representation of the code for a function is a doubly-linked
3617: chain of objects called @dfn{insns}. Insns are expressions with
3618: special codes that are used for no other purpose. Some insns are
3619: actual instructions; others represent dispatch tables for @code{switch}
3620: statements; others represent labels to jump to or various sorts of
1.1.1.2 ! root 3621: declarative information.
1.1 root 3622:
1.1.1.2 ! root 3623: In addition to its own specific data, each insn must have a unique id-number
1.1 root 3624: that distinguishes it from all other insns in the current function, and
3625: chain pointers to the preceding and following insns. These three fields
3626: occupy the same position in every insn, independent of the expression code
3627: of the insn. They could be accessed with @code{XEXP} and @code{XINT},
3628: but instead three special macros are always used:
3629:
3630: @table @code
3631: @item INSN_UID (@var{i})
3632: Accesses the unique id of insn @var{i}.
3633:
3634: @item PREV_INSN (@var{i})
3635: Accesses the chain pointer to the insn preceding @var{i}.
3636: If @var{i} is the first insn, this is a null pointer.
3637:
3638: @item NEXT_INSN (@var{i})
3639: Accesses the chain pointer to the insn following @var{i}.
3640: If @var{i} is the last insn, this is a null pointer.
3641: @end table
3642:
3643: The @code{NEXT_INSN} and @code{PREV_INSN} pointers must always
3644: correspond: if @var{i} is not the first insn,
3645:
3646: @example
3647: NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
3648: @end example
3649:
3650: @noindent
3651: is always true.
3652:
3653: Every insn has one of the following six expression codes:
3654:
1.1.1.2 ! root 3655: @table @samp
1.1 root 3656: @item insn
3657: The expression code @samp{insn} is used for instructions that do not jump
3658: and do not do function calls. Insns with code @samp{insn} have four
3659: additional fields beyond the three mandatory ones listed above.
3660: These four are described in a table below.
3661:
3662: @item jump_insn
3663: The expression code @samp{jump_insn} is used for instructions that may jump
3664: (or, more generally, may contain @samp{label_ref} expressions).
3665: @samp{jump_insn} insns have the same extra fields as @samp{insn} insns,
3666: accessed in the same way.
3667:
3668: @item call_insn
3669: The expression code @samp{call_insn} is used for instructions that may do
3670: function calls. It is important to distinguish these instructions because
3671: they imply that certain registers and memory locations may be altered
3672: unpredictably.
3673:
3674: @samp{call_insn} insns have the same extra fields as @samp{insn} insns,
3675: accessed in the same way.
3676:
3677: @item code_label
3678: A @samp{code_label} insn represents a label that a jump insn can jump to.
3679: It contains one special field of data in addition to the three standard ones.
3680: It is used to hold the @dfn{label number}, a number that identifies this
3681: label uniquely among all the labels in the compilation (not just in the
3682: current function). Ultimately, the label is represented in the assembler
3683: output as an assembler label @samp{L@var{n}} where @var{n} is the label number.
3684:
3685: @item barrier
3686: Barriers are placed in the instruction stream after unconditional
3687: jump instructions to indicate that the jumps are unconditional.
3688: They contain no information beyond the three standard fields.
3689:
3690: @item note
3691: @samp{note} insns are used to represent additional debugging and
1.1.1.2 ! root 3692: declarative information. They contain two nonstandard fields, an
1.1 root 3693: integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3694: string accessed with @code{NOTE_SOURCE_FILE}.
3695:
3696: If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3697: position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3698: that the line came from. These notes control generation of line
3699: number data in the assembler output.
3700:
3701: Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3702: code with one of the following values (and @code{NOTE_SOURCE_FILE}
3703: must contain a null pointer):
3704:
3705: @table @code
3706: @item NOTE_INSN_DELETED
3707: Such a note is completely ignorable. Some passes of the compiler
3708: delete insns by altering them into notes of this kind.
3709:
3710: @item NOTE_INSN_BLOCK_BEG
3711: @itemx NOTE_INSN_BLOCK_END
3712: These types of notes indicate the position of the beginning and end
3713: of a level of scoping of variable names. They control the output
3714: of debugging information.
3715:
3716: @item NOTE_INSN_LOOP_BEG
3717: @itemx NOTE_INSN_LOOP_END
3718: These types of notes indicate the position of the beginning and end
3719: of a @code{while} or @code{for} loop. They enable the loop optimizer
3720: to find loops quickly.
3721: @end table
3722: @end table
3723:
3724: Here is a table of the extra fields of @samp{insn}, @samp{jump_insn}
3725: and @samp{call_insn} insns:
3726:
3727: @table @code
3728: @item PATTERN (@var{i})
3729: An expression for the side effect performed by this insn.
3730:
3731: @item REG_NOTES (@var{i})
3732: A list (chain of @samp{expr_list} expressions) giving information
3733: about the usage of registers in this insn. This list is set up by the
1.1.1.2 ! root 3734: flow analysis pass; it is a null pointer until then.
1.1 root 3735:
3736: @item LOG_LINKS (@var{i})
3737: A list (chain of @samp{insn_list} expressions) of previous ``related''
3738: insns: insns which store into registers values that are used for the
3739: first time in this insn. (An additional constraint is that neither a
3740: jump nor a label may come between the related insns). This list is
1.1.1.2 ! root 3741: set up by the flow analysis pass; it is a null pointer until then.
1.1 root 3742:
3743: @item INSN_CODE (@var{i})
3744: An integer that says which pattern in the machine description matches
3745: this insn, or -1 if the matching has not yet been attempted.
3746:
3747: Such matching is never attempted and this field is not used on an insn
3748: whose pattern consists of a single @samp{use}, @samp{clobber},
3749: @samp{asm}, @samp{addr_vec} or @samp{addr_diff_vec} expression.
3750: @end table
3751:
3752: The @code{LOG_LINKS} field of an insn is a chain of @samp{insn_list}
3753: expressions. Each of these has two operands: the first is an insn,
3754: and the second is another @samp{insn_list} expression (the next one in
3755: the chain). The last @samp{insn_list} in the chain has a null pointer
3756: as second operand. The significant thing about the chain is which
1.1.1.2 ! root 3757: insns appear in it (as first operands of @samp{insn_list}
1.1 root 3758: expressions). Their order is not significant.
3759:
3760: The @code{REG_NOTES} field of an insn is a similar chain but of
1.1.1.2 ! root 3761: @samp{expr_list} expressions instead of @samp{insn_list}. There are four
! 3762: kinds of register notes, which are distinguished by the machine mode of the
! 3763: @samp{expr_list}, which a register note is really understood as being an
! 3764: @code{enum reg_note}. The first operand @var{op} of the @samp{expr_list}
! 3765: is data whose meaning depends on the kind of note. Here are the four
! 3766: kinds:
1.1 root 3767:
3768: @table @code
3769: @item REG_DEAD
1.1.1.2 ! root 3770: The register @var{op} dies in this insn; that is to say, altering the
! 3771: value immediately after this insn would not affect the future behavior
! 3772: of the program.
1.1 root 3773:
3774: @item REG_INC
1.1.1.2 ! root 3775: The register @var{op} is incremented (or decremented; at this level
1.1 root 3776: there is no distinction) by an embedded side effect inside this insn.
1.1.1.2 ! root 3777: This means it appears in a @code{POST_INC}, @code{PRE_INC},
! 3778: @code{POST_DEC} or @code{PRE_DEC} RTX.
1.1 root 3779:
1.1.1.2 ! root 3780: @item REG_EQUIV
! 3781: The register that is set by this insn will be equal to @var{op} at run
! 3782: time, and could validly be replaced in all its occurrences by
! 3783: @var{op}. (``Validly'' here refers to the data flow of the program;
! 3784: simple replacement may make some insns invalid.)
! 3785:
! 3786: The value which the insn explicitly copies into the register may look
! 3787: different from @var{op}, but they will be equal at run time.
! 3788:
! 3789: For example, when a constant is loaded into a register that is never
! 3790: assigned any other value, this kind of note is used.
! 3791:
! 3792: When a parameter is copied into a pseudo-register at entry to a function,
! 3793: a note of this kind records that the register is equivalent to the stack
! 3794: slot where the parameter was passed. Although in this case the register
! 3795: may be set by other insns, it is still valid to replace the register
! 3796: by the stack slot throughout the function.
! 3797:
! 3798: @item REG_EQUAL
! 3799: The register that is set by this insn will be equal to @var{op} at run
! 3800: time at the end of this insn (but not necessarily elsewhere in the
! 3801: function).
! 3802:
! 3803: The RTX @var{op} is typically an arithmetic expression. For example,
! 3804: when a sequence of insns such as a library call is used to perform an
! 3805: arithmetic operation, this kind of note is attached to the insn that
! 3806: produces or copies the final value. It tells the CSE pass how to
! 3807: think of that value.
! 3808:
! 3809: @item REG_RETVAL
! 3810: This insn copies the value of a library call, and @var{op} is the
! 3811: first insn that was generated to set up the arguments for the library
! 3812: call.
! 3813:
! 3814: Flow analysis uses this note to delete all of a library call whose
! 3815: result is dead.
1.1 root 3816:
3817: @item REG_WAS_0
1.1.1.2 ! root 3818: The register @var{op} contained zero before this insn. You can rely
1.1 root 3819: on this note if it is present; its absence implies nothing.
3820: @end table
3821:
3822: (The only difference between the expression codes @samp{insn_list} and
3823: @samp{expr_list} is that the first operand of an @samp{insn_list} is
3824: assumed to be an insn and is printed in debugging dumps as the insn's
3825: unique id; the first operand of an @samp{expr_list} is printed in the
3826: ordinary way as an expression.)
3827:
1.1.1.2 ! root 3828: @node Calls, Sharing, Insns, RTL
! 3829: @section RTL Representation of Function-Call Insns
! 3830:
! 3831: Insns that call subroutines have the RTL expression code @samp{call_insn}.
! 3832: These insns must satisfy special rules, and their bodies must use a special
! 3833: RTL expression code, @samp{call}.
! 3834:
! 3835: A @samp{call} expression has two operands, as follows:
! 3836:
! 3837: @example
! 3838: (call @var{nbytes} (mem:@var{fm} @var{addr}))
! 3839: @end example
! 3840:
! 3841: @noindent
! 3842: Here @var{nbytes} is an operand that represents the number of bytes of
! 3843: argument data being passed to the subroutine, @var{fm} is a machine mode
! 3844: (which must equal as the definition of the @code{FUNCTION_MODE} macro in
! 3845: the machine description) and @var{addr} represents the address of the
! 3846: subroutine.
! 3847:
! 3848: For a subroutine that returns no value, the @samp{call} RTX as shown above
! 3849: is the entire body of the insn.
! 3850:
! 3851: For a subroutine that returns a value whose mode is not @code{BLKmode},
! 3852: the value is returned in a hard register. If this register's number is
! 3853: @var{r}, then the body of the call insn looks like this:
! 3854:
! 3855: @example
! 3856: (set (reg:@var{m} @var{r})
! 3857: (call @var{nbytes} (mem:@var{fm} @var{addr})))
! 3858: @end example
! 3859:
! 3860: @noindent
! 3861: This RTL expression makes it clear (to the optimizer passes) that the
! 3862: appropriate register receives a useful value in this insn.
! 3863:
! 3864: Immediately after RTL generation, if the value of the subroutine is
! 3865: actually used, this call insn is always followed closely by an insn which
! 3866: refers to the register @var{r}. The following insn has one of two forms.
! 3867: Either it copies the value into a pseudo-register, like this:
! 3868:
! 3869: @example
! 3870: (set (reg:@var{m} @var{p}) (reg:@var{m} @var{r}))
! 3871: @end example
! 3872:
! 3873: @noindent
! 3874: or (in the case where the calling function will simply return whatever
! 3875: value the call produced, and no operation is needed to do this):
! 3876:
! 3877: @example
! 3878: (use (reg:@var{m} @var{r}))
! 3879: @end example
! 3880:
! 3881: @noindent
! 3882: Between the call insn and this insn there may intervene only a
! 3883: stack-adjustment insn (and perhaps some @samp{note} insns).
! 3884:
! 3885: When a subroutine returns a @code{BLKmode} value, it is handled by
! 3886: passing to the subroutine the address of a place to store the value.
! 3887: So the call insn itself does not ``return'' any value, and it has the
! 3888: same RTL form as a call that returns nothing.
! 3889:
! 3890: @node Sharing,, Calls, RTL
1.1 root 3891: @section Structure Sharing Assumptions
3892:
3893: The compiler assumes that certain kinds of RTL expressions are unique;
3894: there do not exist two distinct objects representing the same value.
3895: In other cases, it makes an opposite assumption: that no RTL expression
3896: object of a certain kind appears in more than one place in the
3897: containing structure.
3898:
3899: These assumptions refer to a single function; except for the RTL
3900: objects that describe global variables and external functions,
3901: no RTL objects are common to two functions.
3902:
3903: @itemize @bullet
3904: @item
3905: Each pseudo-register has only a single @samp{reg} object to represent it,
3906: and therefore only a single machine mode.
3907:
3908: @item
3909: For any symbolic label, there is only one @samp{symbol_ref} object
3910: referring to it.
3911:
3912: @item
3913: There is only one @samp{const_int} expression with value zero,
3914: and only one with value one.
3915:
3916: @item
3917: There is only one @samp{pc} expression.
3918:
3919: @item
3920: There is only one @samp{cc0} expression.
3921:
3922: @item
3923: There is only one @samp{const_double} expression with mode
3924: @code{SFmode} and value zero, and only one with mode @code{DFmode} and
3925: value zero.
3926:
3927: @item
1.1.1.2 ! root 3928: No @samp{label_ref} appears in more than one place in the RTL
! 3929: structure; in other words, it is safe to do a tree-walk of all the
! 3930: insns in the function and assume that each time a @samp{label_ref} is
! 3931: seen it is distinct from all others that are seen.
1.1 root 3932:
3933: @item
1.1.1.2 ! root 3934: Only one @samp{mem} object is normally created for each static
! 3935: variable or stack slot, so these objects are frequently shared in all
! 3936: the places they appear. However, separate but equal objects for these
! 3937: variables are occasionally made.
! 3938:
! 3939: @item
! 3940: No RTL object appears in more than one place in the RTL structure
! 3941: except as described above. Many passes of the compiler rely on this
! 3942: by assuming that they can modify RTL objects in place without unwanted
! 3943: side-effects on other insns.
! 3944:
! 3945: @item
! 3946: During initial RTL generation, shared structure is freely introduced.
! 3947: After all the RTL for a function has been generated, all shared
! 3948: structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
! 3949: after which the above rules are guaranteed to be followed.
! 3950:
! 3951: @item
! 3952: During the combiner pass, shared structure with an insn can exist
! 3953: temporarily. However, the shared structure is copied before the
! 3954: combiner is finished with the insn. This is done by
! 3955: @code{copy_substitutions} in @samp{combine.c}.
1.1 root 3956: @end itemize
3957:
3958: @node Machine Desc, Machine Macros, RTL, Top
3959: @chapter Machine Descriptions
3960:
3961: A machine description has two parts: a file of instruction patterns
3962: (@file{.md} file) and a C header file of macro definitions.
3963:
3964: The @file{.md} file for a target machine contains a pattern for each
3965: instruction that the target machine supports (or at least each instruction
3966: that is worth telling the compiler about). It may also contain comments.
3967: A semicolon causes the rest of the line to be a comment, unless the semicolon
3968: is inside a quoted string.
3969:
3970: See the next chapter for information on the C header file.
3971:
3972: @menu
3973: * Patterns:: How to write instruction patterns.
1.1.1.2 ! root 3974: * Example:: An explained example of a @samp{define_insn} pattern.
! 3975: * RTL Template:: The RTL template defines what insns match a pattern.
! 3976: * Output Template:: The output template says how to make assembler code
! 3977: from such an insn.
! 3978: * Output Statement:: For more generality, write C code to output
! 3979: the assembler code.
1.1 root 3980: * Constraints:: When not all operands are general operands.
3981: * Standard Names:: Names mark patterns to use for code generation.
1.1.1.2 ! root 3982: * Pattern Ordering:: When the order of patterns makes a difference.
1.1 root 3983: * Dependent Patterns:: Having one pattern may make you need another.
1.1.1.2 ! root 3984: * Jump Patterns:: Special considerations for patterns for jump insns.
! 3985: * Peephole Definitions::Defining machine-specific peephole optimizations.
! 3986: * Expander Definitions::Generating a sequence of several RTL insns
! 3987: for a standard operation.
1.1 root 3988: @end menu
3989:
3990: @node Patterns, Example, Machine Desc, Machine Desc
1.1.1.2 ! root 3991: @section Everything about Instruction Patterns
1.1 root 3992:
3993: Each instruction pattern contains an incomplete RTL expression, with pieces
3994: to be filled in later, operand constraints that restrict how the pieces can
3995: be filled in, and an output pattern or C code to generate the assembler
3996: output, all wrapped up in a @samp{define_insn} expression.
3997:
1.1.1.2 ! root 3998: A @samp{define_insn} is an RTL expression containing four operands:
1.1 root 3999:
4000: @enumerate
4001: @item
4002: An optional name. The presence of a name indicate that this instruction
4003: pattern can perform a certain standard job for the RTL-generation
4004: pass of the compiler. This pass knows certain names and will use
4005: the instruction patterns with those names, if the names are defined
4006: in the machine description.
4007:
4008: The absence of a name is indicated by writing an empty string
4009: where the name should go. Nameless instruction patterns are never
4010: used for generating RTL code, but they may permit several simpler insns
4011: to be combined later on.
4012:
4013: Names that are not thus known and used in RTL-generation have no
4014: effect; they are equivalent to no name at all.
4015:
4016: @item
1.1.1.2 ! root 4017: The @dfn{RTL template} (@pxref{RTL Template}) is a vector of
! 4018: incomplete RTL expressions which show what the instruction should look
! 4019: like. It is incomplete because it may contain @samp{match_operand}
! 4020: and @samp{match_dup} expressions that stand for operands of the
1.1 root 4021: instruction.
4022:
4023: If the vector has only one element, that element is what the
4024: instruction should look like. If the vector has multiple elements,
4025: then the instruction looks like a @samp{parallel} expression
4026: containing that many elements as described.
4027:
4028: @item
4029: A condition. This is a string which contains a C expression that is
4030: the final test to decide whether an insn body matches this pattern.
4031:
4032: For a named pattern, the condition (if present) may not depend on
4033: the data in the insn being matched, but only the target-machine-type
4034: flags. The compiler needs to test these conditions during
4035: initialization in order to learn exactly which named instructions are
4036: available in a particular run.
4037:
4038: For nameless patterns, the condition is applied only when matching an
4039: individual insn, and only after the insn has matched the pattern's
4040: recognition template. The insn's operands may be found in the vector
4041: @code{operands}.
4042:
4043: @item
1.1.1.2 ! root 4044: The @dfn{output template}: a string that says how to output matching
! 4045: insns as assembler code. @samp{%} in this string specifies where
! 4046: to substitute the value of an operand. @xref{Output Template}.
! 4047:
! 4048: When simple substitution isn't general enough, you can specify a piece
! 4049: of C code to compute the output. @xref{Output Statement}.
! 4050: @end enumerate
! 4051:
! 4052: @node Example, RTL Template, Patterns, Machine Desc
! 4053: @section Example of @samp{define_insn}
! 4054:
! 4055: Here is an actual example of an instruction pattern, for the 68000/68020.
! 4056:
! 4057: @example
! 4058: (define_insn "tstsi"
! 4059: [(set (cc0)
! 4060: (match_operand:SI 0 "general_operand" "rm"))]
! 4061: ""
! 4062: "*
! 4063: @{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
! 4064: return \"tstl %0\";
! 4065: return \"cmpl #0,%0\"; @}")
! 4066: @end example
1.1 root 4067:
1.1.1.2 ! root 4068: This is an instruction that sets the condition codes based on the value of
! 4069: a general operand. It has no condition, so any insn whose RTL description
! 4070: has the form shown may be handled according to this pattern. The name
! 4071: @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
! 4072: pass that, when it is necessary to test such a value, an insn to do so
! 4073: can be constructed using this pattern.
1.1 root 4074:
1.1.1.2 ! root 4075: The output control string is a piece of C code which chooses which
! 4076: output template to return based on the kind of operand and the specific
! 4077: type of CPU for which code is being generated.
1.1 root 4078:
1.1.1.2 ! root 4079: @samp{"rm"} is an operand constraint. Its meaning is explained below.
1.1 root 4080:
1.1.1.2 ! root 4081: @node RTL Template, Output Template, Example, Machine Desc
! 4082: @section RTL Template for Generating and Recognizing Insns
1.1 root 4083:
1.1.1.2 ! root 4084: The RTL template is used to define which insns match the particular pattern
! 4085: and how to find their operands. For named patterns, the RTL template also
! 4086: says how to construct an insn from specified operands.
! 4087:
! 4088: Construction involves substituting specified operands into a copy of the
! 4089: template. Matching involves determining the values that serve as the
! 4090: operands in the insn being matched. Both of these activities are
! 4091: controlled by special expression types that direct matching and
! 4092: substitution of the operands.
1.1 root 4093:
4094: @table @code
4095: @item (match_operand:@var{m} @var{n} @var{testfn} @var{constraint})
4096: This expression is a placeholder for operand number @var{n} of
4097: the insn. When constructing an insn, operand number @var{n}
4098: will be substituted at this point. When matching an insn, whatever
4099: appears at this position in the insn will be taken as operand
4100: number @var{n}; but it must satisfy @var{testfn} or this instruction
4101: pattern will not match at all.
4102:
4103: Operand numbers must be chosen consecutively counting from zero in
4104: each instruction pattern. There may be only one @samp{match_operand}
4105: expression in the pattern for each expression number, and they must
4106: appear in order of increasing expression number.
4107:
4108: @var{testfn} is a string that is the name of a C function that accepts
4109: two arguments, a machine mode and an expression. During matching,
4110: the function will be called with @var{m} as the mode argument
4111: and the putative operand as the other argument. If it returns zero,
4112: this instruction pattern fails to match. @var{testfn} may be
4113: an empty string; then it means no test is to be done on the operand.
4114:
4115: Most often, @var{testfn} is @code{"general_operand"}. It checks
4116: that the putative operand is either a constant, a register or a
4117: memory reference, and that it is valid for mode @var{m}.
4118:
1.1.1.2 ! root 4119: For an operand that must be a register, @var{testfn} should be
! 4120: @code{"register_operand"}. This prevents GNU CC from creating insns
! 4121: that have memory references in these operands, insns which would only
! 4122: have to be taken apart in the reload pass.
! 4123:
! 4124: For an operand that must be a constant, either @var{testfn} should be
! 4125: @code{"immediate_operand"}, or the instruction pattern's extra condition
! 4126: should check for constants, or both.
! 4127:
! 4128: @var{constraint} is explained later (@pxref{Constraints}).
1.1 root 4129:
4130: @item (match_dup @var{n})
4131: This expression is also a placeholder for operand number @var{n}.
4132: It is used when the operand needs to appear more than once in the
4133: insn.
4134:
4135: In construction, @samp{match_dup} behaves exactly like
1.1.1.2 ! root 4136: @samp{match_operand}: the operand is substituted into the insn being
1.1 root 4137: constructed. But in matching, @samp{match_dup} behaves differently.
4138: It assumes that operand number @var{n} has already been determined by
1.1.1.2 ! root 4139: a @samp{match_operand} appearing earlier in the recognition template,
1.1 root 4140: and it matches only an identical-looking expression.
4141:
4142: @item (address (match_operand:@var{m} @var{n} "address_operand" ""))
4143: This complex of expressions is a placeholder for an operand number
4144: @var{n} in a ``load address'' instruction: an operand which specifies
4145: a memory location in the usual way, but for which the actual operand
4146: value used is the address of the location, not the contents of the
4147: location.
4148:
4149: @samp{address} expressions never appear in RTL code, only in machine
4150: descriptions. And they are used only in machine descriptions that do
4151: not use the operand constraint feature. When operand constraints are
4152: in use, the letter @samp{p} in the constraint serves this purpose.
4153:
4154: @var{m} is the machine mode of the @emph{memory location being
4155: addressed}, not the machine mode of the address itself. That mode is
4156: always the same on a given target machine (it is @code{Pmode}, which
4157: normally is @code{SImode}), so there is no point in mentioning it;
4158: thus, no machine mode is written in the @samp{address} expression. If
4159: some day support is added for machines in which addresses of different
4160: kinds of objects appear differently or are used differently (such as
4161: the PDP-10), different formats would perhaps need different machine
4162: modes and these modes might be written in the @samp{address}
4163: expression.
4164: @end table
4165:
1.1.1.2 ! root 4166: @node Output Template, Output Statement, RTL Template, Machine Desc
! 4167: @section Output Templates and Operand Substitution
1.1 root 4168:
1.1.1.2 ! root 4169: The @dfn{output template} is a string which specifies how to output
! 4170: the assembler code for an instruction pattern. Most of the template
! 4171: is a fixed string which is output literally. The character @samp{%}
! 4172: is used to specify where to substitute an operand; it can also be
! 4173: used to identify places different variants of the assembler require
! 4174: different syntax.
! 4175:
! 4176: In the simplest case, a @samp{%} followed by a digit @var{n} says to output
! 4177: operand @var{n} at that point in the string.
! 4178:
! 4179: @samp{%} followed by a letter and a digit says to output an operand in an
! 4180: alternate fashion. Four letters have standard, built-in meanings described
! 4181: below. The machine description macro @code{PRINT_OPERAND} can define
! 4182: additional letters with nonstandard meanings.
! 4183:
! 4184: @samp{%c@var{digit}} can be used to substitute an operand that is a
! 4185: constant value without the syntax that normally indicates an immediate
! 4186: operand.
! 4187:
! 4188: @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
! 4189: the constant is negated before printing.
! 4190:
! 4191: @samp{%a@var{digit}} can be used to substitute an operand as if it were a
! 4192: memory reference, with the actual operand treated as the address. This may
! 4193: be useful when outputting a ``load address'' instruction, because often the
! 4194: assembler syntax for such an instruction requires you to write the operand
! 4195: as if it were a memory reference.
! 4196:
! 4197: @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
! 4198: instruction.
! 4199:
! 4200: @samp{%} followed by a punctuation character specifies a substitution that
! 4201: does not use an operand. Only one case is standard: @samp{%%} outputs a
! 4202: @samp{%} into the assembler code. Other nonstandard cases can be
! 4203: defined in the @code{PRINT_OPERAND} macro.
! 4204:
! 4205: The template may generate multiple assembler instructions. Write the text
! 4206: for the instructions, with @samp{\;} between them.
! 4207:
! 4208: When the RTL contains two operand which are required by constraint to match
! 4209: each other, the output template must refer only to the lower-numbered operand.
! 4210: Matching operands are not always identical, and the rest of the compiler
! 4211: arranges to put the proper RTL expression for printing into the lower-numbered
! 4212: operand.
! 4213:
! 4214: One use of nonstandard letters or punctuation following @samp{%} is to
! 4215: distinguish between different assembler languages for the same machine; for
! 4216: example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax
! 4217: requires periods in most opcode names, while MIT syntax does not. For
! 4218: example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
! 4219: syntax. The same file of patterns is used for both kinds of output syntax,
! 4220: but the character sequence @samp{%.} is used in each place where Motorola
! 4221: syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax
! 4222: defines the sequence to output a period; the macro for MIT syntax defines
! 4223: it to do nothing.
! 4224:
! 4225: @node Output Statement, Constraints, Output Template, Machine Desc
! 4226: @section C Statements for Generating Assembler Output
! 4227:
! 4228: Often a single fixed template string cannot produce correct and efficient
! 4229: assembler code for all the cases that are recognized by a single
! 4230: instruction pattern. For example, the opcodes may depend on the kinds of
! 4231: operands; or some unfortunate combinations of operands may require extra
! 4232: machine instructions.
! 4233:
! 4234: If the output control string starts with a @samp{*}, then it is not an
! 4235: output template but rather a piece of C program that should compute a
! 4236: template. It should execute a @code{return} statement to return the
! 4237: template-string you want. Most such templates use C string literals, which
! 4238: require doublequote characters to delimit them. To include these
! 4239: doublequote characters in the string, prefix each one with @samp{\}.
! 4240:
! 4241: The operands may be found in the array @code{operands}, whose C data type
! 4242: is @code{rtx []}.
! 4243:
! 4244: It is possible to output an assembler instruction and then go on to output
! 4245: or compute more of them, using the subroutine @code{output_asm_insn}. This
! 4246: receives two arguments: a template-string and a vector of operands. The
! 4247: vector may be @code{operands}, or it may be another array of @code{rtx}
! 4248: that you declare locally and initialize yourself.
! 4249:
! 4250: When an insn pattern has multiple alternatives in its constraints, often
! 4251: the appearance of the assembler code determined mostly by which alternative
! 4252: was matched. When this is so, the C code can test the variable
! 4253: @code{which_alternative}, which is the ordinal number of the alternative
! 4254: that was actually satisfied (0 for the first, 1 for the second alternative,
! 4255: etc.).
! 4256:
! 4257: For example, suppose there are two opcodes for storing zero, @samp{clrreg}
! 4258: for registers and @samp{clrmem} for memory locations. Here is how
! 4259: a pattern could use @code{which_alternative} to choose between them:
1.1 root 4260:
4261: @example
1.1.1.2 ! root 4262: (define_insn ""
! 4263: [(set (match_operand:SI 0 "general_operand" "r,m")
! 4264: (const_int 0))]
1.1 root 4265: ""
4266: "*
1.1.1.2 ! root 4267: return (which_alternative == 0
! 4268: ? \"clrreg %0\" : \"clrmem %0\");
! 4269: ")
1.1 root 4270: @end example
4271:
1.1.1.2 ! root 4272: @node Constraints, Standard Names, Output Statement, Machine Desc
1.1 root 4273: @section Operand Constraints
4274:
4275: Each @samp{match_operand} in an instruction pattern can specify a
4276: constraint for the type of operands allowed. Constraints can say whether
4277: an operand may be in a register, and which kinds of register; whether the
4278: operand can be a memory reference, and which kinds of address; whether the
4279: operand may be an immediate constant, and which possible values it may
4280: have. Constraints can also require two operands to match.
4281:
4282: @menu
4283: * Simple Constraints:: Basic use of constraints.
1.1.1.2 ! root 4284: * Multi-Alternative:: When an insn has two alternative constraint-patterns.
1.1 root 4285: * Class Preferences:: Constraints guide which hard register to put things in.
4286: * Modifiers:: More precise control over effects of constraints.
4287: * No Constraints:: Describing a clean machine without constraints.
4288: @end menu
4289:
4290: @node Simple Constraints, Multi-Alternative, Constraints, Constraints
4291: @subsection Simple Constraints
4292:
4293: The simplest kind of constraint is a string full of letters, each of
4294: which describes one kind of operand that is permitted. Here are
4295: the letters that are allowed:
4296:
1.1.1.2 ! root 4297: @table @asis
! 4298: @item @samp{m}
1.1 root 4299: A memory operand is allowed, with any kind of address that the machine
4300: supports in general.
4301:
1.1.1.2 ! root 4302: @item @samp{o}
! 4303: A memory operand is allowed, but only if the address is
! 4304: @dfn{offsetable}. This means that adding a small integer (actually,
! 4305: the width in bytes of the operand, as determined by its machine mode)
! 4306: may be added to the address and the result is also a valid memory
! 4307: address.
! 4308:
! 4309: For example, an address which is constant is offsetable; so is an
! 4310: address that is the sum of a register and a constant (as long as a
! 4311: slightly larger constant is also within the range of address-offsets
! 4312: supported by the machine); but an autoincrement or autodecrement
! 4313: address is not offsetable. More complicated indirect/indexed
! 4314: addresses may or may not be offsetable depending on the other
! 4315: addressing modes that the machine supports.
! 4316:
! 4317: Note that in an output operand which can be matched by another
! 4318: operand, the constraint letter @samp{o} is valid only when accompanied
! 4319: by both @samp{<} (if the target machine has predecrement addressing)
! 4320: and @samp{>} (if the target machine has preincrement addressing).
1.1 root 4321:
1.1.1.2 ! root 4322: @item @samp{<}
1.1 root 4323: A memory operand with autodecrement addressing (either predecrement or
4324: postdecrement) is allowed.
4325:
1.1.1.2 ! root 4326: @item @samp{>}
1.1 root 4327: A memory operand with autoincrement addressing (either preincrement or
4328: postincrement) is allowed.
4329:
1.1.1.2 ! root 4330: @item @samp{r}
! 4331: A register operand is allowed provided that it is in a general
! 4332: register.
1.1 root 4333:
1.1.1.2 ! root 4334: @item @samp{d}, @samp{a}, @samp{f}, @dots{}
1.1 root 4335: Other letters can be defined in machine-dependent fashion to stand for
4336: particular classes of registers. @samp{d}, @samp{a} and @samp{f} are
1.1.1.2 ! root 4337: defined on the 68000/68020 to stand for data, address and floating
! 4338: point registers.
1.1 root 4339:
1.1.1.2 ! root 4340: @item @samp{i}
1.1 root 4341: An immediate integer operand (one with constant value) is allowed.
1.1.1.2 ! root 4342: This includes symbolic constants whose values will be known only at
! 4343: assembly time.
1.1 root 4344:
1.1.1.2 ! root 4345: @item @samp{n}
! 4346: An immediate integer operand with a known numeric value is allowed.
! 4347: Many systems cannot support assembly-time constants for operands less
! 4348: than a word wide. Constraints for these operands should use @samp{n}
! 4349: rather than @samp{i}.
! 4350:
! 4351: @item @samp{I}, @samp{J}, @samp{K}, @dots{}
! 4352: Other letters in the range @samp{I} through @samp{M} may be defined in
! 4353: a machine-dependent fashion to permit immediate integer operands with
! 4354: explicit integer values in specified ranges. For example, on the
! 4355: 68000, @samp{I} is defined to stand for the range of values 1 to 8.
! 4356: This is the range permitted as a shift count in the shift
! 4357: instructions.
1.1 root 4358:
1.1.1.2 ! root 4359: @item @samp{F}
1.1 root 4360: An immediate floating operand (expression code @samp{const_double}) is
4361: allowed.
4362:
1.1.1.2 ! root 4363: @item @samp{G}, @samp{H}
1.1 root 4364: @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
4365: permit immediate floating operands in particular ranges of values.
4366:
1.1.1.2 ! root 4367: @item @samp{s}
1.1 root 4368: An immediate integer operand whose value is not an explicit integer is
1.1.1.2 ! root 4369: allowed.
! 4370:
! 4371: This might appear strange; if an insn allows a constant operand with a
! 4372: value not known at compile time, it certainly must allow any known
1.1 root 4373: value. So why use @samp{s} instead of @samp{i}? Sometimes it allows
1.1.1.2 ! root 4374: better code to be generated.
! 4375:
! 4376: For example, on the 68000 in a fullword instruction it is possible to
! 4377: use an immediate operand; but if the immediate value is between -32
! 4378: and 31, better code results from loading the value into a register and
! 4379: using the register. This is because the load into the register can be
! 4380: done with a @samp{moveq} instruction. We arrange for this to happen
! 4381: by defining the letter @samp{K} to mean ``any integer outside the
! 4382: range -32 to 31'', and then specifying @samp{Ks} in the operand
1.1 root 4383: constraints.
4384:
1.1.1.2 ! root 4385: @item @samp{g}
1.1 root 4386: Any register, memory or immediate integer operand is allowed, except for
4387: registers that are not general registers.
4388:
1.1.1.2 ! root 4389: @item @samp{@var{n}} (a digit)
! 4390: An operand that matches operand number @var{n} is allowed.
1.1 root 4391: If a digit is used together with letters, the digit should come last.
4392:
1.1.1.2 ! root 4393: This is called a @dfn{matching constraint} and what it really means is
! 4394: that the assembler has only a single operand that fills two roles
! 4395: considered separate in the RTL insn. For example, an add insn has two
! 4396: input operands and one output operand in the RTL, but on most machines
! 4397: an add instruction really has only two operands, one of them an
! 4398: input-output operand.
! 4399:
! 4400: Matching constraints work only in circumstances like that add insn.
! 4401: More precisely, the matching constraint must appear in an input-only
! 4402: operand and the operand that it matches must be an output-only operand
! 4403: with a lower number.
! 4404:
! 4405: For operands to match in a particular case usually means that they
! 4406: are identical-looking RTL expressions. But in a few special cases
! 4407: specific kinds of dissimilarity are allowed. For example, @code{*x}
! 4408: as an input operand will match @code{*x++} as an output operand.
! 4409: For proper results in such cases, the output template should always
! 4410: use the output-operand's number when printing the operand.
! 4411:
! 4412: @item @samp{p}
1.1 root 4413: An operand that is a valid memory address is allowed. This is
4414: for ``load address'' and ``push address'' instructions.
4415:
4416: If @samp{p} is used in the constraint, the test-function in the
4417: @samp{match_operand} must be @code{address_operand}.
4418: @end table
4419:
4420: In order to have valid assembler code, each operand must satisfy
4421: its constraint. But a failure to do so does not prevent the pattern
4422: from applying to an insn. Instead, it directs the compiler to modify
1.1.1.2 ! root 4423: the code so that the constraint will be satisfied. Usually this is
1.1 root 4424: done by copying an operand into a register.
4425:
4426: Contrast, therefore, the two instruction patterns that follow:
4427:
4428: @example
4429: (define_insn ""
4430: [(set (match_operand:SI 0 "general_operand" "r")
4431: (plus:SI (match_dup 0)
4432: (match_operand:SI 1 "general_operand" "r")))]
4433: ""
4434: "@dots{}")
4435: @end example
4436:
4437: @noindent
4438: which has two operands, one of which must appear in two places, and
4439:
4440: @example
4441: (define_insn ""
4442: [(set (match_operand:SI 0 "general_operand" "r")
4443: (plus:SI (match_operand:SI 1 "general_operand" "0")
4444: (match_operand:SI 2 "general_operand" "r")))]
4445: ""
4446: "@dots{}")
4447: @end example
4448:
4449: @noindent
4450: which has three operands, two of which are required by a constraint to be
4451: identical. If we are considering an insn of the form
4452:
4453: @example
4454: (insn @var{n} @var{prev} @var{next}
4455: (set (reg:SI 3)
4456: (plus:SI (reg:SI 6) (reg:SI 109)))
4457: @dots{})
4458: @end example
4459:
4460: @noindent
4461: the first pattern would not apply at all, because this insn does not
4462: contain two identical subexpressions in the right place. The pattern would
4463: say, ``That does not look like an add instruction; try other patterns.''
4464: The second pattern would say, ``Yes, that's an add instruction, but there
4465: is something wrong with it.'' It would direct the reload pass of the
4466: compiler to generate additional insns to make the constraint true. The
4467: results might look like this:
4468:
4469: @example
4470: (insn @var{n2} @var{prev} @var{n}
4471: (set (reg:SI 3) (reg:SI 6))
4472: @dots{})
4473:
4474: (insn @var{n} @var{n2} @var{next}
4475: (set (reg:SI 3)
4476: (plus:SI (reg:SI 3) (reg:SI 109)))
4477: @dots{})
4478: @end example
4479:
4480: Because insns that don't fit the constraints are fixed up by loading
4481: operands into registers, every instruction pattern's constraints must
4482: permit the case where all the operands are in registers. It need not
4483: permit all classes of registers; the compiler knows how to copy registers
4484: into other registers of the proper class in order to make an instruction
4485: valid. But if no registers are permitted, the compiler will be stymied: it
4486: does not know how to save a register in memory in order to make an
4487: instruction valid. Instruction patterns that reject registers can be
4488: made valid by attaching a condition-expression that refuses to match
4489: an insn at all if the crucial operand is a register.
4490:
4491: @node Multi-Alternative, Class Preferences, Simple Constraints, Constraints
4492: @subsection Multiple Alternative Constraints
4493:
4494: Sometimes a single instruction has multiple alternative sets of possible
4495: operands. For example, on the 68000, a logical-or instruction can combine
4496: register or an immediate value into memory, or it can combine any kind of
4497: operand into a register; but it cannot combine one memory location into
4498: another.
4499:
4500: These constraints are represented as multiple alternatives. An alternative
4501: can be described by a series of letters for each operand. The overall
4502: constraint for an operand is made from the letters for this operand
4503: from the first alternative, a comma, the letters for this operand from
4504: the second alternative, a comma, and so on until the last alternative.
4505: Here is how it is done for fullword logical-or on the 68000:
4506:
4507: @example
4508: (define_insn "iorsi3"
4509: [(set (match_operand:SI 0 "general_operand" "=%m,d")
1.1.1.2 ! root 4510: (ior:SI (match_operand:SI 1 "general_operand" "0,0")
! 4511: (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
1.1 root 4512: @dots{})
4513: @end example
4514:
4515: The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
4516: operand 1 (meaning it must match operand 0), and @samp{dKs} for operand 2.
4517: The second alternative has @samp{d} (data register) for operand 0, @samp{0}
4518: for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and @samp{%} in
4519: the constraint for operand 0 are not part of any alternative; their meaning
4520: is explained in the next section.
4521:
4522: If all the operands fit any one alternative, the instruction is valid.
4523: Otherwise, for each alternative, the compiler counts how many instructions
4524: must be added to copy the operands so that that alternative applies.
4525: The alternative requiring the least copying is chosen. If two alternatives
4526: need the same amount of copying, the one that comes first is chosen.
4527: These choices can be altered with the @samp{?} and @samp{!} characters:
4528:
4529: @table @samp
4530: @item ?
4531: Disparage slightly the alternative that the @samp{?} appears in,
4532: as a choice when no alternative applies exactly. The compiler regards
4533: this alternative as one unit more costly for each @samp{?} that appears
4534: in it.
4535:
4536: @item !
4537: Disparage severely the alternative that the @samp{!} appears in.
4538: When operands must be copied into registers, the compiler will
4539: never choose this alternative as the one to strive for.
4540: @end table
4541:
1.1.1.2 ! root 4542: When an insn pattern has multiple alternatives in its constraints,
! 4543: often the appearance of the assembler code determined mostly by which
! 4544: alternative was matched. When this is so, the C code for writing the
! 4545: assembler code can use the variable @code{which_alternative}, which is
! 4546: the ordinal number of the alternative that was actually satisfied
! 4547: (0 for the first, 1 for the second alternative, etc.). For example:
! 4548:
! 4549: @example
! 4550: (define_insn ""
! 4551: [(set (match_operand:SI 0 "general_operand" "r,m")
! 4552: (const_int 0))]
! 4553: ""
! 4554: "*
! 4555: return (which_alternative == 0
! 4556: ? \"clrreg %0\" : \"clrmem %0\");
! 4557: ")
! 4558: @end example
! 4559:
1.1 root 4560: @node Class Preferences, Modifiers, Multi-Alternative, Constraints
4561: @subsection Register Class Preferences
4562:
4563: The operand constraints have another function: they enable the compiler
4564: to decide which kind of hardware register a pseudo register is best
4565: allocated to. The compiler examines the constraints that apply to the
4566: insns that use the pseudo register, looking for the machine-dependent
4567: letters such as @samp{d} and @samp{a} that specify classes of registers.
4568: The pseudo register is put in whichever class gets the most ``votes''.
4569: The constraint letters @samp{g} and @samp{r} also vote: they vote in
4570: favor of a general register. The machine description says which registers
4571: are considered general.
4572:
4573: Of course, on some machines all registers are equivalent, and no register
4574: classes are defined. Then none of this complexity is relevant.
4575:
4576: @node Modifiers, No Constraints, Class Preferences, Constraints
4577: @subsection Constraint Modifier Characters
4578:
4579: @table @samp
4580: @item =
1.1.1.2 ! root 4581: Means that this operand is write-only for this instruction: the previous
! 4582: value is discarded and replaced by output data.
1.1 root 4583:
4584: @item +
4585: Means that this operand is both read and written by the instruction.
4586:
4587: When the compiler fixes up the operands to satisfy the constraints,
4588: it needs to know which operands are inputs to the instruction and
4589: which are outputs from it. @samp{=} identifies an output; @samp{+}
4590: identifies an operand that is both input and output; all other operands
4591: are assumed to be input only.
4592:
1.1.1.2 ! root 4593: @item &
! 4594: Means (in a particular alternative) that this operand is written
! 4595: before the instruction is finished using the input operands.
! 4596: Therefore, this operand may not lie in a register that is used as an
! 4597: input operand or as part of any memory address.
! 4598:
! 4599: @samp{&} applies only to the alternative in which it is written. In
! 4600: constraints with multiple alternatives, sometimes one alternative
! 4601: requires @samp{&} while others do not. See, for example, the
! 4602: @samp{movdf} insn of the 68000.
! 4603:
! 4604: @samp{&} does not obviate the need to write @samp{=}.
! 4605:
1.1 root 4606: @item %
1.1.1.2 ! root 4607: Declares the instruction to be commutative for this operand and the
! 4608: following operand. This means that the compiler may interchange the
! 4609: two operands if that is the cheapest way to make all operands fit the
! 4610: constraints. This is often used in patterns for addition instructions
! 4611: that really have only two operands: the result must go in one of the
! 4612: arguments. Here for example, is how the 68000 halfword-add
! 4613: instruction is defined:
! 4614:
! 4615: @example
! 4616: (define_insn "addhi3"
! 4617: [(set (match_operand:HI 0 "general_operand" "=m,r")
! 4618: (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
! 4619: (match_operand:HI 2 "general_operand" "di,g")))]
! 4620: @dots{})
! 4621: @end example
! 4622:
! 4623: Note that in previous versions of GNU CC the @samp{%} constraint
! 4624: modifier always applied to operands 1 and 2 regardless of which
! 4625: operand it was written in. The usual custom was to write it in
! 4626: operand 0. Now it must be in operand 1 if the operands to be
! 4627: exchanged are 1 and 2.
1.1 root 4628:
4629: @item #
1.1.1.2 ! root 4630: Says that all following characters, up to the next comma, are to be
! 4631: ignored as a constraint. They are significant only for choosing
! 4632: register preferences.
1.1 root 4633:
4634: @item *
4635: Says that the following character should be ignored when choosing
1.1.1.2 ! root 4636: register preferences. @samp{*} has no effect on the meaning of the
! 4637: constraint as a constraint.
! 4638:
! 4639: Here is an example: the 68000 has an instruction to sign-extend a
! 4640: halfword in a data register, and can also sign-extend a value by
! 4641: copying it into an address register. While either kind of register is
! 4642: acceptable, the constraints on an address-register destination are
! 4643: less strict, so it is best if register allocation makes an address
! 4644: register its goal. Therefore, @samp{*} is used so that the @samp{d}
! 4645: constraint letter (for data register) is ignored when computing
! 4646: register preferences.
! 4647:
! 4648: @example
! 4649: (define_insn "extendhisi2"
! 4650: [(set (match_operand:SI 0 "general_operand" "=*d,a")
! 4651: (sign_extend:SI
! 4652: (match_operand:HI 1 "general_operand" "0,g")))]
! 4653: @dots{})
! 4654: @end example
1.1 root 4655: @end table
4656:
4657: @node No Constraints,, Modifiers, Constraints
4658: @subsection Not Using Constraints
4659:
4660: Some machines are so clean that operand constraints are not required. For
4661: example, on the Vax, an operand valid in one context is valid in any other
1.1.1.2 ! root 4662: context. On such a machine, every operand constraint would be @samp{g},
1.1 root 4663: excepting only operands of ``load address'' instructions which are
4664: written as if they referred to a memory location's contents but actual
1.1.1.2 ! root 4665: refer to its address. They would have constraint @samp{p}.
1.1 root 4666:
1.1.1.2 ! root 4667: For such machines, instead of writing @samp{g} and @samp{p} for all
1.1 root 4668: the constraints, you can choose to write a description with empty constraints.
4669: Then you write @samp{""} for the constraint in every @samp{match_operand}.
4670: Address operands are identified by writing an @samp{address} expression
4671: around the @samp{match_operand}, not by their constraints.
4672:
4673: When the machine description has just empty constraints, certain parts
4674: of compilation are skipped, making the compiler faster.
4675:
1.1.1.2 ! root 4676: @node Standard Names, Pattern Ordering, Constraints, Machine Desc
! 4677: @section Standard Names for Patterns Used in Generation
1.1 root 4678:
4679: Here is a table of the instruction names that are meaningful in the RTL
4680: generation pass of the compiler. Giving one of these names to an
4681: instruction pattern tells the RTL generation pass that it can use the
4682: pattern in to accomplish a certain task.
4683:
1.1.1.2 ! root 4684: @table @asis
! 4685: @item @samp{mov@var{m}}
1.1 root 4686: Here @var{m} is a two-letter machine mode name, in lower case. This
4687: instruction pattern moves data with that machine mode from operand 1 to
4688: operand 0. For example, @samp{movsi} moves full-word data.
4689:
4690: If operand 0 is a @samp{subreg} with mode @var{m} of a register whose
4691: natural mode is wider than @var{m}, the effect of this instruction is
4692: to store the specified value in the part of the register that corresponds
4693: to mode @var{m}. The effect on the rest of the register is undefined.
4694:
1.1.1.2 ! root 4695: @item @samp{movstrict@var{m}}
1.1 root 4696: Like @samp{mov@var{m}} except that if operand 0 is a @samp{subreg}
4697: with mode @var{m} of a register whose natural mode is wider,
4698: the @samp{movstrict@var{m}} instruction is guaranteed not to alter
4699: any of the register except the part which belongs to mode @var{m}.
4700:
1.1.1.2 ! root 4701: @item @samp{add@var{m}3}
1.1 root 4702: Add operand 2 and operand 1, storing the result in operand 0. All operands
4703: must have mode @var{m}. This can be used even on two-address machines, by
4704: means of constraints requiring operands 1 and 0 to be the same location.
4705:
1.1.1.2 ! root 4706: @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}
1.1 root 4707: Similar, for other arithmetic operations.
4708:
1.1.1.2 ! root 4709: @item @samp{andcb@var{m}3}
1.1 root 4710: Bitwise logical-and operand 1 with the complement of operand 2
4711: and store the result in operand 0.
4712:
1.1.1.2 ! root 4713: @item @samp{mulhisi3}
1.1 root 4714: Multiply operands 1 and 2, which have mode @code{HImode}, and store
4715: a @code{SImode} product in operand 0.
4716:
1.1.1.2 ! root 4717: @item @samp{mulqihi3}, @samp{mulsidi3}
1.1 root 4718: Similar widening-multiplication instructions of other widths.
4719:
1.1.1.2 ! root 4720: @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
1.1 root 4721: Similar widening-multiplication instructions that do unsigned
4722: multiplication.
4723:
1.1.1.2 ! root 4724: @item @samp{divmod@var{m}4}
1.1 root 4725: Signed division that produces both a quotient and a remainder.
4726: Operand 1 is divided by operand 2 to produce a quotient stored
4727: in operand 0 and a remainder stored in operand 3.
4728:
1.1.1.2 ! root 4729: @item @samp{udivmod@var{m}4}
1.1 root 4730: Similar, but does unsigned division.
4731:
1.1.1.2 ! root 4732: @item @samp{divmod@var{m}@var{n}4}
1.1 root 4733: Like @samp{divmod@var{m}4} except that only the dividend has mode
4734: @var{m}; the divisor, quotient and remainder have mode @var{n}.
4735: For example, the Vax has a @samp{divmoddisi4} instruction
4736: (but it is omitted from the machine description, because it
4737: is so slow that it is faster to compute remainders by the
4738: circumlocution that the compiler will use if this instruction is
4739: not available).
4740:
1.1.1.2 ! root 4741: @item @samp{ashl@var{m}3}
1.1 root 4742: Arithmetic-shift operand 1 left by a number of bits specified by
4743: operand 2, and store the result in operand 0. Operand 2 has
4744: mode @code{SImode}, not mode @var{m}.
4745:
1.1.1.2 ! root 4746: @item @samp{ashr@var{m}3}, @samp{lshl@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
1.1 root 4747: Other shift and rotate instructions.
4748:
1.1.1.2 ! root 4749: Logical and arithmetic left shift are the same. Machines that do not
! 4750: allow negative shift counts often have only one instruction for
! 4751: shifting left. On such machines, you should define a pattern named
! 4752: @samp{ashl@var{m}3} and leave @samp{lshl@var{m}3} undefined.
! 4753:
! 4754: @item @samp{neg@var{m}2}
1.1 root 4755: Negate operand 1 and store the result in operand 0.
4756:
1.1.1.2 ! root 4757: @item @samp{abs@var{m}2}
1.1 root 4758: Store the absolute value of operand 1 into operand 0.
4759:
1.1.1.2 ! root 4760: @item @samp{sqrt@var{m}2}
1.1 root 4761: Store the square root of operand 1 into operand 0.
4762:
1.1.1.2 ! root 4763: @item @samp{ffs@var{m}2}
! 4764: Store into operand 0 one plus the index of the least significant 1-bit
! 4765: of operand 1. If operand 1 is zero, store zero. @var{m} is the mode
! 4766: of operand 0; operand 1's mode is specified by the instruction
! 4767: pattern, and the compiler will convert the operand to that mode before
! 4768: generating the instruction.
! 4769:
! 4770: @item @samp{one_cmpl@var{m}2}
1.1 root 4771: Store the bitwise-complement of operand 1 into operand 0.
4772:
1.1.1.2 ! root 4773: @item @samp{cmp@var{m}}
1.1 root 4774: Compare operand 0 and operand 1, and set the condition codes.
1.1.1.2 ! root 4775: The RTL pattern should look like this:
1.1 root 4776:
1.1.1.2 ! root 4777: @example
! 4778: (set (cc0) (minus (match_operand:@var{m} 0 @dots{})
! 4779: (match_operand:@var{m} 1 @dots{})))
! 4780: @end example
! 4781:
! 4782: Each such definition in the machine description, for integer mode
! 4783: @var{m}, must have a corresponding @samp{tst@var{m}} pattern, because
! 4784: optimization can simplify the compare into a test when operand 1 is
! 4785: zero.
! 4786:
! 4787: @item @samp{tst@var{m}}
1.1 root 4788: Compare operand 0 against zero, and set the condition codes.
1.1.1.2 ! root 4789: The RTL pattern should look like this:
1.1 root 4790:
1.1.1.2 ! root 4791: @example
! 4792: (set (cc0) (match_operand:@var{m} 0 @dots{}))
! 4793: @end example
! 4794:
! 4795: @item @samp{movstr@var{m}}
1.1 root 4796: Block move instruction. The addresses of the destination and source
4797: strings are the first two operands, and both are in mode @code{Pmode}.
4798: The number of bytes to move is the third operand, in mode @var{m}.
4799:
1.1.1.2 ! root 4800: @item @samp{cmpstr@var{m}}
1.1 root 4801: Block compare instruction, with operands like @samp{movstr@var{m}}
4802: except that the two memory blocks are compared byte by byte
4803: in lexicographic order. The effect of the instruction is to set
4804: the condition codes.
4805:
1.1.1.2 ! root 4806: @item @samp{float@var{m}@var{n}2}
1.1 root 4807: Convert operand 1 (valid for fixed point mode @var{m}) to floating
4808: point mode @var{n} and store in operand 0 (which has mode @var{n}).
4809:
1.1.1.2 ! root 4810: @item @samp{fix@var{m}@var{n}2}
! 4811: Convert operand 1 (valid for floating point mode @var{m}) to fixed
! 4812: point mode @var{n} as a signed number and store in operand 0 (which
! 4813: has mode @var{n}). This instruction's result is defined only when
! 4814: the value of operand 1 is an integer.
! 4815:
! 4816: @item @samp{fixuns@var{m}@var{n}2}
! 4817: Convert operand 1 (valid for floating point mode @var{m}) to fixed
! 4818: point mode @var{n} as an unsigned number and store in operand 0 (which
! 4819: has mode @var{n}). This instruction's result is defined only when the
! 4820: value of operand 1 is an integer.
! 4821:
! 4822: @item @samp{ftrunc@var{m}2}
! 4823: Convert operand 1 (valid for floating point mode @var{m}) to an
! 4824: integer value, still represented in floating point mode @var{m}, and
! 4825: store it in operand 0 (valid for floating point mode @var{m}).
! 4826:
! 4827: @item @samp{fix_trunc@var{m}@var{n}2}
! 4828: Like @samp{fix@var{m}@var{n}2} but works for any floating point value
! 4829: of mode @var{m} by converting the value to an integer.
! 4830:
! 4831: @item @samp{fixuns_trunc@var{m}@var{n}2}
! 4832: Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
! 4833: value of mode @var{m} by converting the value to an integer.
! 4834:
! 4835: @item @samp{trunc@var{m}@var{n}}
1.1 root 4836: Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
4837: store in operand 0 (which has mode @var{n}). Both modes must be fixed
4838: point or both floating point.
4839:
1.1.1.2 ! root 4840: @item @samp{extend@var{m}@var{n}}
1.1 root 4841: Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
4842: store in operand 0 (which has mode @var{n}). Both modes must be fixed
4843: point or both floating point.
4844:
1.1.1.2 ! root 4845: @item @samp{zero_extend@var{m}@var{n}}
1.1 root 4846: Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
4847: store in operand 0 (which has mode @var{n}). Both modes must be fixed
4848: point.
4849:
1.1.1.2 ! root 4850: @item @samp{extv}
1.1 root 4851: Extract a bit-field from operand 1 (a register or memory operand),
4852: where operand 2 specifies the width in bits and operand 3 the starting
4853: bit, and store it in operand 0. Operand 0 must have @code{Simode}.
4854: Operand 1 may have mode @code{QImode} or @code{SImode}; often
4855: @code{SImode} is allowed only for registers. Operands 2 and 3 must be
4856: valid for @code{SImode}.
4857:
4858: The RTL generation pass generates this instruction only with constants
4859: for operands 2 and 3.
4860:
4861: The bit-field value is sign-extended to a full word integer
4862: before it is stored in operand 0.
4863:
1.1.1.2 ! root 4864: @item @samp{extzv}
1.1 root 4865: Like @samp{extv} except that the bit-field value is zero-extended.
4866:
1.1.1.2 ! root 4867: @item @samp{insv}
1.1 root 4868: Store operand 3 (which must be valid for @code{SImode}) into a
4869: bit-field in operand 0, where operand 1 specifies the width in bits
4870: and operand 2 the starting bit. Operand 0 may have mode @code{QImode}
4871: or @code{SImode}; often @code{SImode} is allowed only for registers.
4872: Operands 1 and 2 must be valid for @code{SImode}.
4873:
4874: The RTL generation pass generates this instruction only with constants
4875: for operands 1 and 2.
4876:
1.1.1.2 ! root 4877: @item @samp{s@var{cond}}
! 4878: Store zero or nonzero in the operand according to the condition codes.
! 4879: Value stored is nonzero iff the condition @var{cond} is true.
! 4880: @var{cond} is the name of a comparison operation expression code, such
1.1 root 4881: as @samp{eq}, @samp{lt} or @samp{leu}.
4882:
1.1.1.2 ! root 4883: You specify the mode that the operand must have when you write the
! 4884: @code{match_operand} expression. The compiler automatically sees
! 4885: which mode you have used and supplies an operand of that mode.
! 4886:
! 4887: The value stored for a true condition must have 1 as its low bit.
! 4888: Otherwise the instruction is not suitable and must be omitted from the
! 4889: machine description. You must tell the compiler exactly which value
! 4890: is stored by defining the macro @code{STORE_FLAG_VALUE}.
! 4891:
! 4892: @item @samp{b@var{cond}}
1.1 root 4893: Conditional branch instruction. Operand 0 is a @samp{label_ref}
4894: that refers to the label to jump to. Jump if the condition codes
4895: meet condition @var{cond}.
4896:
1.1.1.2 ! root 4897: @item @samp{call}
! 4898: Subroutine call instruction. Operand 1 is the number of bytes of
! 4899: arguments pushed (in mode @code{SImode}), and operand 0 is the
! 4900: function to call. Operand 0 should be a @samp{mem} RTX whose address
! 4901: is the address of the function.
1.1 root 4902:
1.1.1.2 ! root 4903: @item @samp{return}
1.1 root 4904: Subroutine return instruction. This instruction pattern name should be
4905: defined only if a single instruction can do all the work of returning
4906: from a function.
4907:
1.1.1.2 ! root 4908: @item @samp{tablejump}
! 4909: @item @samp{case@var{m}}
1.1 root 4910: @end table
4911:
1.1.1.2 ! root 4912: @node Pattern Ordering, Dependent Patterns, Standard Names, Machine Desc
! 4913: @section When the Order of Patterns Matters
! 4914:
! 4915: Sometimes an insn can match more than one instruction pattern. Then the
! 4916: pattern that appears first in the machine description is the one used.
! 4917: Therefore, more specific patterns (patterns that will match fewer things)
! 4918: and faster instructions (those that will produce better code when they
! 4919: do match) should usually go first in the description.
! 4920:
! 4921: In some cases the effect of ordering the patterns can be used to hide
! 4922: a pattern when it is not valid. For example, the 68000 has an
! 4923: instruction for converting a fullword to floating point and another
! 4924: for converting a byte to floating point. An instruction converting
! 4925: an integer to floating point could match either one. We put the
! 4926: pattern to convert the fullword first to make sure that one will
! 4927: be used rather than the other. (Otherwise a large integer might
! 4928: be generated as a single-byte immediate quantity, which would not work.)
! 4929: Instead of using this pattern ordering it would be possible to make the
! 4930: pattern for convert-a-byte smart enough to deal properly with any
! 4931: constant value.
! 4932:
! 4933: @node Dependent Patterns, Jump Patterns, Pattern Ordering, Machine Desc
! 4934: @section Interdependence of Patterns
1.1 root 4935:
4936: Every machine description must have a named pattern for each of the
4937: conditional branch names @samp{b@var{cond}}. The recognition template
4938: must always have the form
4939:
4940: @example
4941: (set (pc)
4942: (if_then_else (@var{cond} (cc0) (const_int 0))
4943: (label_ref (match_operand 0 "" ""))
4944: (pc)))
4945: @end example
4946:
4947: @noindent
4948: In addition, every machine description must have an anonymous pattern
4949: for each of the possible reverse-conditional branches. These patterns
4950: look like
4951:
4952: @example
4953: (set (pc)
4954: (if_then_else (@var{cond} (cc0) (const_int 0))
4955: (pc)
4956: (label_ref (match_operand 0 "" ""))))
4957: @end example
4958:
4959: @noindent
4960: They are necessary because jump optimization can turn direct-conditional
4961: branches into reverse-conditional branches.
4962:
4963: The compiler does more with RTL than just create it from patterns
4964: and recognize the patterns: it can perform arithmetic expression codes
4965: when constant values for their operands can be determined. As a result,
4966: sometimes having one pattern can require other patterns. For example, the
4967: Vax has no `and' instruction, but it has `and not' instructions. Here
4968: is the definition of one of them:
4969:
4970: @example
4971: (define_insn "andcbsi2"
4972: [(set (match_operand:SI 0 "general_operand" "")
4973: (and:SI (match_dup 0)
4974: (not:SI (match_operand:SI
4975: 1 "general_operand" ""))))]
4976: ""
4977: "bicl2 %1,%0")
4978: @end example
4979:
4980: @noindent
4981: If operand 1 is an explicit integer constant, an instruction constructed
1.1.1.2 ! root 4982: using that pattern can be simplified into an `and' like this:
1.1 root 4983:
4984: @example
4985: (set (reg:SI 41)
4986: (and:SI (reg:SI 41)
4987: (const_int 0xffff7fff)))
4988: @end example
4989:
4990: @noindent
4991: (where the integer constant is the one's complement of what
4992: appeared in the original instruction).
4993:
4994: To avoid a fatal error, the compiler must have a pattern that recognizes
4995: such an instruction. Here is what is used:
4996:
4997: @example
4998: (define_insn ""
4999: [(set (match_operand:SI 0 "general_operand" "")
5000: (and:SI (match_dup 0)
5001: (match_operand:SI 1 "general_operand" "")))]
5002: "GET_CODE (operands[1]) == CONST_INT"
5003: "*
1.1.1.2 ! root 5004: @{ operands[1]
1.1 root 5005: = gen_rtx (CONST_INT, VOIDmode, ~INTVAL (operands[1]));
5006: return \"bicl2 %1,%0\";
1.1.1.2 ! root 5007: @}")
1.1 root 5008: @end example
5009:
5010: @noindent
5011: Whereas a pattern to match a general `and' instruction is impossible to
5012: support on the Vax, this pattern is possible because it matches only a
5013: constant second argument: a special case that can be output as an `and not'
5014: instruction.
5015:
1.1.1.2 ! root 5016: A ``compare'' instruction whose RTL looks like this:
! 5017:
! 5018: @example
! 5019: (set (cc0) (minus @var{operand} (const_int 0)))
! 5020: @end example
! 5021:
! 5022: @noindent
! 5023: may be simplified by optimization into a ``test'' like this:
! 5024:
! 5025: @example
! 5026: (set (cc0) @var{operand})
! 5027: @end example
! 5028:
! 5029: @noindent
! 5030: So in the machine description, each ``compare'' pattern for an integer
! 5031: mode must have a corresponding ``test'' pattern that will match the
! 5032: result of such simplification.
! 5033:
! 5034: In some cases machines support instructions identical except for the
! 5035: machine mode of one or more operands. For example, there may be
! 5036: ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
! 5037: patterns are
! 5038:
! 5039: @example
! 5040: (set (match_operand:SI 0 @dots{})
! 5041: (extend:SI (match_operand:HI 1 @dots{})))
! 5042:
! 5043: (set (match_operand:SI 0 @dots{})
! 5044: (extend:SI (match_operand:QI 1 @dots{})))
! 5045: @end example
! 5046:
! 5047: @noindent
! 5048: Constant integers do not specify a machine mode, so an instruction to
! 5049: extend a constant value could match either pattern. The pattern it
! 5050: actually will match is the one that appears first in the file. For correct
! 5051: results, this must be the one for the widest possible mode (@code{HImode},
! 5052: here). If the pattern matches the @code{QImode} instruction, the results
! 5053: will be incorrect if the constant value does not actually fit that mode.
! 5054:
! 5055: Such instructions to extend constants are rarely generated because they are
! 5056: optimized away, but they do occasionally happen in nonoptimized
! 5057: compilations.
! 5058:
! 5059: @node Jump Patterns, Peephole Definitions, Dependent Patterns, Machine Desc
! 5060: @section Defining Jump Instruction Patterns
! 5061:
! 5062: GNU CC assumes that the machine has a condition code. A comparison insn
! 5063: sets the condition code, recording the results of both signed and unsigned
! 5064: comparison of the given operands. A separate branch insn tests the
! 5065: condition code and branches or not according its value. The branch insns
! 5066: come in distinct signed and unsigned flavors. Many common machines, such
! 5067: as the Vax, the 68000 and the 32000, work this way.
! 5068:
! 5069: Some machines have distinct signed and unsigned compare instructions, and
! 5070: only one set of conditional branch instructions. The easiest way to handle
! 5071: these machines is to treat them just like the others until the final stage
! 5072: where assembly code is written. At this time, when outputting code for the
! 5073: compare instruction, peek ahead at the following branch using
! 5074: @code{NEXT_INSN (insn)}. (The variable @code{insn} refers to the insn
! 5075: being output, in the output-writing code in an instruction pattern.) If
! 5076: the RTL says that is an unsigned branch, output an unsigned compare;
! 5077: otherwise output a signed compare. When the branch itself is output, you
! 5078: can treat signed and unsigned branches identically.
! 5079:
! 5080: The reason you can do this is that GNU CC always generates a pair of
! 5081: consecutive RTL insns, one to set the condition code and one to test it,
! 5082: and keeps the pair inviolate until the end.
! 5083:
! 5084: To go with this technique, you must define the machine-description macro
! 5085: @code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no
! 5086: compare instruction is superfluous.
! 5087:
! 5088: Some machines have compare-and-branch instructions and no condition code.
! 5089: A similar technique works for them. When it is time to ``output'' a
! 5090: compare instruction, record its operands in two static variables. When
! 5091: outputting the branch-on-condition-code instruction that follows, actually
! 5092: output a compare-and-branch instruction that uses the remembered operands.
! 5093:
! 5094: It also works to define patterns for compare-and-branch instructions.
! 5095: In optimizing compilation, the pair of compare and branch instructions
! 5096: will be combined accoprding to these patterns. But this does not happen
! 5097: if optimization is not requested. So you must use one of the solutions
! 5098: above in addition to any special patterns you define.
! 5099:
! 5100: @node Peephole Definitions, Expander Definitions, Jump Patterns, Machine Desc
! 5101: @section Defining Machine-Specific Peephole Optimizers
! 5102:
! 5103: In addition to instruction patterns the @file{md} file may contain
! 5104: definitions of machine-specific peephole optimizations.
! 5105:
! 5106: The combiner does not notice certain peephole optimizations when the data
! 5107: flow in the program does not suggest that it should try them. For example,
! 5108: sometimes two consecutive insns related in purpose can be combined even
! 5109: though the second one does not appear to use a register computed in the
! 5110: first one. A machine-specific peephole optimizer can detect such
! 5111: opportunities.
! 5112:
! 5113: A definition looks like this:
! 5114:
! 5115: @example
! 5116: (define_peephole
! 5117: [@var{insn-pattern-1}
! 5118: @var{insn-pattern-2}
! 5119: @dots{}]
! 5120: "@var{condition}"
! 5121: "@var{template}")
! 5122: @end example
! 5123:
! 5124: In this skeleton, @var{insn-pattern-1} and so on are patterns to match
! 5125: consecutive instructions. The optimization applies to a sequence of
! 5126: instructions when @var{insn-pattern-1} matches the first one,
! 5127: @var{insn-pattern-2} matches the next, and so on.@refill
! 5128:
! 5129: @var{insn-pattern-1} and so on look @emph{almost} like the second operand
! 5130: of @code{define_insn}. There is one important difference: this pattern is
! 5131: an RTX, not a vector. If the @code{define_insn} pattern would be a vector
! 5132: of one element, the @var{insn-pattern} should be just that element, no
! 5133: vector. If the @code{define_insn} pattern would have multiple elements
! 5134: then the @var{insn-pattern} must place the vector inside an explicit
! 5135: @code{parallel} RTX.@refill
! 5136:
! 5137: The operands of the instructions are matched with @code{match_operands} and
! 5138: @code{match_dup}, as usual). What is not usual is that the operand numbers
! 5139: apply to all the instruction patterns in the definition. So, you can check
! 5140: for identical operands in two instructions by using @code{match_operand}
! 5141: in one instruction and @code{match_dup} in the other.
! 5142:
! 5143: The operand constraints used in @code{match_operand} patterns do not have
! 5144: any direct effect on the applicability of the optimization, but they will
! 5145: be validated afterward, so write constraints that are sure to fit whenever
! 5146: the optimization is applied. It is safe to use @code{"g"} for each
! 5147: operand.
! 5148:
! 5149: Once a sequence of instructions matches the patterns, the @var{condition}
! 5150: is checked. This is a C expression which makes the final decision whether
! 5151: to perform the optimization (do so if the expression is nonzero). If
! 5152: @var{condition} is omitted (in other words, the string is empty) then the
! 5153: optimization is applied to every sequence of instructions that matches the
! 5154: patterns.
! 5155:
! 5156: The defined peephole optimizations are applied after register allocation is
! 5157: complete. Therefore, the optimizer can check which operands have ended up
! 5158: in which kinds of registers, just by looking at the operands.
! 5159:
! 5160: The way to refer to the operands in @var{condition} is to write
! 5161: @code{operands[@var{i}]} for operand number @var{i} (as matched by
! 5162: @code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} to
! 5163: refer to the last of the insns being matched; use @code{PREV_INSN} to find
! 5164: the preceding insns (but be careful to skip over any @samp{note} insns that
! 5165: intervene).@refill
! 5166:
! 5167: When optimizing computations with intermediate results, you can use
! 5168: @var{condition} to match only when the intermediate results are not used
! 5169: elsewhere. Use the C expression @code{dead_or_set_p (@var{insn},
! 5170: @var{op})}, where @var{insn} is the insn in which you expect the value to
! 5171: be used for the last time (from the value of @code{insn}, together with use
! 5172: of @code{PREV_INSN}), and @var{op} is the intermediate value (from
! 5173: @code{operands[@var{i}]}).@refill
! 5174:
! 5175: Applying the optimization means replacing the sequence of instructions with
! 5176: one new instruction. The @var{template} controls ultimate output of
! 5177: assembler code for this combined instruction. It works exactly like the
! 5178: template of a @code{define_insn}. Operand numbers in this template are the
! 5179: same ones used in matching the original sequence of instructions.
! 5180:
! 5181: The result of a defined peephole optimizer does not need to match any of
! 5182: the instruction patterns, and it does not have an opportunity to match
! 5183: them. The peephole optimizer definition itself serves as the instruction
! 5184: pattern to control how the instruction is output.
! 5185:
! 5186: Defined peephole optimizers are run in the last jump optimization pass, so
! 5187: the instructions they produce are never combined or rearranged
! 5188: automatically in any way.
! 5189:
! 5190: Here is an example, taken from the 68000 machine description:
! 5191:
! 5192: @example
! 5193: (define_peephole
! 5194: [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
! 5195: (set (match_operand:DF 0 "register_operand" "f")
! 5196: (match_operand:DF 1 "register_operand" "ad"))]
! 5197: "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
! 5198: "*
! 5199: @{
! 5200: rtx xoperands[2];
! 5201: xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1);
! 5202: #ifdef MOTOROLA
! 5203: output_asm_insn (\"move.l %1,(sp)\", xoperands);
! 5204: output_asm_insn (\"move.l %1,-(sp)\", operands);
! 5205: return \"fmove.d (sp)+,%0\";
! 5206: #else
! 5207: output_asm_insn (\"movel %1,sp@@\", xoperands);
! 5208: output_asm_insn (\"movel %1,sp@@-\", operands);
! 5209: return \"fmoved sp@@+,%0\";
! 5210: #endif
! 5211: @}
! 5212: ")
! 5213: @end example
! 5214:
! 5215: The effect of this optimization is to change
! 5216:
! 5217: @example
! 5218: jbsr _foobar
! 5219: addql #4,sp
! 5220: movel d1,sp@@-
! 5221: movel d0,sp@@-
! 5222: fmoved sp@@+,fp0
! 5223: @end example
! 5224:
! 5225: @noindent
! 5226: into
! 5227:
! 5228: @example
! 5229: jbsr _foobar
! 5230: movel d1,sp@@
! 5231: movel d0,sp@@-
! 5232: fmoved sp@@+,fp0
! 5233: @end example
! 5234:
! 5235: @node Expander Definitions,, Peephole Definitions, Machine Desc
! 5236: @section Defining RTL Sequences for Code Generation
! 5237:
! 5238: On some target machines, some standard pattern names for RTL generation
! 5239: cannot be handled with single insn, but a sequence of RTL insns can
! 5240: represent them. For these target machines, you can write a
! 5241: @samp{define_expand} to specify how to generate the sequence of RTL.
! 5242:
! 5243: A @samp{define_expand} is an RTL expression that looks almost like a
! 5244: @samp{define_insn}; but, unlike the latter, a @samp{define_expand} is used
! 5245: only for RTL generation and it can produce more than one RTL insn.
! 5246:
! 5247: A @samp{define_expand} RTX has four operands:
! 5248:
! 5249: @itemize @bullet
! 5250: @item
! 5251: The name. Each @samp{define_expand} must have a name, since the only
! 5252: use for it is to refer to it by name.
! 5253:
! 5254: @item
! 5255: The RTL template. This is just like the RTL template for a
! 5256: @samp{define_peephole} in that it is a vector of RTL expressions
! 5257: each being one insn.
! 5258:
! 5259: @item
! 5260: The condition, a string containing a C expression. This expression is
! 5261: used to express how the availability of this pattern depends on
! 5262: subclasses of target machine, selected by command-line options when
! 5263: GNU CC is run. This is just like the condition of a
! 5264: @samp{define_insn} that has a standard name.
! 5265:
! 5266: @item
! 5267: The preparation statements, a string containing zero or more C
! 5268: statements which are to be executed before RTL code is generated from
! 5269: the RTL template.
! 5270:
! 5271: Usually these statements prepare temporary registers for use as
! 5272: internal operands in the RTL template, but they can also generate RTL
! 5273: insns directly by calling routines such as @samp{emit_insn}, etc.
! 5274: Any such insns precede the ones that come from the RTL template.
! 5275: @end itemize
! 5276:
! 5277: The RTL template, in addition to controlling generation of RTL insns,
! 5278: also describes the operands that need to be specified when this pattern
! 5279: is used. In particular, it gives a predicate for each operand.
! 5280:
! 5281: A true operand, which need to be specified in order to generate RTL from
! 5282: the pattern, should be described with a @samp{match_operand} in its first
! 5283: occurrence in the RTL template. This enters information on the operand's
! 5284: predicate into the tables that record such things. GNU CC uses the
! 5285: information to preload the operand into a register if that is required for
! 5286: valid RTL code. If the operand is referred to more than once, subsequent
! 5287: references should use @samp{match_dup}.
! 5288:
! 5289: The RTL template may also refer to internal ``operands'' which are
! 5290: temporary registers or labels used only within the sequence made by the
! 5291: @samp{define_expand}. Internal operands are substituted into the RTL
! 5292: template with @samp{match_dup}, never with @samp{match_operand}. The
! 5293: values of the internal operands are not passed in as arguments by the
! 5294: compiler when it requests use of this pattern. Instead, they are computed
! 5295: within the pattern, in the preparation statements. These statements
! 5296: compute the values and store them into the appropriate elements of
! 5297: @code{operands} so that @samp{match_dup} can find them.
! 5298:
! 5299: There are two special macros defined for use in the preparation statements:
! 5300: @code{DONE} and @code{FAIL}. Use them with a following semicolon,
! 5301: as a statement.
! 5302:
! 5303: @table @code
! 5304: @item DONE
! 5305: Use the @code{DONE} macro to end RTL generation for the pattern. The
! 5306: only RTL insns resulting from the pattern on this occasion will be
! 5307: those already emitted by explicit calls to @code{emit_insn} within the
! 5308: preparation statements; the RTL template will not be generated.
! 5309:
! 5310: @item FAIL
! 5311: Make the pattern fail on this occasion. When a pattern fails, it means
! 5312: that the pattern was not truly available. The calling routines in the
! 5313: compiler will try other strategies for code generation using other patterns.
! 5314:
! 5315: Failure is currently supported only for binary operations (addition,
! 5316: multiplication, shifting, etc.).
! 5317:
! 5318: Do not emit any insns explicitly with @code{emit_insn} before failing.
! 5319: @end table
! 5320:
! 5321: Here is an example, the definition of left-shift for the SPUR chip:
! 5322:
! 5323: @example
! 5324: (define_expand "ashlsi3"
! 5325: [(set (match_operand:SI 0 "register_operand" "")
! 5326: (ashift:SI
! 5327: (match_operand:SI 1 "register_operand" "")
! 5328: (match_operand:SI 2 "nonmemory_operand" "")))]
! 5329: ""
! 5330: "
! 5331: @{
! 5332: if (GET_CODE (operands[2]) != CONST_INT
! 5333: || (unsigned) INTVAL (operands[2]) > 3)
! 5334: FAIL;
! 5335: @}")
! 5336: @end example
! 5337:
! 5338: @noindent
! 5339: This example uses @samp{define_expand} so that it can generate an RTL insn
! 5340: for shifting when the shift-count is in the supported range of 0 to 3 but
! 5341: fail in other cases where machine insns aren't available. When it fails,
! 5342: the compiler tries another strategy using different patterns (such as, a
! 5343: library call).
! 5344:
! 5345: If the compiler were able to handle nontrivial condition-strings in
! 5346: patterns with names, then there would be possible to use a
! 5347: @samp{define_insn} in that case. Here is another case (zero-extension on
! 5348: the 68000) which makes more use of the power of @samp{define_expand}:
! 5349:
! 5350: @example
! 5351: (define_expand "zero_extendhisi2"
! 5352: [(set (match_operand:SI 0 "general_operand" "")
! 5353: (const_int 0))
! 5354: (set (strict_low_part
! 5355: (subreg:HI
! 5356: (match_operand:SI 0 "general_operand" "")
! 5357: 0))
! 5358: (match_operand:HI 1 "general_operand" ""))]
! 5359: ""
! 5360: "operands[1] = make_safe_from (operands[1], operands[0]);")
! 5361: @end example
! 5362:
! 5363: @noindent
! 5364: Here two RTL insns are generated, one to clear the entire output operand
! 5365: and the other to copy the input operand into its low half. This sequence
! 5366: is incorrect if the input operand refers to [the old value of] the output
! 5367: operand, so the preparation statement makes sure this isn't so. The
! 5368: function @code{make_safe_from} copies the @code{operands[1]} into a
! 5369: temporary register if it refers to @code{operands[0]}. It does this
! 5370: by emitting another RTL insn.
! 5371:
! 5372: Finally, a third example shows the use of an internal operand.
! 5373: Zero-extension on the SPUR chip is done by @samp{and}-ing the result
! 5374: against a halfword mask. But this mask cannot be represented by a
! 5375: @samp{const_int} because the constant value is too large to be legitimate
! 5376: on this machine. So it must be copied into a register with
! 5377: @code{force_reg} and then the register used in the @samp{and}.
! 5378:
! 5379: @example
! 5380: (define_expand "zero_extendhisi2"
! 5381: [(set (match_operand:SI 0 "register_operand" "")
! 5382: (and:SI (subreg:SI
! 5383: (match_operand:HI 1 "register_operand" "")
! 5384: 0)
! 5385: (match_dup 2)))]
! 5386: ""
! 5387: "operands[2]
! 5388: = force_reg (SImode, gen_rtx (CONST_INT,
! 5389: VOIDmode, 65535)); ")
! 5390: @end example
! 5391:
! 5392: @node Machine Macros, Config, Machine Desc, Top
1.1 root 5393: @chapter Machine Description Macros
5394:
5395: The other half of the machine description is a C header file conventionally
5396: given the name @file{tm-@var{machine}.h}. The file @file{tm.h} should be a
5397: link to it. The header file @file{config.h} includes @file{tm.h} and most
5398: compiler source files include @file{config.h}.
5399:
5400: @menu
1.1.1.2 ! root 5401: * Run-time Target:: Defining -m options like -m68000 and -m68020.
1.1 root 5402: * Storage Layout:: Defining sizes and alignments of data types.
5403: * Registers:: Naming and describing the hardware registers.
5404: * Register Classes:: Defining the classes of hardware registers.
5405: * Stack Layout:: Defining which way the stack grows and by how much.
1.1.1.2 ! root 5406: * Library Names:: Specifying names of subroutines to call automatically.
1.1 root 5407: * Addressing Modes:: Defining addressing modes valid for memory operands.
5408: * Condition Code:: Defining how insns update the condition code.
5409: * Assembler Format:: Defining how to write insns and pseudo-ops to output.
5410: * Misc:: Everything else.
5411: @end menu
5412:
5413: @node Run-time Target, Storage Layout, Machine Macros, Machine Macros
5414: @section Run-time Target Specification
5415:
5416: @table @code
5417: @item CPP_PREDEFINES
1.1.1.2 ! root 5418: Define this to be a string constant containing @samp{-D} options
1.1 root 5419: to define the predefined macros that identify this machine and system.
5420:
5421: For example, on the Sun, one can use the value
5422:
5423: @example
1.1.1.2 ! root 5424: "-Dmc68000 -Dsun -Dunix"
1.1 root 5425: @end example
5426:
5427: @item extern int target_flags;
5428: This declaration should be present.
5429:
5430: @item TARGET_@dots{}
5431: This series of macros is to allow compiler command arguments to
5432: enable or disable the use of optional features of the target machine.
5433: For example, one machine description serves both the 68000 and
5434: the 68020; a command argument tells the compiler whether it should
5435: use 68020-only instructions or not. This command argument works
5436: by means of a macro @code{TARGET_68020} that tests a bit in
5437: @code{target_flags}.
5438:
5439: Define a macro @code{TARGET_@var{featurename}} for each such option.
5440: Its definition should test a bit in @code{target_flags}; for example:
5441:
5442: @example
5443: #define TARGET_68020 (target_flags & 1)
5444: @end example
5445:
5446: One place where these macros are used is in the condition-expressions
5447: of instruction patterns. Note how @code{TARGET_68020} appears
1.1.1.2 ! root 5448: frequently in the 68000 machine description file, @file{m68k.md}.
1.1 root 5449: Another place they are used is in the definitions of the other
5450: macros in the @file{tm-@var{machine}.h} file.
5451:
5452: @item TARGET_SWITCHES
1.1.1.2 ! root 5453: This macro defines names of command options to set and clear
1.1 root 5454: bits in @code{target_flags}. Its definition is an initializer
1.1.1.2 ! root 5455: with a subgrouping for each command option.
1.1 root 5456:
1.1.1.2 ! root 5457: Each subgrouping contains a string constant, that defines the option
1.1 root 5458: name, and a number, which contains the bits to set in
5459: @code{target_flags}. A negative number says to clear bits instead;
1.1.1.2 ! root 5460: the negative of the number is which bits to clear. The actual option
1.1 root 5461: name is made by appending @samp{-m} to the specified name.
5462:
5463: One of the subgroupings should have a null string. The number in
5464: this grouping is the default value for @code{target_flags}. Any
1.1.1.2 ! root 5465: target options act starting with that value.
1.1 root 5466:
5467: Here is an example which defines @samp{-m68000} and @samp{-m68020}
5468: with opposite meanings, and picks the latter as the default:
5469:
5470: @example
5471: #define TARGET_SWITCHES \
5472: @{ @{ "68020", 1@}, \
5473: @{ "68000", -1@}, \
5474: @{ "", 1@}@}
5475: @end example
5476: @end table
5477:
1.1.1.2 ! root 5478: Sometimes certain combinations of command options do not make sense on a
! 5479: particular target machine. You can define a macro @code{OVERRIDE_OPTIONS}
! 5480: to take account of this. This macro, if defined, is executed once
! 5481: just after all the command options have been parsed.
! 5482:
1.1 root 5483: @node Storage Layout, Registers, Run-time Target, Machine Macros
5484: @section Storage Layout
5485:
1.1.1.2 ! root 5486: Note that the definitions of the macros in this table which are sizes or
! 5487: alignments measured in bits do not need to be constant. They can be C
! 5488: expressions that refer to static variables, such as the @code{target_flags}.
! 5489: @xref{Run-time Target}.
! 5490:
1.1 root 5491: @table @code
5492: @item BITS_BIG_ENDIAN
5493: Define this macro if the most significant bit in a byte has the lowest
5494: number. This means that bit-field instructions count from the most
5495: significant bit. If the machine has no bit-field instructions, this
5496: macro is irrelevant.
5497:
5498: @item BYTES_BIG_ENDIAN
5499: Define this macro if the most significant byte in a word has the
5500: lowest number.
5501:
5502: @item WORDS_BIG_ENDIAN
1.1.1.2 ! root 5503: Define this macro if, in a multiword object, the most significant
1.1 root 5504: word has the lowest number.
5505:
5506: @item BITS_PER_UNIT
5507: Number of bits in an addressable storage unit (byte); normally 8.
5508:
5509: @item BITS_PER_WORD
5510: Number of bits in a word; normally 32.
5511:
5512: @item UNITS_PER_WORD
5513: Number of storage units in a word; normally 4.
5514:
5515: @item POINTER_SIZE
5516: Width of a pointer, in bits.
5517:
5518: @item PARM_BOUNDARY
1.1.1.2 ! root 5519: Alignment required for function parameters on the stack, in bits.
! 5520:
! 5521: @item STACK_BOUNDARY
! 5522: Define this macro if you wish to preserve a certain alignment for
! 5523: the stack pointer at all times. The definition is a C expression
! 5524: for the desired alignment (measured in bits).
1.1 root 5525:
5526: @item FUNCTION_BOUNDARY
5527: Alignment required for a function entry point, in bits.
5528:
5529: @item BIGGEST_ALIGNMENT
1.1.1.2 ! root 5530: Biggest alignment that any data type can require on this machine, in bits.
! 5531:
! 5532: @item EMPTY_FIELD_ALIGNMENT
! 5533: Alignment in bits to be given to a structure bit field that follows an
! 5534: empty field such as @code{int : 0;}.
! 5535:
! 5536: @item STRUCTURE_SIZE_BOUNDARY
! 5537: Number of bits which any structure or union's size must be a multiple of.
! 5538: Each structure or union's size is rounded up to a multiple of this.
! 5539:
! 5540: If you do not define this macro, the default is the same as
! 5541: @code{BITS_PER_UNIT}.
1.1 root 5542:
5543: @item STRICT_ALIGNMENT
5544: Define this if instructions will fail to work if given data not
5545: on the nominal alignment. If instructions will merely go slower
5546: in that case, do not define this macro.
5547: @end table
5548:
5549: @node Registers, Register Classes, Storage Layout, Machine Macros
5550: @section Register Usage
5551:
5552: @table @code
5553: @item FIRST_PSEUDO_REGISTER
5554: Number of hardware registers known to the compiler. They receive
5555: numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
1.1.1.2 ! root 5556: pseudo register's number really is assigned the number
1.1 root 5557: @code{FIRST_PSEUDO_REGISTER}.
5558:
5559: @item FIXED_REGISTERS
5560: An initializer that says which registers are used for fixed purposes
5561: all throughout the compiled code and are therefore not available for
1.1.1.2 ! root 5562: general allocation. These would include the stack pointer, the frame
1.1 root 5563: pointer, the program counter on machines where that is considered one
5564: of the addressable registers, and any other numbered register with a
5565: standard use.
5566:
5567: This information is expressed as a sequence of numbers, separated by
5568: commas and surrounded by braces. The @var{n}th number is 1 if
1.1.1.2 ! root 5569: register @var{n} is fixed, 0 otherwise.
! 5570:
! 5571: The table initialized from this macro, and the table initialized by
! 5572: the following one, may be overridden at run time either automatically,
! 5573: by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
! 5574: the user with the command options @samp{-ffixed-@var{reg}},
! 5575: @samp{-fcall-used-@var{reg}} and @samp{-fcall-saved-@var{reg}}.
1.1 root 5576:
5577: @item CALL_USED_REGISTERS
5578: Like @code{FIXED_REGISTERS} but has 1 for each register that is
5579: clobbered (in general) by function calls as well as for fixed
5580: registers. This macro therefore identifies the registers that are not
5581: available for general allocation of values that must live across
5582: function calls.
5583:
1.1.1.2 ! root 5584: If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
1.1 root 5585: automatically saves it on function entry and restores it on function
5586: exit, if the register is used within the function.
5587:
1.1.1.2 ! root 5588: @item CONDITIONAL_REGISTER_USAGE
! 5589: Zero or more C statements that may conditionally modify two variables
! 5590: @code{fixed_regs} and @code{call_used_regs} (both of type @code{char
! 5591: []}) after they have been initialized from the two preceding macros.
! 5592:
! 5593: This is necessary in case the fixed or call-clobbered registers depend
! 5594: on target flags.
! 5595:
! 5596: You need not define this macro if it has no work to do.
! 5597:
1.1 root 5598: @item HARD_REGNO_REGS (@var{regno}, @var{mode})
5599: A C expression for the number of consecutive hard registers, starting
5600: at register number @var{regno}, required to hold a value of mode
5601: @var{mode}.
5602:
5603: On a machine where all registers are exactly one word, a suitable
5604: definition of this macro is
5605:
5606: @example
5607: #define HARD_REGNO_NREGS(REGNO, MODE) \
5608: ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \
5609: / UNITS_PER_WORD))
5610: @end example
5611:
5612: @item HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
5613: A C expression that is nonzero if it is permissible to store a value
5614: of mode @var{mode} in hard register number @var{regno} (or in several
5615: registers starting with that one). For a machine where all registers
5616: are equivalent, a suitable definition is
5617:
5618: @example
5619: #define HARD_REGNO_MODE_OK(REGNO, MODE) 1
5620: @end example
5621:
5622: It is not necessary for this macro to check for fixed register numbers
5623: because the allocation mechanism considers them to be always occupied.
5624:
1.1.1.2 ! root 5625: Many machines have special registers for floating point arithmetic.
! 5626: Often people assume that floating point machine modes are allowed only
! 5627: in floating point registers. This is not true. Any registers that
! 5628: can hold integers can safely @emph{hold} a floating point machine
! 5629: mode, whether or not floating arithmetic can be done on it in those
! 5630: registers.
! 5631:
! 5632: The true significance of special floating registers is rather than
! 5633: non-floating-point machine modes @emph{may not} go in those registers.
! 5634: This is true if the floating registers normalize any value stored in
! 5635: them, because storing a non-floating value there would garble it. If
! 5636: the floating registers do not automatically normalize, if you can
! 5637: store any bit pattern in one and retrieve it unchanged without a trap,
! 5638: then any machine mode may go in a floating register and this macro
! 5639: should say so.
! 5640:
! 5641: Sometimes there are floating registers that are especially slow to
! 5642: access, so that it is better to store a value in a stack frame than in
! 5643: such a register if floating point arithmetic is not being done. As long
! 5644: as the floating registers are not in class @code{GENERAL_REGS}, they
! 5645: will not be used unless some insn's constraint asks for one.
! 5646:
! 5647: It is obligatory to support floating point `move' instructions into
! 5648: and out of general registers, because unions and structures (which
! 5649: have modes @samp{SImode} or @samp{DImode}) can be in those registers
! 5650: and they may have floating point members.
! 5651:
1.1 root 5652: @item MODES_TIEABLE_P (@var{mode1}, @var{mode2})
5653: A C expression that is nonzero if it is desirable to choose register
5654: allocation so as to avoid move instructions between a value of mode
5655: @var{mode1} and a value of mode @var{mode2}.
5656:
5657: If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
5658: @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different
5659: for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1},
5660: @var{mode2})} must be zero.
5661:
5662: @item PC_REGNUM
5663: If the program counter has a register number, define this as that
5664: register number. Otherwise, do not define it.
5665:
5666: @item STACK_POINTER_REGNUM
5667: The register number of the stack pointer register, which must also be
5668: a fixed register according to @code{FIXED_REGISTERS}. On many
5669: machines, the hardware determines which register this is.
5670:
5671: @item FRAME_POINTER_REGNUM
5672: The register number of the frame pointer register, which is used to
1.1.1.2 ! root 5673: access automatic variables in the stack frame. On some machines, the
1.1 root 5674: hardware determines which register this is. On other machines, you
5675: can choose any register you wish for this purpose.
5676:
1.1.1.2 ! root 5677: @item FRAME_POINTER_REQUIRED
! 5678: A C expression which is nonzero if a function must have and use a
! 5679: frame pointer. This expression is evaluated in the reload pass, in
! 5680: the function @code{reload}, and it can in principle examine the
! 5681: current function and decide according to the facts, but on most
! 5682: machines the constant 0 or the constant 1 suffices. Use 0 when the
! 5683: machine allows code to be generated with no frame pointer, and doing
! 5684: so saves some time or space. Use 1 when there is no possible
! 5685: advantage to avoiding a frame pointer.
! 5686:
! 5687: In certain cases, the compiler does not know how to do without a frame
! 5688: pointer. The compiler recognizes those cases and automatically gives
! 5689: the function a frame pointer regardless of what
! 5690: @code{FRAME_POINTER_REQUIRED} says. You don't need to worry about
! 5691: them.@refill
! 5692:
! 5693: In a function that does not require a frame pointer, the frame pointer
! 5694: register can be allocated for ordinary usage, provided it is not
! 5695: marked as a fixed register. See @code{FIXED_REGISTERS} for more
! 5696: information.
! 5697:
1.1 root 5698: @item ARG_POINTER_REGNUM
5699: The register number of the arg pointer register, which is used to
5700: access the function's argument list. On some machines, this is the
5701: same as the frame pointer register. On some machines, the hardware
5702: determines which register this is. On other machines, you can choose
5703: any register you wish for this purpose. It must in any case be a
5704: fixed register according to @code{FIXED_REGISTERS}.
5705:
5706: @item STATIC_CHAIN_REGNUM
5707: The register number used for passing a function's static chain
5708: pointer. This is needed for languages such as Pascal and Algol where
5709: functions defined within other functions can access the local
5710: variables of the outer functions; it is not currently used because C
5711: does not provide this feature.
5712:
5713: The static chain register need not be a fixed register.
5714:
5715: @item STRUCT_VALUE_REGNUM
1.1.1.2 ! root 5716: When a function's value's mode is @code{BLKmode}, the value is not
! 5717: returned according to @code{FUNCTION_VALUE}. Instead, the caller
! 5718: passes the address of a block of memory in which the value should be
! 5719: stored. @code{STRUCT_VALUE_REGNUM} is the register in which this
! 5720: address is passed.
1.1 root 5721: @end table
5722:
5723: @node Register Classes, Stack Layout, Registers, Machine Macros
5724: @section Register Classes
5725:
5726: On many machines, the numbered registers are not all equivalent.
5727: For example, certain registers may not be allowed for indexed addressing;
5728: certain registers may not be allowed in some instructions. These machine
5729: restrictions are described to the compiler using @dfn{register classes}.
5730:
5731: You define a number of register classes, giving each one a name and saying
5732: which of the registers belong to it. Then you can specify register classes
5733: that are allowed as operands to particular instruction patterns.
5734:
5735: In general, each register will belong to several classes. In fact, one
5736: class must be named @code{ALL_REGS} and contain all the registers. Another
5737: class must be named @code{NO_REGS} and contain no registers. Often the
5738: union of two classes will be another class; however, this is not required.
5739:
5740: One of the classes must be named @code{GENERAL_REGS}. There is nothing
5741: terribly special about the name, but the operand constraint letters
5742: @samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is
5743: the same as @code{ALL_REGS}, just define it as a macro which expands
5744: to @code{ALL_REGS}.
5745:
5746: The way classes other than @code{GENERAL_REGS} are specified in operand
5747: constraints is through machine-dependent operand constraint letters.
5748: You can define such letters to correspond to various classes, then use
5749: them in operand constraints.
5750:
1.1.1.2 ! root 5751: You should define a class for the union of two classes whenever some
! 5752: instruction allows both classes. For example, if an instruction allows
! 5753: either a floating-point (coprocessor) register or a general register for a
! 5754: certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
! 5755: which includes both of them. Otherwise you will get suboptimal code.
! 5756:
1.1 root 5757: You must also specify certain redundant information about the register
5758: classes: for each class, which classes contain it and which ones are
5759: contained in it; for each pair of classes, the largest class contained
5760: in their union.
5761:
5762: @table @code
5763: @item enum reg_class
5764: An enumeral type that must be defined with all the register class names
5765: as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS}
5766: must be the last register class, followed by one more enumeral value,
5767: @code{LIM_REG_CLASSES}, which is not a register class but rather
5768: tells how many classes there are.
5769:
5770: Each register class has a number, which is the value of casting
5771: the class name to type @code{int}. The number serves as an index
5772: in many of the tables described below.
5773:
5774: @item REG_CLASS_NAMES
5775: An initializer containing the names of the register classes as C string
5776: constants. These names are used in writing some of the debugging dumps.
5777:
5778: @item REG_CLASS_CONTENTS
5779: An initializer containing the contents of the register classes, as integers
5780: which are bit masks. The @var{n}th integer specifies the contents of class
5781: @var{n}. The way the integer @var{mask} is interpreted is that
5782: register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
5783:
5784: When the machine has more than 32 registers, an integer does not suffice.
5785: Then the integers are replaced by sub-initializers, braced groupings containing
5786: several integers. Each sub-initializer must be suitable as an initializer
5787: for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
5788:
5789: @item REGNO_REG_CLASS (@var{regno})
5790: A C expression whose value is a register class containing hard register
5791: @var{regno}. In general there is more that one such class; choose a class
5792: which is @dfn{minimal}, meaning that no smaller class also contains the
5793: register.
5794:
5795: @item INDEX_REG_CLASS
5796: A macro whose definition is the name of the class to which a valid index
5797: register must belong.
5798:
5799: @item REG_CLASS_FROM_LETTER (@var{char})
5800: A C expression which defines the machine-dependent operand constraint
5801: letters for register classes. If @var{char} is such a letter, the value
5802: should be the register class corresponding to it. Otherwise, the value
5803: should be @code{NO_REGS}.
5804:
1.1.1.2 ! root 5805: @item REGNO_OK_FOR_BASE_P (@var{num})
! 5806: A C expression which is nonzero if register number @var{num} is
! 5807: suitable for use as a base register in operand addresses. It may be
! 5808: either a suitable hard register or a pseudo register that has been
! 5809: allocated such a hard register.
! 5810:
! 5811: @item REGNO_OK_FOR_INDEX_P (@var{num})
! 5812: A C expression which is nonzero if register number @var{num} is
! 5813: suitable for use as an index register in operand addresses. It may be
! 5814: either a suitable hard register or a pseudo register that has been
! 5815: allocated such a hard register.
! 5816:
! 5817: The difference between an index register and a base register is that
! 5818: the index register may be scaled. If an address involves the sum of
! 5819: two registers, neither one of them scaled, then either one may be
! 5820: labeled the ``base'' and the other the ``index''; but whichever
! 5821: labeling is used must fit the machine's constraints of which registers
! 5822: may serve in each capacity. The compiler will try both labelings,
! 5823: looking for one that is valid, and reload one or both registers only
! 5824: if neither labeling works.
1.1 root 5825:
5826: @item PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
5827: A C expression that places additional restrictions on the register class
5828: to use when it is necessary to copy value @var{x} into a register in class
5829: @var{class}. The value is a register class; perhaps @var{class}, or perhaps
5830: another, smaller class. @var{class} is always safe as a value. In fact,
5831: the definition
5832:
5833: @example
5834: #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
5835: @end example
5836:
5837: @noindent
5838: is always safe. However, sometimes returning a more restrictive class
5839: makes better code. For example, on the 68000, when @var{x} is an
5840: integer constant that is in range for a @samp{moveq} instruction,
5841: the value of this macro is always @code{DATA_REGS} as long as
5842: @var{class} includes the data registers. Requiring a data register
5843: guarantees that a @samp{moveq} will be used.
1.1.1.2 ! root 5844:
! 5845: @item CLASS_MAX_NREGS (@var{class}, @var{mode})
! 5846: A C expression for the maximum number of consecutive registers
! 5847: of class @var{class} needed to hold a value of mode @var{mode}.
! 5848:
! 5849: This is closely related to the macro @code{HARD_REGNO_NREGS}.
! 5850: In fact, the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
! 5851: should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, @var{mode})}
! 5852: for all @var{regno} values in the class @var{class}.
! 5853:
! 5854: This macro helps control the handling of multiple-word values
! 5855: in the reload pass.
1.1 root 5856: @end table
5857:
1.1.1.2 ! root 5858: Two other special macros describe which constants fit which constraint
! 5859: letters.
1.1 root 5860:
5861: @table @code
5862: @item CONST_OK_FOR_LETTER_P (@var{value}, @var{c})
5863: A C expression that defines the machine-dependent operand constraint letters
5864: that specify particular ranges of integer values. If @var{c} is one
5865: of those letters, the expression should check that @var{value}, an integer,
5866: is in the appropriate range and return 1 if so, 0 otherwise. If @var{c} is
5867: not one of those letters, the value should be 0 regardless of @var{value}.
5868:
5869: @item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c})
5870: A C expression that defines the machine-dependent operand constraint
5871: letters that specify particular ranges of floating values. If @var{c} is
1.1.1.2 ! root 5872: one of those letters, the expression should check that @var{value}, an RTX
1.1 root 5873: of code @samp{const_double}, is in the appropriate range and return 1 if
5874: so, 0 otherwise. If @var{c} is not one of those letters, the value should
5875: be 0 regardless of @var{value}.
5876: @end table
5877:
1.1.1.2 ! root 5878: @node Stack Layout, Library Names, Register Classes, Machine Macros
1.1 root 5879: @section Describing Stack Layout
5880:
5881: @table @code
5882: @item STACK_GROWS_DOWNWARD
5883: Define this macro if pushing a word onto the stack moves the stack
1.1.1.2 ! root 5884: pointer to a smaller address.
! 5885:
! 5886: When we say, ``define this macro if @dots{},'' it means that the
! 5887: compiler checks this macro only with @code{#ifdef} so the precise
! 5888: definition used does not matter.
1.1 root 5889:
5890: @item FRAME_GROWS_DOWNWARD
5891: Define this macro if the addresses of local variable slots are at negative
5892: offsets from the frame pointer.
5893:
5894: @item STARTING_FRAME_OFFSET
5895: Offset from the frame pointer to the first local variable slot to be allocated.
5896:
5897: If @code{FRAME_GROWS_DOWNWARD}, the next slot's offset is found by
5898: subtracting the length of the first slot from @code{STARTING_FRAME_OFFSET}.
5899: Otherwise, it is found by adding the length of the first slot to
5900: the value @code{STARTING_FRAME_OFFSET}.
5901:
5902: @item PUSH_ROUNDING (@var{npushed})
5903: A C expression that is the number of bytes actually pushed onto the
5904: stack when an instruction attempts to push @var{npushed} bytes.
5905:
1.1.1.2 ! root 5906: If the target machine does not have a push instruction, do not define
! 5907: this macro. That directs GNU CC to use an alternate strategy: to
! 5908: allocate the entire argument block and then store the arguments into
! 5909: it.
! 5910:
1.1 root 5911: On some machines, the definition
5912:
5913: @example
5914: #define PUSH_ROUNDING(BYTES) (BYTES)
5915: @end example
5916:
5917: @noindent
5918: will suffice. But on other machines, instructions that appear
5919: to push one byte actually push two bytes in an attempt to maintain
5920: alignment. Then the definition should be
5921:
5922: @example
5923: #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
5924: @end example
5925:
5926: @item FIRST_PARM_OFFSET
5927: Offset from the argument pointer register to the first argument's address.
5928:
1.1.1.2 ! root 5929: @item RETURN_POPS_ARGS (@var{funtype})
! 5930: A C expression that should be 1 if a function pops its own arguments
! 5931: on returning, or 0 if the function pops no arguments and the caller
! 5932: must therefore pop them all after the function returns.
! 5933:
! 5934: @var{funtype} is a C variable whose value is a tree node that
! 5935: describes the function in question. Normally it is a node of type
! 5936: @code{FUNCTION_TYPE} that describes the data type of the function.
! 5937: From this it is possible to obtain the data types of the value and
! 5938: arguments (if known).
! 5939:
! 5940: When a call to a library function is being considered, @var{funtype}
! 5941: will contain an identifier node for the library function. Thus, if
! 5942: you need to distinguish among various library functions, you can do so
! 5943: by their names. Note that ``library function'' in this context means
! 5944: a function used to perform arithmetic, whose name is known specially
! 5945: in the compiler and was not mentioned in the C code being compiled.
! 5946:
! 5947: On the Vax, all functions always pop their arguments, so the
! 5948: definition of this macro is 1. On the 68000, using the standard
! 5949: calling convention, no functions pop their arguments, so the value of
! 5950: the macro is always 0 in this case. But an alternative calling
! 5951: convention is available in which functions that take a fixed number of
! 5952: arguments pop them but other functions (such as @code{printf}) pop
! 5953: nothing (the caller pops all). When this convention is in use,
! 5954: @var{funtype} is examined to determine whether a function takes a
! 5955: fixed number of arguments.
! 5956:
! 5957: @item FUNCTION_VALUE (@var{valtype}, @var{func})
! 5958: A C expression to create an RTX representing the place where a
! 5959: function returns a value of data type @var{valtype}. @var{valtype} is
! 5960: a tree node representing a data type. Write @code{TYPE_MODE
! 5961: (@var{valtype})} to get the machine mode used to represent that type.
! 5962: On many machines, only the mode is relevant. (Actually, on most
! 5963: machines, scalar values are returned in the same place regardless of
! 5964: mode).@refill
! 5965:
! 5966: If the precise function being called is known, @var{func} is a tree
! 5967: node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
! 5968: pointer. This makes it possible to use a different value-returning
! 5969: convention for specific functions when all their calls are
! 5970: known.@refill
! 5971:
! 5972: @item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func})
! 5973: Define this macro if the target machine has ``register windows''
! 5974: so that the register in which a function returns its value is not
! 5975: the same as the one in which the caller sees the value.
! 5976:
! 5977: For such machines, @code{FUNCTION_VALUE} computes the register in
! 5978: which the caller will see the value, and
! 5979: @code{FUNCTION_OUTGOING_VALUE} should be defined in a similar fashion
! 5980: to tell the function where to put the value.@refill
! 5981:
! 5982: If @code{FUNCTION_OUTGOING_VALUE} is not defined,
! 5983: @code{FUNCTION_VALUE} serves both purposes.@refill
! 5984:
! 5985: @item LIBCALL_VALUE (@var{mode})
! 5986: A C expression to create an RTX representing the place where a library
! 5987: function returns a value of mode @var{mode}. If the precise function
! 5988: being called is known, @var{func} is a tree node
! 5989: (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
! 5990: pointer. This makes it possible to use a different value-returning
! 5991: convention for specific functions when all their calls are
! 5992: known.@refill
! 5993:
! 5994: Note that ``library function'' in this context means a compiler
! 5995: support routine, used to perform arithmetic, whose name is known
! 5996: specially by the compiler and was not mentioned in the C code being
! 5997: compiled.
! 5998:
! 5999: @item FUNCTION_VALUE_REGNO_P (@var{regno})
! 6000: A C expression that is nonzero if @var{regno} is the number of a hard
! 6001: register in which function values are sometimes returned.
! 6002:
! 6003: A register whose use for returning values is limited to serving as the
! 6004: second of a pair (for a value of type @code{double}, say) need not be
! 6005: recognized by this macro. So for most machines, this definition
! 6006: suffices:
! 6007:
! 6008: @example
! 6009: #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
! 6010: @end example
! 6011:
! 6012: @item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
! 6013: A C expression that controls whether a function argument is passed
! 6014: in a register, and which register.
! 6015:
! 6016: The arguments are @var{cum}, which summarizes all the previous
! 6017: arguments; @var{mode}, the machine mode of the argument; @var{type},
! 6018: the data type of the argument as a tree node or 0 if that is not known
! 6019: (which happens for C support library functions); and @var{named},
! 6020: which is 1 for an ordinary argument and 0 for nameless arguments that
! 6021: correspond to @samp{...} in the called function's prototype.
! 6022:
! 6023: The value of the expression should either be a @samp{reg} RTX for the
! 6024: hard register in which to pass the argument, or zero to pass the
! 6025: argument on the stack.
! 6026:
! 6027: For the Vax and 68000, where normally all arguments are pushed, zero
! 6028: suffices as a definition.
! 6029:
! 6030: @item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
! 6031: Define this macro if the target machine has ``register windows'', so
! 6032: that the register in which a function sees an arguments is not
! 6033: necessarily the same as the one in which the caller passed the
! 6034: argument.
! 6035:
! 6036: For such machines, @code{FUNCTION_ARG} computes the register in which
! 6037: the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should
! 6038: be defined in a similar fashion to tell the function being called
! 6039: where the arguments will arrive.
! 6040:
! 6041: If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG}
! 6042: serves both purposes.@refill
! 6043:
! 6044: @item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named})
! 6045: A C expression for the number of words, at the beginning of an
! 6046: argument, must be put in registers. The value must be zero for
! 6047: arguments that are passed entirely in registers or that are entirely
! 6048: pushed on the stack.
! 6049:
! 6050: On some machines, certain arguments must be passed partially in
! 6051: registers and partially in memory. On these machines, typically the
! 6052: first @var{n} words of arguments are passed in registers, and the rest
! 6053: on the stack. If a multi-word argument (a @code{double} or a
! 6054: structure) crosses that boundary, its first few words must be passed
! 6055: in registers and the rest must be pushed. This macro tells the
! 6056: compiler when this occurs, and how many of the words should go in
! 6057: registers.
! 6058:
! 6059: @code{FUNCTION_ARG} for these arguments should return the first
! 6060: register to be used by the caller for this argument; likewise
! 6061: @code{FUNCTION_INCOMING_ARG}, for the called function.
! 6062:
! 6063: @item CUMULATIVE_ARGS
! 6064: A C type for declaring a variable that is used as the first argument
! 6065: of @code{FUNCTION_ARG} and other related values. For some target
! 6066: machines, the type @code{int} suffices and can hold the number of
! 6067: bytes of argument so far.
! 6068:
! 6069: @item INIT_CUMULATIVE_ARGS (@var{cum})
! 6070: A C statement (sans semicolon) for initializing the variable @var{cum}
! 6071: for the state at the beginning of the argument list. The variable has
! 6072: type @code{CUMULATIVE_ARGS}.
! 6073:
! 6074: @item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named})
! 6075: Update the summarizer variable @var{cum} to advance past an argument
! 6076: in the argument list. The values @var{mode}, @var{type} and
! 6077: @var{named} describe that argument. Once this is done, the variable
! 6078: @var{cum} is suitable for analyzing the @emph{following} argument
! 6079: with @code{FUNCTION_ARG}, etc.@refill
! 6080:
! 6081: @item FUNCTION_ARG_REGNO_P (@var{regno})
! 6082: A C expression that is nonzero if @var{regno} is the number of a hard
! 6083: register in which function arguments are sometimes passed. This does
! 6084: @emph{not} include implicit arguments such as the static chain and
! 6085: the structure-value address. On many machines, no registers can be
! 6086: used for this purpose since all function arguments are pushed on the
! 6087: stack.
1.1 root 6088:
6089: @item FUNCTION_PROLOGUE (@var{file}, @var{size})
6090: A C compound statement that outputs the assembler code for entry to a
6091: function. The prologue is responsible for setting up the stack frame,
6092: initializing the frame pointer register, saving registers that must be
1.1.1.2 ! root 6093: saved, and allocating @var{size} additional bytes of storage for the
! 6094: local variables. @var{size} is an integer. @var{file} is a stdio
! 6095: stream to which the assembler code should be output.
1.1 root 6096:
6097: The label for the beginning of the function need not be output by this
6098: macro. That has already been done when the macro is run.
6099:
6100: To determine which registers to save, the macro can refer to the array
1.1.1.2 ! root 6101: @code{regs_ever_live}: element @var{r} is nonzero if hard register
! 6102: @var{r} is used anywhere within the function. This implies the
! 6103: function prologue should save register @var{r}, but not if it is one
! 6104: of the call-used registers.
! 6105:
! 6106: On machines where functions may or may not have frame-pointers, the
! 6107: function entry code must vary accordingly; it must set up the frame
! 6108: pointer if one is wanted, and not otherwise. To determine whether a
! 6109: frame pointer is in wanted, the macro can refer to the variable
! 6110: @code{frame_pointer_needed}. The variable's value will be 1 at run
! 6111: time in a function that needs a frame pointer.
! 6112:
! 6113: @item FUNCTION_PROFILER (@var{file}, @var{labelno})
! 6114: A C statement or compound statement to output to @var{file} some
! 6115: assembler code to call the profiling subroutine @code{mcount}.
! 6116: Before calling, the assembler code must load the address of a
! 6117: counter variable into a register where @code{mcount} expects to
! 6118: find the address. The name of this variable is @samp{LP} followed
! 6119: by the number @var{labelno}, so you would generate the name using
! 6120: @samp{LP%d} in a @code{fprintf}.
! 6121:
! 6122: The details of how the address should be passed to @code{mcount} are
! 6123: determined by your operating system environment, not by GNU CC. To
! 6124: figure them out, compile a small program for profiling using the
! 6125: system's installed C compiler and look at the assembler code that
! 6126: results.
! 6127:
! 6128: @item EXIT_IGNORES_STACK
! 6129: Define this macro as a C expression that is nonzero if the return
! 6130: instruction or the function epilogue ignores the value of the stack
! 6131: pointer; in other words, if it is safe to delete an instruction to
! 6132: adjust the stack pointer before a return from the function.
! 6133:
! 6134: Note that this macro's value is relevant only for for which frame
! 6135: pointers are maintained. It is never possible to delete a final stack
! 6136: adjustment in a function that has no frame pointer, and the compiler
! 6137: knows this regardless of @code{EXIT_IGNORES_STACK}.
1.1 root 6138:
6139: @item FUNCTION_EPILOGUE (@var{file}, @var{size})
6140: A C compound statement that outputs the assembler code for exit from a
6141: function. The epilogue is responsible for restoring the saved
6142: registers and stack pointer to their values when the function was
6143: called, and returning control to the caller. This macro takes the
6144: same arguments as the macro @code{FUNCTION_PROLOGUE}, and the
6145: registers to restore are determined from @code{regs_ever_live} and
6146: @code{CALL_USED_REGISTERS} in the same way.
6147:
1.1.1.2 ! root 6148: On some machines, there is a single instruction that does all the work
! 6149: of returning from the function. On these machines, give that
! 6150: instruction the name @samp{return} and do not define the macro
! 6151: @code{FUNCTION_EPILOGUE} at all.
! 6152:
! 6153: On machines where functions may or may not have frame-pointers, the
! 6154: function exit code must vary accordingly. Sometimes the code for
! 6155: these two cases is completely different. To determine whether a frame
! 6156: pointer is in wanted, the macro can refer to the variable
! 6157: @code{frame_pointer_needed}. The variable's value will be 1 at run
! 6158: time in a function that needs a frame pointer.
! 6159:
! 6160: On some machines, some functions pop their arguments on exit while
! 6161: others leave that for the caller to do. For example, the 68020 when
! 6162: given @samp{-mrtd} pops arguments in functions that take a fixed
! 6163: number of arguments.
! 6164:
! 6165: Your definition of the macro @code{RETURN_POPS_ARGS} decides which
! 6166: functions pop their own arguments. @code{FUNCTION_EPILOGUE} needs to
! 6167: know what was decided. The variable @code{current_function_pops_args}
! 6168: is nonzero if the function should pop its own arguments. If so, use
! 6169: the variable @code{current_function_args_size} as the number of bytes
! 6170: to pop.
! 6171:
! 6172: @item FIX_FRAME_POINTER_ADDRESS (@var{addr}, @var{depth})
! 6173: A C compound statement to alter a memory address that uses the frame
! 6174: pointer register so that it uses the stack pointer register instead.
! 6175: This must be done in the instructions that load parameter values into
! 6176: registers, when the reload pass determines that a frame pointer is not
! 6177: necessary for the function. @var{addr} will be a C variable name, and
! 6178: the updated address should be stored in that variable. @var{depth}
! 6179: will be the current depth of stack temporaries (number of bytes of
! 6180: arguments currently pushed). The change in offset between a
! 6181: frame-pointer-relative address and a stack-pointer-relative address
! 6182: must include @var{depth}.
! 6183:
! 6184: Even if your machine description specifies there will always be a
! 6185: frame pointer in the frame pointer register, you must still define
! 6186: @code{FIX_FRAME_POINTER_ADDRESS}, but the definition will never be
! 6187: executed at run time, so it may be empty.
! 6188: @end table
! 6189:
! 6190: @node Library Names, Addressing Modes, Stack Layout, Machine Macros
! 6191: @section Library Subroutine Names
! 6192:
! 6193: @table @code
! 6194: @item UDIVSI3_LIBCALL
! 6195: A C string constant giving the name of the function to call for
! 6196: division of a full-word by a full-word. If you do not define this
! 6197: macro, the default name is used, which is @code{_udivsi3}, a function
! 6198: defined in @file{gnulib}.
! 6199:
! 6200: @item UMODSI3_LIBCALL
! 6201: A C string constant giving the name of the function to call for the
! 6202: remainder in division of a full-word by a full-word. If you do not
! 6203: define this macro, the default name is used, which is @code{_umodsi3},
! 6204: a function defined in @file{gnulib}.
! 6205:
! 6206: @item TARGET_MEM_FUNCTIONS
! 6207: Define this macro if GNU CC should generate calls to the System V
! 6208: (and ANSI C) library functions @code{memcpy} and @code{memset}
! 6209: rather than the BSD functions @code{bcopy} and @code{bzero}.
1.1 root 6210: @end table
6211:
1.1.1.2 ! root 6212: @node Addressing Modes, Misc, Library Names, Machine Macros
1.1 root 6213: @section Addressing Modes
6214:
6215: @table @code
6216: @item HAVE_POST_INCREMENT
6217: Define this macro if the machine supports post-increment addressing.
6218:
6219: @item HAVE_PRE_INCREMENT
6220: @itemx HAVE_POST_DECREMENT
6221: @itemx HAVE_PRE_DECREMENT
6222: Similar for other kinds of addressing.
6223:
6224: @item CONSTANT_ADDRESS_P (@var{x})
1.1.1.2 ! root 6225: A C expression that is 1 if the RTX @var{x} is a constant whose value
1.1 root 6226: is an integer. This includes integers whose values are not explicitly
1.1.1.2 ! root 6227: known, such as @samp{symbol_ref} and @samp{label_ref} expressions and
! 6228: @samp{const} arithmetic expressions.
! 6229:
! 6230: On most machines, this can be defined as @code{CONSTANT_P (@var{x})},
! 6231: but a few machines are more restrictive in which constant addresses
! 6232: are supported.
1.1 root 6233:
6234: @item MAX_REGS_PER_ADDRESS
6235: A number, the maximum number of registers that can appear in a valid
6236: memory address.
6237:
6238: @item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label})
6239: A C compound statement with a conditional @code{goto @var{label};}
1.1.1.2 ! root 6240: executed if @var{x} (an RTX) is a legitimate memory address on the
! 6241: target machine for a memory operand of mode @var{mode}.
1.1 root 6242:
6243: It usually pays to define several simpler macros to serve as
1.1.1.2 ! root 6244: subroutines for this one. Otherwise it may be too complicated to
! 6245: understand.
! 6246:
! 6247: This macro must exist in two variants: a strict variant and a
! 6248: non-strict one. The strict variant is used in the reload pass. It
! 6249: must be defined so that any pseudo-register that has not been
! 6250: allocated a hard register is considered a memory reference. In
! 6251: contexts where some kind of register is required, a pseudo-register
! 6252: with no hard register must be rejected.
! 6253:
! 6254: The non-strict variant is used in other passes. It must be defined to
! 6255: accept all pseudo-registers in every context where some kind of
! 6256: register is required.
! 6257:
! 6258: Compiler source files that want to use the strict variant of this
! 6259: macro define the macro @code{REG_OK_STRICT}. You should use an
! 6260: @code{#ifdef REG_OK_STRICT} conditional to define the strict variant
! 6261: in that case and the non-strict variant otherwise.
! 6262:
! 6263: Typically among the subroutines used to define
! 6264: @code{GO_IF_LEGITIMATE_ADDRESS} are subroutines to check for
! 6265: acceptable registers for various purposes (one for base registers, one
! 6266: for index registers, and so on). Then only these subroutine macros
! 6267: need have two variants; the higher levels of macros may be the same
! 6268: whether strict or not.@refill
1.1 root 6269:
6270: @item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win})
6271: A C compound statement that attempts to replace @var{x} with a valid
1.1.1.2 ! root 6272: memory address for an operand of mode @var{mode}. @var{win} will be a
! 6273: C statement label elsewhere in the code; the macro definition may use
1.1 root 6274:
6275: @example
6276: GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win});
6277: @end example
6278:
6279: @noindent
6280: to avoid further processing if the address has become legitimate.
6281:
6282: @var{x} will always be the result of a call to @code{break_out_memory_refs},
6283: and @var{oldx} will be the operand that was given to that function to produce
6284: @var{x}.
6285:
1.1.1.2 ! root 6286: The code generated by this macro should not alter the substructure of
! 6287: @var{x}. If it transforms @var{x} into a more legitimate form, it
! 6288: should assign @var{x} (which will always be a C variable) a new value.
! 6289:
! 6290: It is not necessary for this macro to come up with a legitimate
! 6291: address. The compiler has standard ways of doing so in all cases. In
! 6292: fact, it is safe for this macro to do nothing. But often a
! 6293: machine-dependent strategy can generate better code.
! 6294:
! 6295: @item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label})
! 6296: A C statement or compound statement with a conditional @code{goto
! 6297: @var{label};} executed if memory address @var{x} (an RTX) can have
! 6298: different meanings depending on the machine mode of the memory
! 6299: reference it is used for.
! 6300:
! 6301: Autoincrement and autodecrement addresses typically have mode-dependent
! 6302: effects because the amount of the increment or decrement is the size
! 6303: of the operand being addressed. Some machines have other mode-dependent
! 6304: addresses. Many RISC machines have no mode-dependent addresses.
! 6305:
! 6306: You may assume that @var{addr} is a valid address for the machine.
! 6307:
! 6308: @item LEGITIMATE_CONSTANT_P (@var{x})
! 6309: A C expression that is nonzero if @var{x} is a legitimate constant for
! 6310: an immediate operand on the target machine. You can assume that
! 6311: either @var{x} is a @samp{const_double} or it satisfies
! 6312: @code{CONSTANT_P}, so you need not check these things. In fact,
! 6313: @samp{1} is a suitable definition for this macro on machines where any
! 6314: @samp{const_double} is valid and anything @code{CONSTANT_P} is valid.@refill
1.1 root 6315: @end table
6316:
6317: @node Misc, Condition Code, Addressing Modes, Machine Macros
6318: @section Miscellaneous Parameters
6319:
6320: @table @code
6321: @item CASE_VECTOR_MODE
1.1.1.2 ! root 6322: An alias for a machine mode name. This is the machine mode that
! 6323: elements of a jump-table should have.
1.1 root 6324:
6325: @item CASE_VECTOR_PC_RELATIVE
6326: Define this macro if jump-tables should contain relative addresses.
6327:
1.1.1.2 ! root 6328: @item CASE_DROPS_THROUGH
! 6329: Define this if control falls through a @code{case} insn when the index
! 6330: value is out of range. This means the specified default-label is
! 6331: actually ignored by the @code{case} insn proper.
! 6332:
1.1 root 6333: @item IMPLICIT_FIX_EXPR
6334: An alias for a tree code that should be used by default for conversion
1.1.1.2 ! root 6335: of floating point values to fixed point. Normally,
! 6336: @code{FIX_ROUND_EXPR} is used.@refill
! 6337:
! 6338: @item FIXUNS_TRUNC_LIKE_FIX_TRUNC
! 6339: Define this macro if the same instructions that convert a floating
! 6340: point number to a signed fixed point number also convert validly to an
! 6341: unsigned one.
1.1 root 6342:
6343: @item EASY_DIV_EXPR
1.1.1.2 ! root 6344: An alias for a tree code that is the easiest kind of division to
! 6345: compile code for in the general case. It may be
! 6346: @code{TRUNC_DIV_EXPR}, @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or
! 6347: @code{ROUND_DIV_EXPR}. These four division operators differ in how
! 6348: they round the result to an integer. @code{EASY_DIV_EXPR} is used
! 6349: when it is permissible to use any of those kinds of division and the
! 6350: choice should be made on the basis of efficiency.@refill
! 6351:
! 6352: @item DEFAULT_SIGNED_CHAR
! 6353: An expression whose value is 1 or 0, according to whether the type
! 6354: @code{char} should be signed or unsigned by default. The user can
! 6355: always override this default with the options @samp{-fsigned-char}
! 6356: and @samp{-funsigned-char}.
! 6357:
! 6358: @item SCCS_DIRECTIVE
! 6359: Define this if the preprocessor should ignore @code{#sccs} directives
! 6360: with no error message.
1.1 root 6361:
6362: @item MOVE_MAX
6363: The maximum number of bytes that a single instruction can move quickly
6364: from memory to memory.
6365:
1.1.1.2 ! root 6366: @item INT_TYPE_SIZE
! 6367: A C expression for the size in bits of the type @code{int} on the
! 6368: target machine.
! 6369:
! 6370: @item SLOW_BYTE_ACCESS
! 6371: Define this macro as a C expression which is nonzero if accessing less
! 6372: than a word of memory (i.e. a @code{char} or a @code{short}) is slow
! 6373: (requires more than one instruction).
! 6374:
1.1 root 6375: @item SLOW_ZERO_EXTEND
1.1.1.2 ! root 6376: Define this macro if zero-extension (of a @code{char} or @code{short}
! 6377: to an @code{int}) can be done faster if the destination is a register
! 6378: that is known to be zero.
! 6379:
! 6380: If you define this macro, you must have instruction patterns that
! 6381: recognize RTL structures like this:
! 6382:
! 6383: @example
! 6384: (set (strict-low-part (subreg:QI (reg:SI @dots{}) 0)) @dots{})
! 6385: @end example
! 6386:
! 6387: @noindent
! 6388: and likewise for @code{HImode}.
1.1 root 6389:
6390: @item SHIFT_COUNT_TRUNCATED
6391: Define this macro if shift instructions ignore all but the lowest few
6392: bits of the shift count. It implies that a sign-extend or zero-extend
6393: instruction for the shift count can be omitted.
6394:
1.1.1.2 ! root 6395: @item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec})
1.1 root 6396: A C expression which is nonzero if on this machine it is safe to
1.1.1.2 ! root 6397: ``convert'' an integer of @var{inprec} bits to one of @var{outprec}
! 6398: bits (where @var{outprec} is smaller than @var{inprec}) by merely
! 6399: operating on it as if it had only @var{outprec} bits.
1.1 root 6400:
6401: On many machines, this expression can be 1.
6402:
1.1.1.2 ! root 6403: @item NO_FUNCTION_CSE
! 6404: Define this macro if it is as good or better to call a constant
! 6405: function address than to call an address kept in a register.
! 6406:
! 6407: @item STORE_FLAG_VALUE
! 6408: A C expression for the value stored by a store-flag instruction
! 6409: (@code{s@var{cond}}) when the condition is true. This is usually 1 or
! 6410: -1; it is required to be an odd number.
! 6411:
! 6412: Do not define @code{STORE_FLAG_VALUE} if the machine has no store-flag
! 6413: instructions.
! 6414:
1.1 root 6415: @item Pmode
1.1.1.2 ! root 6416: An alias for the machine mode for pointers. Normally the definition
! 6417: can be
1.1 root 6418:
6419: @example
6420: #define Pmode SImode
6421: @end example
6422:
6423: @item FUNCTION_MODE
1.1.1.2 ! root 6424: An alias for the machine mode used for memory references to functions
! 6425: being called, in @samp{call} RTL expressions. On most machines this
! 6426: should be @code{QImode}.
1.1 root 6427:
6428: @item CONST_COST (@var{x}, @var{code})
1.1.1.2 ! root 6429: A part of a C @code{switch} statement that describes the relative
! 6430: costs of constant RTL expressions. It must contain @code{case} labels
! 6431: for expression codes @samp{const_int}, @samp{const}, @samp{symbol_ref}, @samp{label_ref}
! 6432: and @samp{const_double}. Each case must ultimately reach a
! 6433: @code{return} statement to return the relative cost of the use of that
1.1 root 6434: kind of constant value in an expression. The cost may depend on the
6435: precise value of the constant, which is available for examination in
6436: @var{x}.
6437:
1.1.1.2 ! root 6438: @var{code} is the expression code---redundant, since it can be
! 6439: obtained with @code{GET_CODE (@var{x})}.
! 6440:
! 6441: @item DOLLARS_IN_IDENTIFIERS
! 6442: Define this if the character @samp{$} should be allowed in identifier
! 6443: names.
1.1 root 6444: @end table
6445:
6446: @node Condition Code, Assembler Format, Misc, Machine Macros
6447: @section Condition Code Information
6448:
6449: The file @file{conditions.h} defines a variable @code{cc_status} to
6450: describe how the condition code was computed (in case the interpretation of
6451: the condition code depends on the instruction that it was set by). This
6452: variable contains the RTL expressions on which the condition code is
6453: currently based, and several standard flags.
6454:
6455: Sometimes additional machine-specific flags must be defined in the machine
6456: description header file. It can also add additional machine-specific
6457: information by defining @code{CC_STATUS_MDEP}.
6458:
6459: @table @code
6460: @item CC_STATUS_MDEP
1.1.1.2 ! root 6461: C code for a data type which is used for declaring the @code{mdep}
! 6462: component of @code{cc_status}. It defaults to @code{int}.
1.1 root 6463:
6464: @item CC_STATUS_MDEP_INIT
1.1.1.2 ! root 6465: A C expression for the initial value of the @code{mdep} field. It
! 6466: defaults to 0.
1.1 root 6467:
6468: @item NOTICE_UPDATE_CC (@var{exp})
6469: A C compound statement to set the components of @code{cc_status}
1.1.1.2 ! root 6470: appropriately for an insn whose body is @var{exp}. It is this macro's
! 6471: responsibility to recognize insns that set the condition code as a
! 6472: byproduct of other activity as well as those that explicitly set
! 6473: @code{(cc0)}.
! 6474:
! 6475: If there are insn that do not set the condition code but do alter
! 6476: other machine registers, this macro must check to see whether they
! 6477: invalidate the expressions that the condition code is recorded as
! 6478: reflecting. For example, on the 68000, insns that store in address
! 6479: registers do not set the condition code, which means that usually
! 6480: @code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such
! 6481: insns. But suppose that the previous insn set the condition code
! 6482: based on location @samp{a4@@(102)} and the current insn stores a new
! 6483: value in @samp{a4}. Although the condition code is not changed by
! 6484: this, it will no longer be true that it reflects the contents of
! 6485: @samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter
1.1 root 6486: @code{cc_status} in this case to say that nothing is known about the
6487: condition code value.
6488: @end table
6489:
6490: @node Assembler Format,, Condition Code, Machine Macros
6491: @section Output of Assembler Code
6492:
6493: @table @code
1.1.1.2 ! root 6494: @item ASM_SPEC
! 6495: A C string constant that tells the GNU CC driver program options to
! 6496: pass to the assembler. It can also specify how to translate options
! 6497: you give to GNU CC into options for GNU CC to pass to the assembler.
! 6498: See the file @file{tm-sun3.h} for an example of this.
! 6499:
! 6500: Do not define this macro if it does not need to do anything.
! 6501:
! 6502: @item LINK_SPEC
! 6503: A C string constant that tells the GNU CC driver program options to
! 6504: pass to the linker. It can also specify how to translate options you
! 6505: give to GNU CC into options for GNU CC to pass to the linker.
! 6506:
! 6507: Do not define this macro if it does not need to do anything.
! 6508:
! 6509: @item ASM_FILE_START
! 6510: A C string constant for text to be output at the start of each
! 6511: assembler output file. Normally this is @code{"#NO_APP"}, which is a
! 6512: comment that has no effect on most assemblers but tells the GNU
! 6513: assembler that it can save time by not checking for certain assembler
! 6514: constructs.
! 6515:
! 6516: @item ASM_APP_ON
! 6517: A C string constant for text to be output before each @code{asm}
! 6518: statement or group of consecutive ones. Normally this is
! 6519: @code{"#APP"}, which is a comment that has no effect on most
! 6520: assemblers but tells the GNU assembler that it must check the lines
! 6521: that follow for all valid assembler constructs.
! 6522:
! 6523: @item ASM_APP_OFF
! 6524: A C string constant for text to be output after each @code{asm}
! 6525: statement or group of consecutive ones. Normally this is
! 6526: @code{"#NO_APP"}, which tells the GNU assembler to resume making the
! 6527: time-saving assumptions that are valid for ordinary compiler output.
! 6528:
1.1 root 6529: @item TEXT_SECTION_ASM_OP
6530: A C string constant for the assembler operation that should precede
6531: instructions and read-only data. Normally @code{".text"} is right.
6532:
6533: @item DATA_SECTION_ASM_OP
1.1.1.2 ! root 6534: A C string constant for the assembler operation to identify the
! 6535: following data as writable initialized data. Normally @code{".data"}
! 6536: is right.
1.1 root 6537:
6538: @item REGISTER_NAMES
1.1.1.2 ! root 6539: A C initializer containing the assembler's names for the machine
! 6540: registers, each one as a C string constant. This is what translates
! 6541: register numbers in the compiler into assembler language.
1.1 root 6542:
6543: @item DBX_REGISTER_NUMBER (@var{regno})
1.1.1.2 ! root 6544: A C expression that returns the DBX register number for the compiler
! 6545: register number @var{regno}. In simple cases, the value of this
! 6546: expression may be @var{regno} itself. But sometimes there are some
! 6547: registers that the compiler knows about and DBX does not, or vice
! 6548: versa. In such cases, some register may need to have one number in
! 6549: the compiler and another for DBX.
! 6550:
! 6551: @item DBX_NO_XREFS
! 6552: Define this macro if DBX on your system does not support the construct
! 6553: @samp{xs@var{tagname}}. On some systems, this construct is used to
! 6554: describe a forward reference to a structure named @var{tagname}.
! 6555: On other systems, this construct is not supported at all.
! 6556:
! 6557: @item DBX_CONTIN_LENGTH
! 6558: A symbol name in DBX-format debugging information is normally
! 6559: continued (split into two separate @code{.stabs} directives) when it
! 6560: exceeds a certain length (by default, 80 characters). On some
! 6561: operating systems, DBX requires this splitting; on others, splitting
! 6562: must not be done. You can inhibit splitting by defining this macro
! 6563: with the value zero. You can override the default splitting-length by
! 6564: defining this macro as an expression for the length you desire.
! 6565:
! 6566: @item DBX_CONTIN_CHAR
! 6567: Normally continuation is indicated by adding a @samp{\} character to
! 6568: the end of a @code{.stabs} string when a continuation follows. To use
! 6569: a different character instead, define this macro as a character
! 6570: constant for the character you want to use. Do not define this macro
! 6571: if backslash is correct for your system.
! 6572:
! 6573: @item ASM_OUTPUT_LABEL (@var{file}, @var{name})
! 6574: A C statement (sans semicolon) to output to the stdio stream
! 6575: @var{file} the assembler definition of a label named @var{name}. Use
! 6576: the expression @code{assemble_name (@var{file}, @var{name})} to output
! 6577: the name itself; before and after that, output the additional
! 6578: assembler syntax for defining the name, and a newline.
! 6579:
! 6580: @item ASM_DECLARE_FUNCTION_NAME (@var{file}, @var{name})
! 6581: A C statement (sans semicolon) to output to the stdio stream
! 6582: @var{file} any text necessary for declaring the name of a function
! 6583: which is being defined. This macro is responsible for outputting
! 6584: the label definition (perhaps using @code{ASM_OUTPUT_LABEL}).
! 6585:
! 6586: If this macro is not defined, then the function name is defined in the
! 6587: usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
! 6588:
! 6589: @item ASM_GLOBALIZE_LABEL (@var{file}, @var{name})
! 6590: A C statement (sans semicolon) to output to the stdio stream
! 6591: @var{file} some commands that will make the label @var{name} global;
! 6592: that is, available for reference from other files. Use the expression
! 6593: @code{assemble_name (@var{file}, @var{name})} to output the name
! 6594: itself; before and after that, output the additional assembler syntax
! 6595: for making that name global, and a newline.
! 6596:
! 6597: @item ASM_OUTPUT_EXTERNAL (@var{file}, @var{name})
! 6598: A C statement (sans semicolon) to output to the stdio stream
! 6599: @var{file} any text necessary for declaring the name of an external
! 6600: symbol which is referenced in this compilation but not defined.
! 6601:
! 6602: This macro need not be defined if it does not need to output anything.
! 6603: The GNU assembler and most Unix assemblers don't require anything.
! 6604:
! 6605: @item ASM_OUTPUT_LABELREF (@var{file}, @var{name})
! 6606: A C statement to output to the stdio stream @var{file} a reference in
! 6607: assembler syntax to a label named @var{name}. The character @samp{_}
! 6608: should be added to the front of the name, if that is customary on your
! 6609: operating system, as it is in most Berkeley Unix systems. This macro
! 6610: is used in @code{assemble_name}.
! 6611:
! 6612: @item ASM_OUTPUT_INTERNAL_LABEL (@var{file}, @var{prefix}, @var{num})
! 6613: A C statement to output to the stdio stream @var{file} a label whose
! 6614: name is made from the string @var{prefix} and the number @var{num}.
! 6615: These labels are used for internal purposes, and there is no reason
! 6616: for them to appear in the symbol table of the object file. On many
! 6617: systems, the letter @samp{L} at the beginning of a label has this
! 6618: effect. The usual definition of this macro is as follows:
! 6619:
! 6620: @example
! 6621: fprintf (@var{file}, "L%s%d:\n", @var{prefix}, @var{num})
! 6622: @end example
! 6623:
! 6624: @item ASM_OUTPUT_CASE_LABEL (@var{file}, @var{prefix}, @var{num}, @var{table})
! 6625: Define this if the label before a jump-table needs to be output
! 6626: specially. The first three arguments are the same as for
! 6627: @code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the
! 6628: jump-table which follows (a @samp{jump_insn} containing an
! 6629: @samp{addr_vec} or @samp{addr_diff_vec}).
! 6630:
! 6631: This feature is used on system V to output a @code{swbeg} statement
! 6632: for the table.
! 6633:
! 6634: If this macro is not defined, these labels are output with
! 6635: @code{ASM_OUTPUT_INTERNAL_LABEL}.
! 6636:
! 6637: @item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number})
! 6638: A C expression to assign to @var{outvar} (which is a variable of type
! 6639: @code{char *}) a newly allocated string made from the string
! 6640: @var{name} and the number @var{number}, with some suitable punctuation
! 6641: added. Use @code{alloca} to get space for the string.
! 6642:
! 6643: This string will be used as the argument to @code{ASM_OUTPUT_LABELREF}
! 6644: to produce an assembler label for an internal static variable whose
! 6645: name is @var{name}. Therefore, the string must be such as to result
! 6646: in valid assembler code. The argument @var{number} is different each
! 6647: time this macro is executed; it prevents conflicts between
! 6648: similarly-named internal static variables in different scopes.
! 6649:
! 6650: Ideally this string should not be a valid C identifier, to prevent any
! 6651: conflict with the user's own symbols. Most assemblers allow periods
! 6652: or percent signs in assembler symbols; putting at least one of these
! 6653: between the name and the number will suffice.
! 6654:
! 6655: @item ASM_OUTPUT_ADDR_DIFF_ELT (@var{file}, @var{value}, @var{rel})
! 6656: This macro should be provided on machines where the addresses
! 6657: in a dispatch table are relative to the table's own address.
! 6658:
! 6659: The definition should be a C statement to output to the stdio stream
! 6660: @var{file} an assembler pseudo-instruction to generate a difference
! 6661: between two labels. @var{value} and @var{rel} are the numbers of two
! 6662: internal labels. The definitions of these labels are output using
! 6663: @code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same
! 6664: way here. For example,
! 6665:
! 6666: @example
! 6667: fprintf (@var{file}, "\t.word L%d-L%d\n",
! 6668: @var{value}, @var{rel})
! 6669: @end example
! 6670:
! 6671: @item ASM_OUTPUT_ADDR_VEC_ELT (@var{file}, @var{value})
! 6672: This macro should be provided on machines where the addresses
! 6673: in a dispatch table are absolute.
! 6674:
! 6675: The definition should be a C statement to output to the stdio stream
! 6676: @var{file} an assembler pseudo-instruction to generate a reference to
! 6677: a label. @var{value} is the number of an internal label whose
! 6678: definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}.
! 6679: For example,
! 6680:
! 6681: @example
! 6682: fprintf (@var{file}, "\t.word L%d\n", @var{value})
! 6683: @end example
1.1 root 6684:
6685: @item ASM_OUTPUT_DOUBLE (@var{file}, @var{value})
6686: A C statement to output to the stdio stream @var{file} an assembler
6687: instruction to assemble a @code{double} constant whose value is
1.1.1.2 ! root 6688: @var{value}. @var{value} will be a C expression of type
! 6689: @code{double}.
1.1 root 6690:
6691: @item ASM_OUTPUT_FLOAT (@var{file}, @var{value})
6692: A C statement to output to the stdio stream @var{file} an assembler
1.1.1.2 ! root 6693: instruction to assemble a @code{float} constant whose value is
! 6694: @var{value}. @var{value} will be a C expression of type @code{float}.
! 6695:
! 6696: @item ASM_OUTPUT_INT (@var{file}, @var{exp})
! 6697: @itemx ASM_OUTPUT_SHORT (@var{file}, @var{exp})
! 6698: @itemx ASM_OUTPUT_CHAR (@var{file}, @var{exp})
! 6699: A C statement to output to the stdio stream @var{file} an assembler
! 6700: instruction to assemble a @code{int}, @code{short} or @code{char}
! 6701: constant whose value is @var{value}. The argument @var{exp} will be
! 6702: an RTL expression which represents a constant value. Use
! 6703: @samp{output_addr_const (@var{exp})} to output this value as an
! 6704: assembler expression.@refill
! 6705:
! 6706: @item ASM_OUTPUT_BYTE (@var{file}, @var{value})
! 6707: A C statement to output to the stdio stream @var{file} an assembler
! 6708: instruction to assemble a single byte containing the number @var{value}.
! 6709:
! 6710: @item ASM_OUTPUT_ASCII (@var{file}, @var{ptr}, @var{len})
! 6711: A C statement to output to the stdio stream @var{file} an assembler
! 6712: instruction to assemble a string constant containing the @var{len}
! 6713: bytes at @var{ptr}. @var{ptr} will be a C expression of type
! 6714: @code{char *} and @var{len} a C expression of type @code{int}.
! 6715:
! 6716: If the assembler has a @code{.ascii} pseudo-op as found in the
! 6717: Berkeley Unix assembler, do not define the macro
! 6718: @code{ASM_OUTPUT_ASCII}.
1.1 root 6719:
6720: @item ASM_OUTPUT_SKIP (@var{file}, @var{nbytes})
6721: A C statement to output to the stdio stream @var{file} an assembler
6722: instruction to advance the location counter by @var{nbytes} bytes.
6723: @var{nbytes} will be a C expression of type @code{int}.
6724:
6725: @item ASM_OUTPUT_ALIGN (@var{file}, @var{power})
6726: A C statement to output to the stdio stream @var{file} an assembler
6727: instruction to advance the location counter to a multiple of 2 to the
6728: @var{power} bytes. @var{power} will be a C expression of type @code{int}.
6729:
1.1.1.2 ! root 6730: @item ASM_OUTPUT_COMMON (@var{file}, @var{name}, @var{size})
! 6731: A C statement (sans semicolon) to output to the stdio stream
! 6732: @var{file} the assembler definition of a common-label named @var{name}
! 6733: whose size is @var{size} bytes. Use the expression
! 6734: @code{assemble_name (@var{file}, @var{name})} to output the name
! 6735: itself; before and after that, output the additional assembler syntax
! 6736: for defining the name, and a newline.
! 6737:
! 6738: This macro controls how the assembler definitions of uninitialized
! 6739: global variables are output.
! 6740:
! 6741: @item ASM_OUTPUT_LOCAL (@var{file}, @var{name}, @var{size})
! 6742: A C statement (sans semicolon) to output to the stdio stream
! 6743: @var{file} the assembler definition of a local-common-label named
! 6744: @var{name} whose size is @var{size} bytes. Use the expression
! 6745: @code{assemble_name (@var{file}, @var{name})} to output the name
! 6746: itself; before and after that, output the additional assembler syntax
! 6747: for defining the name, and a newline.
! 6748:
! 6749: This macro controls how the assembler definitions of uninitialized
! 6750: static variables are output.
1.1 root 6751:
6752: @item TARGET_BELL
1.1.1.2 ! root 6753: A C constant expression for the integer value for escape sequence
! 6754: @samp{\a}.
1.1 root 6755:
6756: @item TARGET_BS
6757: @itemx TARGET_TAB
6758: @itemx TARGET_NEWLINE
6759: C constant expressions for the integer values for escape sequences
6760: @samp{\b}, @samp{\t} and @samp{\n}.
6761:
6762: @item TARGET_VT
6763: @itemx TARGET_FF
6764: @itemx TARGET_CR
6765: C constant expressions for the integer values for escape sequences
6766: @samp{\v}, @samp{\f} and @samp{\r}.
6767:
1.1.1.2 ! root 6768: @item ASM_OUTPUT_OPCODE (@var{file}, @var{ptr})
! 6769: Define this macro if you are using an unusual assembler that
! 6770: requires different names for the machine instructions.
! 6771:
! 6772: The definition is a C statement or statements which output an
! 6773: assembler instruction opcode to the stdio stream @var{file}. The
! 6774: macro-operand @var{ptr} is a variable of type @code{char *} which
! 6775: points to the opcode name in its ``internal'' form---the form that is
! 6776: written in the machine description. The definition should output the
! 6777: opcode name to @var{file}, performing any translation you desire, and
! 6778: increment the variable @var{ptr} to point at the end of the opcode
! 6779: so that it will not be output twice.
! 6780:
! 6781: In fact, your macro definition may process less than the entire opcode
! 6782: name, or more than the opcode name; but if you want to process text
! 6783: that includes @samp{%}-sequences to substitute operands, you must take
! 6784: care of the substitution yourself. Just be sure to increment
! 6785: @var{ptr} over whatever text should not be output normally.
! 6786:
! 6787: If the macro definition does nothing, the instruction is output
! 6788: in the usual way.
! 6789:
! 6790: @item PRINT_OPERAND (@var{file}, @var{x}, @var{code})
! 6791: A C compound statement to output to stdio stream @var{file} the
! 6792: assembler syntax for an instruction operand @var{x}. @var{x} is an
! 6793: RTL expression.
! 6794:
! 6795: @var{code} is a value that can be used to specify one of several ways
! 6796: of printing the operand. It is used when identical operands must be
! 6797: printed differently depending on the context. @var{code} comes from
! 6798: the @samp{%} specification that was used to request printing of the
! 6799: operand. If the specification was just @samp{%@var{digit}} then
! 6800: @var{code} is 0; if the specification was @samp{%@var{ltr}
! 6801: @var{digit}} then @var{code} is the ASCII code for @var{ltr}.
! 6802:
! 6803: If @var{x} is a register, this macro should print the register's name.
! 6804: The names can be found in an array @code{reg_names} whose type is
! 6805: @code{char *[]}. @code{reg_names} is initialized from
! 6806: @code{REGISTER_NAMES}.
! 6807:
! 6808: When the machine description has a specification @samp{%@var{punct}}
! 6809: (a @samp{%} followed by a punctuation character), this macro is called
! 6810: with a null pointer for @var{x} and the punctuation character for
! 6811: @var{code}.
1.1 root 6812:
6813: @item PRINT_OPERAND_ADDRESS (@var{file}, @var{x})
1.1.1.2 ! root 6814: A C compound statement to output to stdio stream @var{file} the
! 6815: assembler syntax for an instruction operand that is a memory reference
! 6816: whose address is @var{x}. @var{x} is an RTL expression.
! 6817:
! 6818: @item ASM_OPEN_PAREN
! 6819: @itemx ASM_CLOSE_PAREN
! 6820: These macros are defined as C string constant, describing the syntax
! 6821: in the assembler for grouping arithmetic expressions. The following
! 6822: definitions are correct for most assemblers:
! 6823:
! 6824: @example
! 6825: #define ASM_OPEN_PAREN "("
! 6826: #define ASM_CLOSE_PAREN ")"
! 6827: @end example
! 6828: @end table
! 6829:
! 6830: @node Config,, Machine Macros, Top
! 6831: @chapter The Configuration File
! 6832:
! 6833: The configuration file @file{config-@var{machine}.h} contains macro
! 6834: definitions that describe the machine and system on which the compiler is
! 6835: running. Most of the values in it are actually the same on all machines
! 6836: that GNU CC runs on, so most all configuration files are identical. But
! 6837: there are some macros that vary:
! 6838:
! 6839: @table @code
! 6840: @item FAILURE_EXIT_CODE
! 6841: A C expression for the status code to be returned when the compiler
! 6842: exits after serious errors.
! 6843:
! 6844: @item SUCCESS_EXIT_CODE
! 6845: A C expression for the status code to be returned when the compiler
! 6846: exits without serious errors.
1.1 root 6847: @end table
6848:
6849: @contents
6850: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.