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