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