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