![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.texinfo CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 1.x] / gcc|
Return to gcc.texinfo CVS log | Up to [GCC 1.x] / gcc |
1.1 root 1: \input texinfo @c -*-texinfo-*-
2:
3: @settitle Using and Porting GNU CC
4: @setfilename gcc.info
5:
6: @ifinfo
7: This file documents the use and the internals of the GNU compiler.
8:
1.1.1.5 root 9: Copyright (C) 1988, 1989 Free Software Foundation, Inc.
1.1 root 10:
11: Permission is granted to make and distribute verbatim copies of
12: this manual provided the copyright notice and this permission notice
13: are preserved on all copies.
14:
15: @ignore
16: Permission is granted to process this file through Tex and print the
17: results, provided the printed document carries copying permission
18: notice identical to this one except for the removal of this paragraph
19: (this paragraph not being relevant to the printed manual).
20:
21: @end ignore
22: Permission is granted to copy and distribute modified versions of this
23: manual under the conditions for verbatim copying, provided also that the
1.1.1.6 root 24: section entitled ``GNU General Public License'' is included exactly as
1.1 root 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.6 root 30: except that the section entitled ``GNU General Public License'' and
1.1 root 31: this permission notice may be included in translations approved by the
32: Free Software Foundation instead of in the original English.
33: @end ifinfo
34:
35: @setchapternewpage odd
36:
37: @titlepage
38: @center @titlefont{Using and Porting GNU CC}
39: @sp 2
40: @center Richard M. Stallman
41: @sp 3
1.1.1.7 ! root 42: @center last updated 22 April 1989
1.1 root 43: @sp 1
1.1.1.7 ! root 44: @center for version 1.35
1.1 root 45: @page
46: @vskip 0pt plus 1filll
1.1.1.5 root 47: Copyright @copyright{} 1988, 1989 Free Software Foundation, Inc.
1.1 root 48:
49: Permission is granted to make and distribute verbatim copies of
50: this manual provided the copyright notice and this permission notice
51: are preserved on all copies.
52:
53: Permission is granted to copy and distribute modified versions of this
54: manual under the conditions for verbatim copying, provided also that the
1.1.1.6 root 55: section entitled ``GNU General Public License'' is included exactly as
1.1 root 56: in the original, and provided that the entire resulting derived work is
57: distributed under the terms of a permission notice identical to this one.
58:
59: Permission is granted to copy and distribute translations of this manual
60: into another language, under the above conditions for modified versions,
1.1.1.6 root 61: <except that the section entitled ``GNU General Public License'' and
1.1 root 62: this permission notice may be included in translations approved by the
63: Free Software Foundation instead of in the original English.
64: @end titlepage
65: @page
66:
67: @ifinfo
68: @node Top, Copying,, (DIR)
69: @ichapter Introduction
70:
71: This manual documents how to run, install and port the GNU C compiler, as
72: well as its new features and incompatibilities, and how to report bugs.
73:
74: @end ifinfo
75: @menu
1.1.1.6 root 76: * Copying:: GNU General Public License says
1.1 root 77: how you can copy and share GNU CC.
78: * Contributors:: People who have contributed to GNU CC.
79: * Options:: Command options supported by @samp{gcc}.
80: * Installation:: How to configure, compile and install GNU CC.
81: * Trouble:: If you have trouble installing GNU CC.
82: * Incompatibilities:: Incompatibilities of GNU CC.
83: * Extensions:: GNU extensions to the C language.
84: * Bugs:: How to report bugs (if you want to get them fixed).
85: * Portability:: Goals of GNU CC's portability features.
86: * Interface:: Function-call interface of GNU CC output.
87: * Passes:: Order of passes, what they do, and what each file is for.
88: * RTL:: The intermediate representation that most passes work on.
89: * Machine Desc:: How to write machine description instruction patterns.
90: * Machine Macros:: How to write the machine description C macros.
91: @end menu
92:
93: @node Copying, Contributors, Top, Top
1.1.1.6 root 94: @unnumbered GNU GENERAL PUBLIC LICENSE
95: @center Version 1, February 1989
1.1 root 96:
1.1.1.6 root 97: @display
98: Copyright @copyright{} 1989 Free Software Foundation, Inc.
99: 675 Mass Ave, Cambridge, MA 02139, USA
100:
101: Everyone is permitted to copy and distribute verbatim copies
102: of this license document, but changing it is not allowed.
103: @end display
104:
105: @unnumberedsec Preamble
106:
107: The license agreements of most software companies try to keep users
108: at the mercy of those companies. By contrast, our General Public
109: License is intended to guarantee your freedom to share and change free
110: software---to make sure the software is free for all its users. The
111: General Public License applies to the Free Software Foundation's
112: software and to any other program whose authors commit to using it.
113: You can use it for your programs, too.
114:
115: When we speak of free software, we are referring to freedom, not
116: price. Specifically, the General Public License is designed to make
117: sure that you have the freedom to give away or sell copies of free
118: software, that you receive source code or can get it if you want it,
119: that you can change the software or use pieces of it in new free
120: programs; and that you know you can do these things.
121:
122: To protect your rights, we need to make restrictions that forbid
123: anyone to deny you these rights or to ask you to surrender the rights.
124: These restrictions translate to certain responsibilities for you if you
125: distribute copies of the software, or if you modify it.
126:
127: For example, if you distribute copies of a such a program, whether
128: gratis or for a fee, you must give the recipients all the rights that
129: you have. You must make sure that they, too, receive or can get the
1.1 root 130: source code. And you must tell them their rights.
131:
1.1.1.6 root 132: We protect your rights with two steps: (1) copyright the software, and
133: (2) offer you this license which gives you legal permission to copy,
134: distribute and/or modify the software.
135:
136: Also, for each author's protection and ours, we want to make certain
137: that everyone understands that there is no warranty for this free
138: software. If the software is modified by someone else and passed on, we
139: want its recipients to know that what they have is not the original, so
140: that any problems introduced by others will not reflect on the original
141: authors' reputations.
1.1 root 142:
1.1.1.6 root 143: The precise terms and conditions for copying, distribution and
144: modification follow.
1.1 root 145:
1.1.1.6 root 146: @iftex
147: @unnumberedsec TERMS AND CONDITIONS
148: @end iftex
149: @ifinfo
150: @center TERMS AND CONDITIONS
151: @end ifinfo
1.1 root 152:
1.1.1.6 root 153: @enumerate
1.1 root 154: @item
1.1.1.6 root 155: This License Agreement applies to any program or other work which
156: contains a notice placed by the copyright holder saying it may be
157: distributed under the terms of this General Public License. The
158: ``Program'', below, refers to any such program or work, and a ``work based
159: on the Program'' means either the Program or any work containing the
160: Program or a portion of it, either verbatim or with modifications. Each
161: licensee is addressed as ``you''.
162:
163: @item
164: You may copy and distribute verbatim copies of the Program's source
165: code as you receive it, in any medium, provided that you conspicuously and
166: appropriately publish on each copy an appropriate copyright notice and
167: disclaimer of warranty; keep intact all the notices that refer to this
168: General Public License and to the absence of any warranty; and give any
169: other recipients of the Program a copy of this General Public License
170: along with the Program. You may charge a fee for the physical act of
171: transferring a copy.
172:
173: @item
174: You may modify your copy or copies of the Program or any portion of
175: it, and copy and distribute such modifications under the terms of Paragraph
176: 1 above, provided that you also do the following:
1.1 root 177:
178: @itemize @bullet
179: @item
1.1.1.6 root 180: cause the modified files to carry prominent notices stating that
181: you changed the files and the date of any change; and
1.1 root 182:
183: @item
184: cause the whole of any work that you distribute or publish, that
1.1.1.6 root 185: in whole or in part contains the Program or any part thereof, either
186: with or without modifications, to be licensed at no charge to all
187: third parties under the terms of this General Public License (except
188: that you may choose to grant warranty protection to some or all
189: third parties, at your option).
190:
191: @item
192: If the modified program normally reads commands interactively when
193: run, you must cause it, when started running for such interactive use
194: in the simplest and most usual way, to print or display an
195: announcement including an appropriate copyright notice and a notice
196: that there is no warranty (or else, saying that you provide a
197: warranty) and that users may redistribute the program under these
198: conditions, and telling the user how to view a copy of this General
199: Public License.
200:
201: @item
202: You may charge a fee for the physical act of transferring a
203: copy, and you may at your option offer warranty protection in
204: exchange for a fee.
1.1 root 205: @end itemize
206:
1.1.1.6 root 207: Mere aggregation of another independent work with the Program (or its
1.1 root 208: derivative) on a volume of a storage or distribution medium does not bring
1.1.1.6 root 209: the other work under the scope of these terms.
1.1 root 210:
211: @item
1.1.1.6 root 212: You may copy and distribute the Program (or a portion or derivative of
213: it, under Paragraph 2) in object code or executable form under the terms of
214: Paragraphs 1 and 2 above provided that you also do one of the following:
1.1 root 215:
216: @itemize @bullet
217: @item
218: accompany it with the complete corresponding machine-readable
219: source code, which must be distributed under the terms of
220: Paragraphs 1 and 2 above; or,
221:
222: @item
223: accompany it with a written offer, valid for at least three
1.1.1.6 root 224: years, to give any third party free (except for a nominal charge
225: for the cost of distribution) a complete machine-readable copy of the
1.1 root 226: corresponding source code, to be distributed under the terms of
227: Paragraphs 1 and 2 above; or,
228:
229: @item
230: accompany it with the information you received as to where the
231: corresponding source code may be obtained. (This alternative is
232: allowed only for noncommercial distribution and only if you
233: received the program in object code or executable form alone.)
234: @end itemize
235:
1.1.1.6 root 236: Source code for a work means the preferred form of the work for making
237: modifications to it. For an executable file, complete source code means
238: all the source code for all modules it contains; but, as a special
239: exception, it need not include source code for modules which are standard
240: libraries that accompany the operating system on which the executable
241: file runs, or for standard header files or definitions files that
242: accompany that operating system.
243:
244: @item
245: You may not copy, modify, sublicense, distribute or transfer the
246: Program except as expressly provided under this General Public License.
247: Any attempt otherwise to copy, modify, sublicense, distribute or transfer
248: the Program is void, and will automatically terminate your rights to use
249: the Program under this License. However, parties who have received
250: copies, or rights to use copies, from you under this General Public
251: License will not have their licenses terminated so long as such parties
252: remain in full compliance.
253:
254: @item
255: By copying, distributing or modifying the Program (or any work based
256: on the Program) you indicate your acceptance of this license to do so,
257: and all its terms and conditions.
258:
259: @item
260: Each time you redistribute the Program (or any work based on the
261: Program), the recipient automatically receives a license from the original
262: licensor to copy, distribute or modify the Program subject to these
263: terms and conditions. You may not impose any further restrictions on the
264: recipients' exercise of the rights granted herein.
265:
266: @item
267: The Free Software Foundation may publish revised and/or new versions
268: of the General Public License from time to time. Such new versions will
269: be similar in spirit to the present version, but may differ in detail to
270: address new problems or concerns.
271:
272: Each version is given a distinguishing version number. If the Program
273: specifies a version number of the license which applies to it and ``any
274: later version'', you have the option of following the terms and conditions
275: either of that version or of any later version published by the Free
276: Software Foundation. If the Program does not specify a version number of
277: the license, you may choose any version ever published by the Free Software
278: Foundation.
279:
280: @item
281: If you wish to incorporate parts of the Program into other free
282: programs whose distribution conditions are different, write to the author
283: to ask for permission. For software which is copyrighted by the Free
284: Software Foundation, write to the Free Software Foundation; we sometimes
285: make exceptions for this. Our decision will be guided by the two goals
286: of preserving the free status of all derivatives of our free software and
287: of promoting the sharing and reuse of software generally.
288:
289: @iftex
290: @heading NO WARRANTY
291: @end iftex
292: @ifinfo
293: @center NO WARRANTY
294: @end ifinfo
295:
296: @item
297: BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
298: FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
299: OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
300: PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
301: OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
302: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
303: TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
304: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
305: REPAIR OR CORRECTION.
306:
307: @item
308: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
309: ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
310: REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
311: INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
312: ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
313: LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
314: SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
315: WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
316: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
1.1 root 317: @end enumerate
318:
1.1.1.6 root 319: @iftex
320: @heading END OF TERMS AND CONDITIONS
321: @end iftex
322: @ifinfo
323: @center END OF TERMS AND CONDITIONS
324: @end ifinfo
325:
326: @page
327: @unnumberedsec Appendix: How to Apply These Terms to Your New Programs
328:
329: If you develop a new program, and you want it to be of the greatest
330: possible use to humanity, the best way to achieve this is to make it
331: free software which everyone can redistribute and change under these
332: terms.
333:
334: To do so, attach the following notices to the program. It is safest to
335: attach them to the start of each source file to most effectively convey
336: the exclusion of warranty; and each file should have at least the
337: ``copyright'' line and a pointer to where the full notice is found.
338:
339: @smallexample
340: @var{one line to give the program's name and a brief idea of what it does.}
341: Copyright (C) 19@var{yy} @var{name of author}
342:
343: This program is free software; you can redistribute it and/or modify
344: it under the terms of the GNU General Public License as published by
345: the Free Software Foundation; either version 1, or (at your option)
346: any later version.
347:
348: This program is distributed in the hope that it will be useful,
349: but WITHOUT ANY WARRANTY; without even the implied warranty of
350: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
351: GNU General Public License for more details.
352:
353: You should have received a copy of the GNU General Public License
354: along with this program; if not, write to the Free Software
355: Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
356: @end smallexample
357:
358: Also add information on how to contact you by electronic and paper mail.
359:
360: If the program is interactive, make it output a short notice like this
361: when it starts in an interactive mode:
362:
363: @smallexample
364: Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
365: Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
366: This is free software, and you are welcome to redistribute it
367: under certain conditions; type `show c' for details.
368: @end smallexample
369:
370: The hypothetical commands `show w' and `show c' should show the
371: appropriate parts of the General Public License. Of course, the
372: commands you use may be called something other than `show w' and `show
373: c'; they could even be mouse-clicks or menu items---whatever suits your
374: program.
375:
376: You should also get your employer (if you work as a programmer) or your
377: school, if any, to sign a ``copyright disclaimer'' for the program, if
378: necessary. Here a sample; alter the names:
379:
380: @example
381: Yoyodyne, Inc., hereby disclaims all copyright interest in the
382: program `Gnomovision' (a program to direct compilers to make passes
383: at assemblers) written by James Hacker.
384:
385: @var{signature of Ty Coon}, 1 April 1989
386: Ty Coon, President of Vice
387: @end example
388:
389: That's all there is to it!
1.1 root 390:
391: @node Contributors, Options, Copying, Top
392: @unnumbered Contributors to GNU CC
393:
394: In addition to Richard Stallman, several people have written parts
395: of GNU CC.
396:
397: @itemize @bullet
398: @item
399: The idea of using RTL and some of the optimization ideas came from the
400: U. of Arizona Portable Optimizer, written by Jack Davidson and
401: Christopher Fraser. See ``Register Allocation and Exhaustive Peephole
402: Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
403: 857-866.
404:
405: @item
406: Paul Rubin wrote most of the preprocessor.
407:
408: @item
1.1.1.6 root 409: Leonard Tower wrote parts of the parser, RTL generator, and RTL
1.1 root 410: definitions, and of the Vax machine description.
411:
412: @item
413: Ted Lemon wrote parts of the RTL reader and printer.
414:
415: @item
416: Jim Wilson implemented loop strength reduction and some other
417: loop optimizations.
418:
419: @item
420: Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
421: the support for the SONY NEWS machine.
422:
423: @item
424: Charles LaBrec contributed the support for the Integrated Solutions
425: 68020 system.
426:
427: @item
428: Michael Tiemann of MCC wrote most of the description of the National
429: Semiconductor 32000 series cpu. He also wrote the code for inline
430: function integration and for the SPARC cpu and Motorola 88000 cpu
431: and part of the Sun FPA support.
432:
433: @item
434: Jan Stein of the Chalmers Computer Society provided support for
435: Genix, as well as part of the 32000 machine description.
436:
437: @item
438: Randy Smith finished the Sun FPA support.
439:
440: @item
441: Robert Brown implemented the support for Encore 32000 systems.
442:
443: @item
444: David Kashtan of SRI adapted GNU CC to the Vomit-Making System.
445:
446: @item
447: Alex Crain provided changes for the 3b1.
448:
449: @item
450: Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for
451: the 9000 series 300.
452:
453: @item
454: William Schelter did most of the work on the Intel 80386 support.
1.1.1.5 root 455:
456: @item
457: Christopher Smith did the port for Convex machines.
458:
459: @item
460: Paul Petersen wrote the machine description for the Alliant FX/8.
1.1.1.7 ! root 461:
! 462: @item
! 463: Alain Lichnewsky ported GNU CC to the MIPS cpu.
1.1 root 464: @end itemize
465:
466: @node Options, Installation, Contributors, Top
467: @chapter GNU CC Command Options
468:
469: The GNU C compiler uses a command syntax much like the Unix C compiler.
470: The @code{gcc} program accepts options and file names as operands.
471: Multiple single-letter options may @emph{not} be grouped: @samp{-dr} is
472: very different from @samp{-d -r}.
473:
474: When you invoke GNU CC, it normally does preprocessing, compilation,
475: assembly and linking. File names which end in @samp{.c} are taken as C
1.1.1.5 root 476: source to be preprocessed and compiled; file names ending in @samp{.i}
477: are taken as preprocessor output to be compiled; compiler output files
478: plus any input files with names ending in @samp{.s} are assembled; then
479: the resulting object files, plus any other input files, are linked
480: together to produce an executable.
1.1 root 481:
482: Command options allow you to stop this process at an intermediate stage.
483: For example, the @samp{-c} option says not to run the linker. Then the
484: output consists of object files output by the assembler.
485:
1.1.1.5 root 486: Other command options are passed on to one stage of processing. Some
487: options control the preprocessor and others the compiler itself. Yet
488: other options control the assembler and linker; these are not documented
489: here, but you rarely need to use any of them.
1.1 root 490:
491: Here are the options to control the overall compilation process, including
492: those that say whether to link, whether to assemble, and so on.
493:
494: @table @samp
495: @item -o @var{file}
496: Place output in file @var{file}. This applies regardless to whatever
497: sort of output is being produced, whether it be an executable file,
498: an object file, an assembler file or preprocessed C code.
499:
500: If @samp{-o} is not specified, the default is to put an executable file
501: in @file{a.out}, the object file @file{@var{source}.c} in
502: @file{@var{source}.o}, an assembler file in @file{@var{source}.s}, and
503: preprocessed C on standard output.@refill
504:
505: @item -c
506: Compile or assemble the source files, but do not link. Produce object
507: files with names made by replacing @samp{.c} or @samp{.s} with
508: @samp{.o} at the end of the input file names. Do nothing at all for
509: object files specified as input.
510:
511: @item -S
512: Compile into assembler code but do not assemble. The assembler output
513: file name is made by replacing @samp{.c} with @samp{.s} at the end of
514: the input file name. Do nothing at all for assembler source files or
515: object files specified as input.
516:
517: @item -E
518: Run only the C preprocessor. Preprocess all the C source files
519: specified and output the results to standard output.
520:
521: @item -v
522: Compiler driver program prints the commands it executes as it runs
523: the preprocessor, compiler proper, assembler and linker. Some of
524: these are directed to print their own version numbers.
525:
1.1.1.5 root 526: @item -pipe
527: Use pipes rather than temporary files for communication between the
528: various stages of compilation. This fails to work on some systems
529: where the assembler is unable to read from a pipe; but the GNU
530: assembler has no trouble.
531:
1.1 root 532: @item -B@var{prefix}
533: Compiler driver program tries @var{prefix} as a prefix for each
534: program it tries to run. These programs are @file{cpp}, @file{cc1},
535: @file{as} and @file{ld}.
536:
537: For each subprogram to be run, the compiler driver first tries the
538: @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
539: was not specified, the driver tries two standard prefixes, which are
540: @file{/usr/lib/gcc-} and @file{/usr/local/lib/gcc-}. If neither of
541: those results in a file name that is found, the unmodified program
542: name is searched for using the directories specified in your
543: @samp{PATH} environment variable.
544:
545: The run-time support file @file{gnulib} is also searched for using
546: the @samp{-B} prefix, if needed. If it is not found there, the two
547: standard prefixes above are tried, and that is all. The file is left
548: out of the link if it is not found by those means. Most of the time,
549: on most machines, you can do without it.
1.1.1.5 root 550:
551: You can get a similar result from the environment variable;
552: @code{GCC_EXEC_PREFIX} if it is defined, its value is used as a prefix
553: in the same way. If both the @samp{-B} option and the
554: @code{GCC_EXEC_PREFIX} variable are present, the @samp{-B} option is
555: used first and the environment variable value second.
1.1 root 556: @end table
557:
558: These options control the details of C compilation itself.
559:
560: @table @samp
561: @item -ansi
562: Support all ANSI standard C programs.
563:
564: This turns off certain features of GNU C that are incompatible with
565: ANSI C, such as the @code{asm}, @code{inline} and @code{typeof}
566: keywords, and predefined macros such as @code{unix} and @code{vax}
567: that identify the type of system you are using. It also enables the
568: undesirable and rarely used ANSI trigraph feature.
569:
1.1.1.7 ! root 570: The alternate keywords @code{__asm}, @code{__inline} and
! 571: @code{__typeof} continue to work despite @samp{-ansi}. You would not
! 572: want to use them in an ANSI C program, of course, but it useful to put
! 573: them in header files that might be included in compilations done with
! 574: @samp{-ansi}. Alternate predefined macros such as @code{__unix} and
! 575: @code{__vax} are also available, with or without @samp{-ansi}.
! 576:
1.1 root 577: The @samp{-ansi} option does not cause non-ANSI programs to be
578: rejected gratuitously. For that, @samp{-pedantic} is required in
579: addition to @samp{-ansi}.
580:
581: The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
582: option is used. Some header files may notice this macro and refrain
583: from declaring certain functions or defining certain macros that the
1.1.1.7 ! root 584: ANSI standard doesn't call for; this is to avoid interfering with any
! 585: programs that might use these names for other things.
1.1 root 586:
587: @item -traditional
588: Attempt to support some aspects of traditional C compilers.
589: Specifically:
590:
591: @itemize @bullet
592: @item
593: All @code{extern} declarations take effect globally even if they
594: are written inside of a function definition. This includes implicit
595: declarations of functions.
596:
597: @item
598: The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
599: and @code{volatile} are not recognized.@refill
600:
601: @item
602: Comparisons between pointers and integers are always allowed.
603:
604: @item
605: Integer types @code{unsigned short} and @code{unsigned char} promote
606: to @code{unsigned int}.
607:
608: @item
609: Out-of-range floating point literals are not an error.
610:
611: @item
1.1.1.2 root 612: All automatic variables not declared @code{register} are preserved by
613: @code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
614: not declared @code{volatile} may be clobbered.
615:
616: @item
1.1 root 617: In the preprocessor, comments convert to nothing at all, rather than
618: to a space. This allows traditional token concatenation.
619:
620: @item
621: In the preprocessor, macro arguments are recognized within string
622: constants in a macro definition (and their values are stringified,
623: though without additional quote marks, when they appear in such a
624: context). The preprocessor always considers a string constant to end
625: at a newline.
626:
627: @item
628: The predefined macro @code{__STDC__} is not defined when you use
629: @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
630: which @code{__GNUC__} indicates are not affected by
631: @samp{-traditional}). If you need to write header files that work
632: differently depending on whether @samp{-traditional} is in use, by
633: testing both of these predefined macros you can distinguish four
634: situations: GNU C, traditional GNU C, other ANSI C compilers, and
635: other old C compilers.
636: @end itemize
637:
638: @item -O
639: Optimize. Optimizing compilation takes somewhat more time, and a lot
640: more memory for a large function.
641:
642: Without @samp{-O}, the compiler's goal is to reduce the cost of
643: compilation and to make debugging produce the expected results.
644: Statements are independent: if you stop the program with a breakpoint
645: between statements, you can then assign a new value to any variable or
646: change the program counter to any other statement in the function and
647: get exactly the results you would expect from the source code.
648:
649: Without @samp{-O}, only variables declared @code{register} are
650: allocated in registers. The resulting compiled code is a little worse
651: than produced by PCC without @samp{-O}.
652:
653: With @samp{-O}, the compiler tries to reduce code size and execution
654: time.
655:
656: Some of the @samp{-f} options described below turn specific kinds of
657: optimization on or off.
658:
659: @item -g
660: Produce debugging information in the operating system's native format
661: (for DBX or SDB). GDB also can work with this debugging information.
662:
663: Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
664: @samp{-O}. The shortcuts taken by optimized code may occasionally
665: produce surprising results: some variables you declared may not exist
666: at all; flow of control may briefly move where you did not expect it;
667: some statements may not be executed because they compute constant
668: results or their values were already at hand; some statements may
669: execute in different places because they were moved out of loops.
670: Nevertheless it proves possible to debug optimized output. This makes
671: it reasonable to use the optimizer for programs that might have bugs.
672:
673: @item -gg
674: Produce debugging information in GDB's own format. This requires the
675: GNU assembler and linker in order to work.
676:
677: This feature will probably be eliminated. It was intended to enable
678: GDB to read the symbol table faster, but it doesn't result in enough
679: of a speedup to be worth the larger object files and executables. We
1.1.1.2 root 680: are working on other ways of making GDB start even faster, which work
681: with DBX format debugging information and could be made to work with
682: SDB format.
1.1 root 683:
684: @item -w
685: Inhibit all warning messages.
686:
687: @item -W
688: Print extra warning messages for these events:
689:
690: @itemize @bullet
691: @item
692: An automatic variable is used without first being initialized.
693:
694: These warnings are possible only in optimizing compilation,
695: because they require data flow information that is computed only
1.1.1.6 root 696: when optimizing. If you don't specify @samp{-O}, you simply won't
697: get these warnings.
698:
699: These warnings occur only for variables that are candidates for
700: register allocation. Therefore, they do not occur for a variable that
701: is declared @code{volatile}, or whose address is taken, or whose size
702: is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
703: structures, unions or arrays, even when they are in registers.
704:
705: Note that there may be no warning about a variable that is used only
706: to compute a value that itself is never used, because such
707: computations may be deleted by data flow analysis before the warnings
708: are printed.
1.1 root 709:
710: These warnings are made optional because GNU CC is not smart
711: enough to see all the reasons why the code might be correct
712: despite appearing to have an error. Here is one example of how
713: this can happen:
714:
715: @example
716: @{
717: int x;
718: switch (y)
719: @{
720: case 1: x = 1;
721: break;
722: case 2: x = 4;
723: break;
724: case 3: x = 5;
725: @}
726: foo (x);
727: @}
728: @end example
729:
730: @noindent
731: If the value of @code{y} is always 1, 2 or 3, then @code{x} is
732: always initialized, but GNU CC doesn't know this. Here is
733: another common case:
734:
735: @example
736: @{
737: int save_y;
738: if (change_y) save_y = y, y = new_y;
739: @dots{}
740: if (change_y) y = save_y;
741: @}
742: @end example
743:
744: @noindent
745: This has no bug because @code{save_y} is used only if it is set.
746:
1.1.1.5 root 747: Some spurious warnings can be avoided if you declare as
748: @code{volatile} all the functions you use that never return.
749: @xref{Function Attributes}.
750:
1.1 root 751: @item
752: A nonvolatile automatic variable might be changed by a call to
753: @code{longjmp}. These warnings as well are possible only in
754: optimizing compilation.
755:
756: The compiler sees only the calls to @code{setjmp}. It cannot know
757: where @code{longjmp} will be called; in fact, a signal handler could
758: call it at any point in the code. As a result, you may get a warning
759: even when there is in fact no problem because @code{longjmp} cannot
760: in fact be called at the place which would cause a problem.
761:
762: @item
763: A function can return either with or without a value. (Falling
764: off the end of the function body is considered returning without
1.1.1.6 root 765: a value.) For example, this function would evoke such a
1.1 root 766: warning:
767:
768: @example
769: foo (a)
770: @{
771: if (a > 0)
772: return a;
773: @}
774: @end example
775:
776: Spurious warnings can occur because GNU CC does not realize that
777: certain functions (including @code{abort} and @code{longjmp})
778: will never return.
1.1.1.4 root 779:
780: @item
781: An expression-statement contains no side effects.
1.1 root 782: @end itemize
783:
784: In the future, other useful warnings may also be enabled by this
785: option.
786:
787: @item -Wimplicit
788: Warn whenever a function is implicitly declared.
789:
790: @item -Wreturn-type
791: Warn whenever a function is defined with a return-type that defaults
792: to @code{int}. Also warn about any @code{return} statement with no
793: return-value in a function whose return-type is not @code{void}.
794:
795: @item -Wunused
1.1.1.5 root 796: Warn whenever a local variable is unused aside from its declaration,
797: and whenever a function is declared static but never defined.
1.1 root 798:
1.1.1.7 ! root 799: @item -Wshadow
! 800: Warn whenever a local variable shadows another local variable.
! 801:
! 802: @item -Wid-clash-@var{len}
! 803: Warn whenever two distinct identifiers match in the first @var{len}
! 804: characters. This may help you prepare a program that will compile
! 805: with certain obsolete, brain-damaged compilers.
! 806:
! 807: @item -Wswitch
! 808: Warn whenever a @code{switch} statement has an index of enumeral type
! 809: and lacks a @code{case} for one or more of the named codes of that
! 810: enumeration. (The presence of a @code{default} label prevents this
! 811: warning.) @code{case} labels outside the enumeration range also
! 812: provoke warnings when this option is used.
! 813:
1.1 root 814: @item -Wcomment
815: Warn whenever a comment-start sequence @samp{/*} appears in a comment.
816:
1.1.1.7 ! root 817: @item -Wtrigraphs
! 818: Warn if any trigraphs are encountered (assuming they are enabled).
! 819:
1.1 root 820: @item -Wall
821: All of the above @samp{-W} options combined.
822:
1.1.1.6 root 823: @item -Wcast-qual
824: Warn whenever a pointer is cast so as to remove a type qualifier from
825: the target type. For example, warn if a @code{const char *} is cast
826: to an ordinary @code{char *}.
827:
1.1 root 828: @item -Wwrite-strings
829: Give string constants the type @code{const char[@var{length}]} so that
830: copying the address of one into a non-@code{const} @code{char *}
831: pointer will get a warning. These warnings will help you find at
832: compile time code that can try to write into a string constant, but
833: only if you have been very careful about using @code{const} in
834: declarations and prototypes. Otherwise, it will just be a nuisance;
835: this is why we did not make @samp{-Wall} request these warnings.
836:
837: @item -p
838: Generate extra code to write profile information suitable for the
839: analysis program @code{prof}.
840:
841: @item -pg
842: Generate extra code to write profile information suitable for the
843: analysis program @code{gprof}.
844:
1.1.1.6 root 845: @item -a
846: Generate extra code to write profile information for basic blocks,
847: suitable for the analysis program @code{tcov}. Eventually GNU
848: @code{gprof} should be extended to process this data.
849:
1.1 root 850: @item -l@var{library}
851: Search a standard list of directories for a library named
852: @var{library}, which is actually a file named
853: @file{lib@var{library}.a}. The linker uses this file as if it
854: had been specified precisely by name.
855:
856: The directories searched include several standard system directories
857: plus any that you specify with @samp{-L}.
858:
859: Normally the files found this way are library files---archive files
860: whose members are object files. The linker handles an archive file by
861: scanning through it for members which define symbols that have so far
862: been referenced but not defined. But if the file that is found is an
863: ordinary object file, it is linked in the usual fashion. The only
864: difference between using an @samp{-l} option and specifying a file name
865: is that @samp{-l} searches several directories.
866:
867: @item -L@var{dir}
868: Add directory @var{dir} to the list of directories to be searched
869: for @samp{-l}.
870:
871: @item -nostdlib
872: Don't use the standard system libraries and startup files when
873: linking. Only the files you specify (plus @file{gnulib}) will be
874: passed to the linker.
875:
876: @item -m@var{machinespec}
877: Machine-dependent option specifying something about the type of target
878: machine. These options are defined by the macro
879: @code{TARGET_SWITCHES} in the machine description. The default for
880: the options is also defined by that macro, which enables you to change
881: the defaults.@refill
882:
883: These are the @samp{-m} options defined in the 68000 machine
884: description:
885:
886: @table @samp
887: @item -m68020
888: @itemx -mc68020
889: Generate output for a 68020 (rather than a 68000). This is the
890: default if you use the unmodified sources.
891:
892: @item -m68000
893: @item -mc68000
894: Generate output for a 68000 (rather than a 68020).
895:
896: @item -m68881
897: Generate output containing 68881 instructions for floating point.
898: This is the default if you use the unmodified sources.
899:
900: @item -mfpa
901: Generate output containing Sun FPA instructions for floating point.
902:
903: @item -msoft-float
904: Generate output containing library calls for floating point.
905:
906: @item -mshort
907: Consider type @code{int} to be 16 bits wide, like @code{short int}.
908:
909: @item -mnobitfield
910: Do not use the bit-field instructions. @samp{-m68000} implies
911: @samp{-mnobitfield}.
912:
913: @item -mbitfield
914: Do use the bit-field instructions. @samp{-m68020} implies
915: @samp{-mbitfield}. This is the default if you use the unmodified
916: sources.
917:
918: @item -mrtd
919: Use a different function-calling convention, in which functions
920: that take a fixed number of arguments return with the @code{rtd}
921: instruction, which pops their arguments while returning. This
922: saves one instruction in the caller since there is no need to pop
923: the arguments there.
924:
925: This calling convention is incompatible with the one normally
926: used on Unix, so you cannot use it if you need to call libraries
927: compiled with the Unix compiler.
928:
929: Also, you must provide function prototypes for all functions that
930: take variable numbers of arguments (including @code{printf});
931: otherwise incorrect code will be generated for calls to those
932: functions.
933:
934: In addition, seriously incorrect code will result if you call a
935: function with too many arguments. (Normally, extra arguments are
936: harmlessly ignored.)
937:
938: The @code{rtd} instruction is supported by the 68010 and 68020
939: processors, but not by the 68000.
940: @end table
941:
942: These @samp{-m} options are defined in the Vax machine description:
943:
944: @table @samp
945: @item -munix
946: Do not output certain jump instructions (@code{aobleq} and so on)
947: that the Unix assembler for the Vax cannot handle across long
948: ranges.
949:
950: @item -mgnu
951: Do output those jump instructions, on the assumption that you
952: will assemble with the GNU assembler.
953:
954: @item -mg
955: Output code for g-format floating point numbers instead of d-format.
956: @end table
957:
1.1.1.5 root 958: These @samp{-m} switches are supported on the Sparc:
959:
960: @table @samp
961: @item -mfpu
962: Generate output containing floating point instructions. This is the
963: default if you use the unmodified sources.
964:
965: @item -msoft-float
966: Generate output containing library calls for floating point.
967:
968: @item -mno-epilogue
1.1.1.6 root 969: Generate separate return instructions for @code{return} statements.
970: This has both advantages and disadvantages; I don't recall what they
971: are.
1.1.1.5 root 972: @end table
973:
974: These @samp{-m} options are defined in the Convex machine description:
975:
976: @table @samp
977: @item -mc1
978: Generate output for a C1. This is the default when the compiler is
979: configured for a C1.
980:
981: @item -mc2
982: Generate output for a C2. This is the default when the compiler is
983: configured for a C2.
984:
985: @item -margcount
986: Generate code which puts an argument count in the word preceding each
987: argument list. Some nonportable Convex and Vax programs need this
988: word. (Debuggers don't; this info is in the symbol table.)
989:
990: @item -mnoargcount
991: Omit the argument count word. This is the default if you use the
992: unmodified sources.
993: @end table
994:
1.1 root 995: @item -f@var{flag}
1.1.1.4 root 996: Specify machine-independent flags. Most flags have both positive and
997: negative forms; the negative form of @samp{-ffoo} would be
998: @samp{-fno-foo}. In the table below, only one of the forms is
999: listed---the one which is not the default. You can figure out the
1000: other form by either removing @samp{no-} or adding it.
1.1 root 1001:
1002: @table @samp
1.1.1.6 root 1003: @item -fpcc-struct-return
1004: Use the same convention for returning @code{struct} and @code{union}
1005: values that is used by the usual C compiler on your system. This
1006: convention is less efficient for small structures, and on many
1007: machines it fails to be reentrant; but it has the advantage of
1008: allowing intercallability between GCC-compiled code and PCC-compiled
1009: code.
1010:
1.1 root 1011: @item -ffloat-store
1012: Do not store floating-point variables in registers. This
1013: prevents undesirable excess precision on machines such as the
1014: 68000 where the floating registers (of the 68881) keep more
1015: precision than a @code{double} is supposed to have.
1016:
1017: For most programs, the excess precision does only good, but a few
1018: programs rely on the precise definition of IEEE floating point.
1019: Use @samp{-ffloat-store} for such programs.
1020:
1021: @item -fno-asm
1022: Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1.1.1.7 ! root 1023: keyword. These words may then be used as identifiers. You can
! 1024: use @code{__asm}, @code{__inline} and @code{__typeof} instead.
1.1 root 1025:
1026: @item -fno-defer-pop
1027: Always pop the arguments to each function call as soon as that
1028: function returns. Normally the compiler (when optimizing) lets
1029: arguments accumulate on the stack for several function calls and
1030: pops them all at once.
1031:
1032: @item -fstrength-reduce
1033: Perform the optimizations of loop strength reduction and
1034: elimination of iteration variables.
1035:
1036: @item -fcombine-regs
1037: Allow the combine pass to combine an instruction that copies one
1038: register into another. This might or might not produce better
1039: code when used in addition to @samp{-O}. I am interested in
1040: hearing about the difference this makes.
1041:
1042: @item -fforce-mem
1043: Force memory operands to be copied into registers before doing
1044: arithmetic on them. This may produce better code by making all
1045: memory references potential common subexpressions. When they are
1046: not common subexpressions, instruction combination should
1047: eliminate the separate register-load. I am interested in hearing
1048: about the difference this makes.
1049:
1050: @item -fforce-addr
1051: Force memory address constants to be copied into registers before
1052: doing arithmetic on them. This may produce better code just as
1053: @samp{-fforce-mem} may. I am interested in hearing about the
1054: difference this makes.
1055:
1056: @item -fomit-frame-pointer
1057: Don't keep the frame pointer in a register for functions that
1058: don't need one. This avoids the instructions to save, set up and
1059: restore frame pointers; it also makes an extra register available
1060: in many functions. @strong{It also makes debugging impossible.}
1061:
1062: On some machines, such as the Vax, this flag has no effect,
1063: because the standard calling sequence automatically handles the
1064: frame pointer and nothing is saved by pretending it doesn't
1065: exist. The machine-description macro
1066: @code{FRAME_POINTER_REQUIRED} controls whether a target machine
1067: supports this flag. @xref{Registers}.@refill
1068:
1069: @item -finline-functions
1070: Integrate all simple functions into their callers. The compiler
1071: heuristically decides which functions are simple enough to be
1072: worth integrating in this way.
1073:
1074: If all calls to a given function are integrated, and the function
1075: is declared @code{static}, then the function is normally not
1076: output as assembler code in its own right.
1077:
1.1.1.6 root 1078: @item -fcaller-saves
1079: Enable values to be allocated in registers that will be clobbered by
1080: function calls, by emitting extra instructions to save and restore the
1081: registers around such calls. Such allocation is done only when it
1082: seems to result in better code than would otherwise be produced.
1083:
1084: This option is enabled by default on certain machines, usually those
1085: which have no call-preserved registers to use instead.
1086:
1.1 root 1087: @item -fkeep-inline-functions
1088: Even if all calls to a given function are integrated, and the
1089: function is declared @code{static}, nevertheless output a
1090: separate run-time callable version of the function.
1091:
1092: @item -fwritable-strings
1093: Store string constants in the writable data segment and don't
1094: uniquize them. This is for compatibility with old programs which
1095: assume they can write into string constants. Writing into string
1096: constants is a very bad idea; ``constants'' should be constant.
1097:
1.1.1.4 root 1098: @item -fcond-mismatch
1099: Allow conditional expressions with mismatched types in the second and
1100: third arguments. The value of such an expression is void.
1101:
1.1 root 1102: @item -fno-function-cse
1103: Do not put function addresses in registers; make each instruction
1104: that calls a constant function contain the function's address
1105: explicitly.
1106:
1107: This option results in less efficient code, but some strange
1108: hacks that alter the assembler output may be confused by the
1109: optimizations performed when this option is not used.
1110:
1111: @item -fvolatile
1112: Consider all memory references through pointers to be volatile.
1113:
1.1.1.4 root 1114: @item -fshared-data
1115: Requests that the data and non-@code{const} variables of this
1116: compilation be shared data rather than private data. The distinction
1117: makes sense only on certain operating systems, where shared data is
1118: shared between processes running the same program, while private data
1119: exists in one copy per process.
1120:
1.1 root 1121: @item -funsigned-char
1.1.1.4 root 1122: Let the type @code{char} be the unsigned, like @code{unsigned char}.
1.1 root 1123:
1124: Each kind of machine has a default for what @code{char} should
1125: be. It is either like @code{unsigned char} by default or like
1126: @code{signed char} by default. (Actually, at present, the
1127: default is always signed.)
1128:
1129: The type @code{char} is always a distinct type from either
1130: @code{signed char} or @code{unsigned char}, even though its
1131: behavior is always just like one of those two.
1132:
1.1.1.4 root 1133: Note that this is equivalent to @samp{-fno-signed-char}, which is the
1134: negative form of @samp{-fsigned-char}.
1135:
1.1 root 1136: @item -fsigned-char
1137: Let the type @code{char} be signed, like @code{signed char}.
1138:
1.1.1.4 root 1139: Note that this is equivalent to @samp{-fno-unsigned-char}, which is
1140: the negative form of @samp{-funsigned-char}.
1141:
1.1 root 1142: @item -ffixed-@var{reg}
1143: Treat the register named @var{reg} as a fixed register; generated
1144: code should never refer to it (except perhaps as a stack pointer,
1145: frame pointer or in some other fixed role).
1146:
1147: @var{reg} must be the name of a register. The register names
1148: accepted are machine-specific and are defined in the
1149: @code{REGISTER_NAMES} macro in the machine description macro
1150: file.
1151:
1.1.1.4 root 1152: This flag does not have a negative form, because it specifies a
1153: three-way choice.
1154:
1.1 root 1155: @item -fcall-used-@var{reg}
1156: Treat the register named @var{reg} as an allocatable register
1157: that is clobbered by function calls. It may be allocated for
1158: temporaries or variables that do not live across a call.
1159: Functions compiled this way will not save and restore the
1160: register @var{reg}.
1161:
1162: Use of this flag for a register that has a fixed pervasive role
1163: in the machine's execution model, such as the stack pointer or
1164: frame pointer, will produce disastrous results.
1165:
1.1.1.4 root 1166: This flag does not have a negative form, because it specifies a
1167: three-way choice.
1168:
1.1 root 1169: @item -fcall-saved-@var{reg}
1170: Treat the register named @var{reg} as an allocatable register
1171: saved by functions. It may be allocated even for temporaries or
1172: variables that live across a call. Functions compiled this way
1173: will save and restore the register @var{reg} if they use it.
1174:
1175: Use of this flag for a register that has a fixed pervasive role
1176: in the machine's execution model, such as the stack pointer or
1177: frame pointer, will produce disastrous results.
1178:
1179: A different sort of disaster will result from the use of this
1180: flag for a register in which function values may be returned.
1.1.1.4 root 1181:
1182: This flag does not have a negative form, because it specifies a
1183: three-way choice.
1.1 root 1184: @end table
1185:
1186: @item -d@var{letters}
1187: Says to make debugging dumps at times specified by @var{letters}.
1188: Here are the possible letters:
1189:
1190: @table @samp
1191: @item r
1192: Dump after RTL generation.
1193: @item j
1194: Dump after first jump optimization.
1195: @item J
1196: Dump after last jump optimization.
1197: @item s
1198: Dump after CSE (including the jump optimization that sometimes
1199: follows CSE).
1200: @item L
1201: Dump after loop optimization.
1202: @item f
1203: Dump after flow analysis.
1204: @item c
1205: Dump after instruction combination.
1206: @item l
1207: Dump after local register allocation.
1208: @item g
1209: Dump after global register allocation.
1210: @item m
1211: Print statistics on memory usage, at the end of the run.
1212: @end table
1213:
1214: @item -pedantic
1215: Issue all the warnings demanded by strict ANSI standard C; reject
1216: all programs that use forbidden extensions.
1217:
1218: Valid ANSI standard C programs should compile properly with or without
1219: this option (though a rare few will require @samp{-ansi}). However,
1220: without this option, certain GNU extensions and traditional C features
1221: are supported as well. With this option, they are rejected. There is
1222: no reason to @i{use} this option; it exists only to satisfy pedants.
1.1.1.5 root 1223:
1224: @item -static
1225: On Suns running version 4, this prevents linking with the shared
1226: libraries. (@samp{-g} has the same effect.)
1.1 root 1227: @end table
1228:
1229: These options control the C preprocessor, which is run on each C source
1230: file before actual compilation. If you use the @samp{-E} option, nothing
1231: is done except C preprocessing. Some of these options make sense only
1232: together with @samp{-E} because they request preprocessor output that is
1233: not suitable for actual compilation.
1234:
1235: @table @samp
1236: @item -C
1237: Tell the preprocessor not to discard comments. Used with the
1238: @samp{-E} option.
1239:
1240: @item -I@var{dir}
1241: Search directory @var{dir} for include files.
1242:
1243: @item -I-
1244: Any directories specified with @samp{-I} options before the @samp{-I-}
1245: option are searched only for the case of @samp{#include "@var{file}"};
1246: they are not searched for @samp{#include <@var{file}>}.
1247:
1248: If additional directories are specified with @samp{-I} options after
1249: the @samp{-I-}, these directories are searched for all @samp{#include}
1250: directives. (Ordinarily @emph{all} @samp{-I} directories are used
1251: this way.)
1252:
1253: In addition, the @samp{-I-} option inhibits the use of the current
1254: directory as the first search directory for @samp{#include
1255: "@var{file}"}. Therefore, the current directory is searched only if
1256: it is requested explicitly with @samp{-I.}. Specifying both
1257: @samp{-I-} and @samp{-I.} allows you to control precisely which
1258: directories are searched before the current one and which are searched
1259: after.
1260:
1261: @item -nostdinc
1262: Do not search the standard system directories for header files. Only
1263: the directories you have specified with @samp{-I} options (and the
1264: current directory, if appropriate) are searched.
1265:
1266: Between @samp{-nostdinc} and @samp{-I-}, you can eliminate all
1267: directories from the search path except those you specify.
1268:
1269: @item -M
1270: Tell the preprocessor to output a rule suitable for @code{make}
1271: describing the dependencies of each source file. For each source
1272: file, the preprocessor outputs one @code{make}-rule whose target is
1273: the object file name for that source file and whose dependencies are
1274: all the files @samp{#include}d in it. This rule may be a single line
1275: or may be continued with @samp{\}-newline if it is long.
1276:
1277: @samp{-M} implies @samp{-E}.
1278:
1279: @item -MM
1280: Like @samp{-M} but the output mentions only the user-header files
1281: included with @samp{#include "@var{file}"}. System header files
1282: included with @samp{#include <@var{file}>} are omitted.
1283:
1284: @samp{-MM} implies @samp{-E}.
1285:
1286: @item -D@var{macro}
1287: Define macro @var{macro} with the empty string as its definition.
1288:
1289: @item -D@var{macro}=@var{defn}
1290: Define macro @var{macro} as @var{defn}.
1291:
1292: @item -U@var{macro}
1293: Undefine macro @var{macro}.
1294:
1.1.1.7 ! root 1295: @item -trigraphs
1.1 root 1296: Support ANSI C trigraphs. You don't want to know about this
1297: brain-damage. The @samp{-ansi} option also has this effect.
1298: @end table
1299:
1300: @node Installation, Trouble, Options, Top
1301: @chapter Installing GNU CC
1302:
1303: Here is the procedure for installing GNU CC on a Unix system.
1304: @menu
1305: * VMS Install:: See below for installation on VMS.
1306: @end menu
1307: @iftex
1308: (See below for VMS.)
1309: @end iftex
1310:
1311: @enumerate
1312: @item
1313: Edit @file{Makefile}. If you are using HPUX, or any form of system V,
1314: you must make a few changes described in comments at the beginning of
1.1.1.4 root 1315: the file. Genix requires changes also.
1.1 root 1316:
1317: @item
1318: On a Sequent system, go to the Berkeley universe.
1319:
1320: @item
1.1.1.2 root 1321: Choose configuration files. The easy way to do this is to run the
1322: command file @file{config.gcc} with a single argument, which is the
1.1.1.4 root 1323: name of the machine (and operating system, in some cases).
1324:
1325: Here is a list of the possible arguments:
1326:
1327: @table @samp
1328: @item vax
1329: Vaxes running BSD.
1330: @item vms
1331: Vaxes running VMS.
1332: @item vax-sysv
1333: Vaxes running system V.
1334: @item i386-sysv
1335: Intel 386 PCs running system V.
1.1.1.5 root 1336: @item i386-sysv-gas
1337: Intel 386 PCs running system V, using the GNU assembler and GNU
1338: linker.
1.1.1.6 root 1339: @item sequent-i386
1.1.1.4 root 1340: Sequent with Intel 386 processors.
1341: @item sun2
1342: Sun 2 running system version 2 or 3.
1343: @item sun3
1.1.1.5 root 1344: Sun 3 running system version 2 or 3, with 68881.
1.1.1.7 ! root 1345:
! 1346: Note there we do not provide a configuration file to use an FPA
! 1347: by default because programs that establish signal handlers for
! 1348: floating point traps inherently cannot work with the FPA.
1.1.1.5 root 1349: @item sun3-nfp
1350: Sun 3 running system version 2 or 3, without 68881.
1.1.1.4 root 1351: @item sun4
1352: Sun 4 running system version 2 or 3.
1353: @item sun2-os4
1354: Sun 2 running system version 4.
1355: @item sun3-os4
1.1.1.5 root 1356: Sun 3 running system version 4, with 68881.
1357: @item sun3-nfp-os4
1358: Sun 3 running system version 4, without 68881.
1.1.1.4 root 1359: @item sun4-os4
1360: Sun 4 running system version 4.
1361: @item sun386
1362: Sun 386 (``roadrunner'').
1.1.1.5 root 1363: @item alliant
1.1.1.7 ! root 1364: Alliant FX/8 computer. Currently, there are bugs in the support
! 1365: for floating point. Also note that Alliant's version of dbx does
! 1366: not manage to work with the output from GNU CC.
! 1367: @item mips
! 1368: Some variant of MIPS computer (but not the one from DEC). Note
! 1369: that this machine description was written for GNU CC version 1.32
! 1370: and may require some updating to work with the current version.
1.1.1.5 root 1371: @item convex-c1
1372: Convex C1 computer.
1373: @item convex-c2
1374: Convex C2 computer.
1.1.1.4 root 1375: @item hp9k320
1.1.1.7 ! root 1376: HP 9000 series 300 using HPUX assembler. Note there is no
! 1377: support in GNU CC for HP's debugger; thus, @samp{-g} is not
! 1378: available in this configuration.
1.1.1.6 root 1379: @item hp9k320g
1.1.1.4 root 1380: HP 9000 series 300 using GNU assembler, linker and debugger.
1.1.1.7 ! root 1381: This requires the HP-adapt package, which is available along with
! 1382: the GNU linker as part of the ``binutils'' distribution.
! 1383: This is on the GNU CC distribution tape.
1.1.1.4 root 1384: @item isi68
1385: ISI 68000 or 68020 system.
1386: @item news800
1387: Sony NEWS 68020 system.
1.1.1.6 root 1388: @item next
1389: NeXT system.
1.1.1.7 ! root 1390: @item altos
! 1391: Altos 3068. Note that you must use the GNU assembler, linker and
! 1392: debugger, with COFF-encapsulation. Also, you must fix a kernel
! 1393: bug. Details in the file @file{ALTOS-README}.
1.1.1.4 root 1394: @item 3b1
1.1.1.7 ! root 1395: AT&T 3b1, a.k.a. 7300 PC. Note that the current version of GNU
! 1396: CC cannot be compiled with the Unix compiler on this machine, due
! 1397: to bugs in the Unix comiler. GNU CC does work correctly,
! 1398: however, if you can compile it with older version of GNU CC or
! 1399: cross-compile it.
1.1.1.4 root 1400: @item sequent-ns32k
1401: Sequent containing ns32000 processors.
1402: @item encore
1403: Encore ns32000 system.
1404: @item genix
1405: National Semiconductor ns32000 system.
1406: @item 88000
1407: Motorola 88000 processor. This port is not finished.
1408: @end table
1.1.1.2 root 1409:
1.1.1.4 root 1410: Here we spell out what files need to be set up:
1.1 root 1411:
1412: @itemize @bullet
1413: @item
1414: Make a symbolic link named @file{config.h} to the top-level
1415: config file for the machine you are using (@pxref{Config}). This
1416: file is responsible for defining information about the host
1417: machine. It includes @file{tm.h}.
1418:
1.1.1.7 ! root 1419: The file is located in the subdirectory @file{config}. Its name
! 1420: should be @file{xm-@var{machine}.h}, with these exceptions:
1.1 root 1421:
1422: @table @file
1.1.1.3 root 1423: @item xm-vms.h
1.1 root 1424: for vaxen running VMS.
1.1.1.3 root 1425: @item xm-vaxv.h
1.1 root 1426: for vaxen running system V.
1.1.1.3 root 1427: @item xm-i386v.h
1.1 root 1428: for Intel 80386's running system V.
1.1.1.3 root 1429: @item xm-sunos4.h
1.1 root 1430: for Suns (model 2, 3 or 4) running @emph{operating system} version 4.
1.1.1.3 root 1431: (Use @file{xm-m68k.h} or @file{xm-sparc.h} for version 3.)
1432: @item xm-sun386i.h
1433: for Sun roadrunner running any version of the operating system.
1434: @item xm-hp9k320.h
1.1 root 1435: for the HP 9000 series 300.
1.1.1.4 root 1436: @item xm-genix.h
1.1 root 1437: for the ns32000 running Genix
1438: @end table
1439:
1440: If your system does not support symbolic links, you might want to
1441: set up @file{config.h} to contain a @samp{#include} command which
1442: refers to the appropriate file.
1443:
1444: @item
1445: Make a symbolic link named @file{tm.h} to the machine-description
1.1.1.7 ! root 1446: macro file for your machine. It should be in the subdirectory
! 1447: @file{config} and its name should be @file{tm-@var{machine}.h}.
1.1 root 1448:
1449: If your system is a 68000, don't use the file @file{tm-m68k.h}
1450: directly. Instead, use one of these files:
1451:
1452: @table @file
1453: @item tm-sun3.h
1.1.1.5 root 1454: for Sun 3 machines with 68881.
1455: @item tm-sun3-nfp.h
1456: for Sun 3 machines with no hardware floating point.
1.1 root 1457: @item tm-sun2.h
1458: for Sun 2 machines.
1459: @item tm-3b1.h
1460: for AT&T 3b1 (aka 7300 Unix PC).
1461: @item tm-isi68.h
1.1.1.3 root 1462: for Integrated Solutions systems. This file assumes you
1463: use the GNU assembler.
1.1 root 1464: @item tm-news800.h
1465: for SONY News systems.
1466: @item tm-hp9k320.h
1467: for HPUX systems, if you are using GNU CC with the system's
1468: assembler and linker.
1469: @item tm-hp9k320g.h
1470: for HPUX systems, if you are using the GNU assembler, linker and
1471: other utilities. Not all of the pieces of GNU software needed
1472: for this mode of operation are as yet in distribution; full
1473: instructions will appear here in the future.@refill
1474: @end table
1475:
1476: For the vax, use @file{tm-vax.h} on BSD Unix, @file{tm-vaxv.h} on
1477: system V, or @file{tm-vms.h} on VMS.@refill
1478:
1479: For the Motorola 88000, use @file{tm-m88k.h}. The support for the
1480: 88000 has a few unfinished spots because there was no way to run the
1.1.1.2 root 1481: output. Bugs are suspected in handling of branch-tables and in the
1482: function prologue and epilogue.
1.1 root 1483:
1484: For the 80386, don't use @file{tm-i386.h} directly. Use
1485: @file{tm-i386v.h} if the target machine is running system V,
1.1.1.5 root 1486: @file{tm-i386gas.h} if it is running system V but you are using the
1487: GNU assembler and linker, @file{tm-seq386.h} for a Sequent 386 system,
1488: or @file{tm-compaq.h} for a Compaq, or @file{tm-sun386i.h} for a Sun
1489: 386 system.
1.1 root 1490:
1491: For the 32000, use @file{tm-sequent.h} if you are using a Sequent
1492: machine, or @file{tm-encore.h} for an Encore machine, or
1.1.1.4 root 1493: @file{tm-genix.h} if you are using Genix version 3; otherwise, perhaps
1.1 root 1494: @file{tm-ns32k.h} will work for you.
1495:
1496: Note that Genix has bugs in @code{alloca} and @code{malloc}; you must
1497: get the compiled versions of these from GNU Emacs and edit GNU CC's
1498: @file{Makefile} to use them.
1499:
1500: Note that Encore systems are supported only under BSD.
1501:
1.1.1.6 root 1502: For Sparc (Sun 4) machines, use @file{tm-sparc.h} with operating system
1503: version 4, and @file{tm-sun4os3.h} with system version 3.
1504:
1.1 root 1505: @item
1506: Make a symbolic link named @file{md} to the machine description
1.1.1.7 ! root 1507: pattern file. It should be in the @file{config} subdirectory and its
! 1508: name should be @file{@var{machine}.md}; but @var{machine} is often not
! 1509: the same as the name used in the @file{tm.h} file because the
! 1510: @file{md} files are more general.
1.1 root 1511:
1512: @item
1513: Make a symbolic link named @file{aux-output.c} to the output
1.1.1.7 ! root 1514: subroutine file for your machine. It should be in the @file{config}
! 1515: subdirectory and its name should be @file{out-@var{machine}.c}.
1.1 root 1516: @end itemize
1517:
1518: @item
1519: Make sure the Bison parser generator is installed. (This is
1520: unnecessary if the Bison output files @file{c-parse.tab.c} and
1521: @file{cexp.c} are more recent than @file{c-parse.y} and @file{cexp.y}
1522: and you do not plan to change the @samp{.y} files.)
1523:
1524: Bison versions older that Sept 8, 1988 will produce incorrect output
1525: for @file{c-parse.tab.c}.
1526:
1527: @item
1528: If you are using a Sun, make sure the environment variable
1529: @code{FLOAT_OPTION} is not set. If this option were set to
1530: @code{f68881} when @file{gnulib} is compiled, the resulting code would
1531: demand to be linked with a special startup file and will not link
1532: properly without special pains.
1533:
1534: @item
1535: Build the compiler. Just type @samp{make} in the compiler directory.
1536:
1.1.1.2 root 1537: Ignore any warnings you may see about ``statement not reached'' in the
1538: @file{insn-emit.c}; they are normal. Any other compilation errors may
1539: represent bugs in the port to your machine or operating system, and
1540: should be investigated and reported (@pxref{Bugs}).
1541:
1.1 root 1542: @item
1.1.1.7 ! root 1543: Optionally, install the library functions for 64-bit integer
! 1544: arithmetic. You do this with the command @samp{make gnulib2}. In the
! 1545: future this will happen automatically; for now, it is optional, until
! 1546: we are sure it works on all machines.
! 1547:
! 1548: @item
1.1.1.5 root 1549: If you are using COFF-encapsulation, you must convert @file{gnulib} to
1550: a GNU-format library at this point. See the file @file{README-ENCAP}
1551: in the directory containing the GNU binary file utilities, for
1552: directions.
1553:
1554: @item
1.1 root 1555: Move the first-stage object files and executables into a subdirectory
1556: with this command:
1557:
1558: @example
1559: make stage1
1560: @end example
1561:
1562: The files are moved into a subdirectory named @file{stage1}.
1563: Once installation is complete, you may wish to delete these files
1564: with @code{rm -r stage1}.
1565:
1566: @item
1567: Recompile the compiler with itself, with this command:
1568:
1569: @example
1570: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/"
1571: @end example
1572:
1573: On a 68000 or 68020 system lacking floating point hardware,
1574: unless you have selected a @file{tm.h} file that expects by default
1575: that there is no such hardware, do this instead:
1576:
1577: @example
1578: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -msoft-float"
1579: @end example
1580:
1581: @item
1582: If you wish to test the compiler by compiling it with itself one more
1.1.1.7 ! root 1583: time, do this (in C shell):
1.1 root 1584:
1585: @example
1586: make stage2
1587: make CC=stage2/gcc CFLAGS="-g -O -Bstage2/"
1588: foreach file (*.o)
1589: cmp $file stage2/$file
1590: end
1591: @end example
1592:
1.1.1.7 ! root 1593: @noindent
1.1 root 1594: Aside from the @samp{-B} option, the options should be the same as
1595: when you made stage 2.
1596:
1.1.1.7 ! root 1597: The @code{foreach} command (written in C shell) will notify you if any of
! 1598: these stage 3 object files differs from those of stage 2. On BSD systems,
! 1599: any difference, no matter how innocuous, indicates that the stage 2
! 1600: compiler has compiled GNU CC incorrectly, and is therefore a potentially
! 1601: serious bug which you should investigate and report (@pxref{Bugs}).
! 1602:
! 1603: On systems that use COFF object files, bytes 5 to 8 will always be
! 1604: different, since it is a timestamp. On these systems, you can do the
! 1605: comparison as follows (in Bourne shell):
! 1606:
! 1607: @example
! 1608: for file in *.o; do
! 1609: echo $file
! 1610: tail +10 $file > foo1
! 1611: tail +10 stage2/$file > foo2
! 1612: cmp foo1 foo2
! 1613: done
! 1614: @end example
! 1615:
1.1 root 1616: @item
1617: Install the compiler driver, the compiler's passes and run-time support.
1618: You can use the following command:
1619:
1620: @example
1621: make install
1622: @end example
1623:
1624: @noindent
1625: This copies the files @file{cc1}, @file{cpp} and @file{gnulib} to
1626: files @file{gcc-cc1}, @file{gcc-cpp} and @file{gcc-gnulib} in
1627: directory @file{/usr/local/lib}, which is where the compiler driver
1628: program looks for them. It also copies the driver program @file{gcc}
1.1.1.6 root 1629: into the directory @file{/usr/local/bin}, so that it appears in typical
1.1 root 1630: execution search paths.@refill
1631:
1632: @strong{Warning: there is a bug in @code{alloca} in the Sun library.
1633: To avoid this bug, install the binaries of GNU CC that were compiled
1634: by GNU CC. They use @code{alloca} as a built-in function and never
1635: the one in the library.}
1636:
1637: @strong{Warning: the GNU CPP may not work for @file{ioctl.h},
1638: @file{ttychars.h} and other system header files unless the
1639: @samp{-traditional} option is used.} The bug is in the header files:
1640: at least on some machines, they rely on behavior that is incompatible
1641: with ANSI C. This behavior consists of substituting for macro
1642: argument names when they appear inside of character constants. The
1643: @samp{-traditional} option tells GNU CC to behave the way these
1644: headers expect.
1645:
1646: Because of this problem, you might prefer to configure GNU CC to use
1647: the system's own C preprocessor. To do so, make the file
1648: @file{/usr/local/lib/gcc-cpp} a link to @file{/lib/cpp}.
1649:
1650: Alternatively, on Sun systems and 4.3BSD at least, you can correct the
1651: include files by running the shell script @file{fixincludes}. This
1652: installs modified, corrected copies of the files @file{ioctl.h},
1653: @file{ttychars.h} and many others, in a special directory where only
1.1.1.2 root 1654: GNU CC will normally look for them. This script will work on various
1.1.1.6 root 1655: systems because it chooses the files by searching all the system
1.1.1.2 root 1656: headers for the problem cases that we know about.
1.1 root 1657: @end enumerate
1658:
1659: If you cannot install the compiler's passes and run-time support in
1660: @file{/usr/local/lib}, you can alternatively use the @samp{-B} option to
1661: specify a prefix by which they may be found. The compiler concatenates
1662: the prefix with the names @file{cpp}, @file{cc1} and @file{gnulib}.
1663: Thus, you can put the files in a directory @file{/usr/foo/gcc} and
1664: specify @samp{-B/usr/foo/gcc/} when you run GNU CC.
1665:
1666: Also, you can specify an alternative default directory for these files
1667: by setting the Make variable @code{libdir} when you make GNU CC.
1668:
1669: @node VMS Install,, Installation, Installation
1670: @section Installing GNU CC on VMS
1671:
1.1.1.4 root 1672: The VMS version of GNU CC is distributed in a backup saveset containing
1673: both source code and precompiled binaries.
1674:
1675: Sometimes the binaries will be from an older version that the sources,
1676: because we don't always have time to update them. In this case, you
1677: should use the binaries you get to recompile the sources. If you must
1.1 root 1678: recompile, here is how:
1679:
1680: @enumerate
1681: @item
1.1.1.3 root 1682: Copy the file @file{tm-vms.h} to @file{tm.h}, @file{xm-vms.h} to
1.1 root 1683: @file{config.h}, @file{vax.md} to @file{md.} and @file{output-vax.c}
1684: to @file{aux-output.c}.@refill
1685:
1686: @item
1687: Type @samp{@@make} to do recompile everything.
1.1.1.5 root 1688:
1689: If you are compiling with a version of GCC older than 1.33, specify
1690: @samp{/DEFINE=("inline=")} as an option in all the compilations. This
1691: requires editing all the @code{gcc} commands in @file{make-cc1.com}.
1692: (The older versions had problems supporting @code{inline}.) Once you
1693: have a working 1.33 or newer GCC, you can change this file back.
1.1 root 1694: @end enumerate
1695:
1696: To install the @samp{GCC} command so you can use the compiler easily, in
1697: the same manner as you use the VMS C compiler, you must install the VMS CLD
1698: file for GNU CC as follows:
1699:
1700: @enumerate
1701: @item
1702: Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE}
1703: to point to the directories where the GNU CC executables
1704: (@samp{gcc-cpp}, @samp{gcc-cc1}, etc.) and the C include files are
1705: kept. This should be done with the commands:@refill
1706:
1707: @example
1708: $ assign /super /system disk:[gcc] gnu_cc
1709: $ assign /super /system disk:[gcc.include] gnu_cc_include
1710: @end example
1711:
1712: @noindent
1713: with the appropriate disk and directory names. These commands can be
1714: placed in your system startup file so they will be executed whenever
1715: the machine is rebooted.
1716:
1717: @item
1718: Install the @samp{GCC} command with the command line:
1719:
1720: @example
1721: $ set command /table=sys$library:dcltables gnu_cc:gcc
1722: @end example
1723:
1.1.1.7 ! root 1724: @item
! 1725: To install the help file, do the following:
! 1726:
! 1727: @example
! 1728: $ lib/help sys$library:helplib.hlb gcc.hlp
! 1729: @end example
! 1730:
1.1 root 1731: @noindent
1732: Now you can invoke the compiler with a command like @samp{gcc /verbose
1733: file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in
1734: Unix.
1735: @end enumerate
1736:
1.1.1.5 root 1737: There is a known problem on VMS: @code{const} global variables don't
1738: work compatibly with the VMS C compiler; we don't know a way to get
1739: them to the linker properly.
1740:
1.1.1.7 ! root 1741: Note that GNU CC on VMS does not generate debugging information to
! 1742: describe the program's symbols. It is not straightforward to implement
! 1743: this, and we have no time to spend on it, but we might consent to
! 1744: install a very modular implementation if you write it. You will
! 1745: probably have to modify GAS as well as GNU CC.
! 1746:
1.1 root 1747: @node Trouble, Incompatibilities, Installation, Top
1748: @chapter Known Causes of Trouble with GNU CC.
1749:
1750: Here are some of the things that have caused trouble for people installing
1751: or using GNU CC.
1752:
1753: @itemize @bullet
1754: @item
1755: On certain systems, defining certain environment variables such as
1756: @samp{CC} can interfere with the functioning of @code{make}.
1757:
1758: @item
1759: Cross compilation can run into trouble for certain machines because
1760: some target machines' assemblers require floating point numbers to be
1761: written as @emph{integer} constants in certain contexts.
1762:
1763: The compiler writes these integer constants by examining the floating
1764: point value as an integer and printing that integer, because this is
1765: simple to write and independent of the details of the floating point
1766: representation. But this does not work if the compiler is running on
1767: a different machine with an incompatible floating point format, or
1768: even a different byte-ordering.
1769:
1.1.1.5 root 1770: In addition, correct constant folding of floating point values
1771: requires representing them in the target machine's format.
1772: (The C standard does not quite require this, but in practice
1773: it is the only way to win.)
1774:
1775: It is now possible to overcome these problems by defining macros such
1776: as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
1777: work for each target machine. @xref{Cross-compilation}.
1.1 root 1778:
1779: @item
1780: DBX rejects some files produced by GNU CC, though it accepts similar
1781: constructs in output from PCC. Until someone can supply a coherent
1782: description of what is valid DBX input and what is not, there is
1783: nothing I can do about these problems. You are on your own.
1.1.1.2 root 1784:
1785: @item
1786: Users often think it is a bug when GNU CC reports an error for code
1787: like this:
1788:
1789: @example
1790: int foo (short);
1791:
1792: int foo (x)
1793: short x;
1794: @{@dots{}@}
1795: @end example
1796:
1.1.1.4 root 1797: The error message is correct: this code really is erroneous, because the
1798: old-style non-prototype definition passes subword integers in their
1799: promoted types. In other words, the argument is really an @code{int},
1800: not a @code{short}. The correct prototype is this:
1.1.1.2 root 1801:
1802: @example
1803: int foo (int);
1804: @end example
1805:
1806: @item
1807: Users often think it is a bug when GNU CC reports an error for code
1808: like this:
1809:
1810: @example
1811: int foo (struct mumble *);
1812:
1813: struct mumble @{ @dots{} @};
1814:
1815: int foo (struct mumble *x)
1816: @{ @dots{} @}
1817: @end example
1818:
1819: This code really is erroneous, because the scope of @code{struct
1820: mumble} the prototype is limited to the argument list containing it.
1821: It does not refer to the @code{struct mumble} defined with file scope
1822: immediately below---they are two unrelated types with similar names in
1823: different scopes.
1824:
1825: But in the definition of @code{foo}, the file-scope type is used
1826: because that is available to be inherited. Thus, the definition and
1827: the prototype do not match, and you get an error.
1828:
1829: This behavior may seem silly, but it's what the ANSI standard
1830: specifies. It is easy enough for you to make your code work by moving
1831: the definition of @code{struct mumble} above the prototype. I don't
1832: think it's worth being incompatible for.
1.1 root 1833: @end itemize
1834:
1835: @node Incompatibilities, Extensions, Trouble, Top
1836: @chapter Incompatibilities of GNU CC
1837:
1838: There are several noteworthy incompatibilities between GNU C and most
1839: existing (non-ANSI) versions of C.
1840:
1841: Ultimately our intention is that the @samp{-traditional} option will
1842: eliminate most of these incompatibilities by telling GNU C to behave
1843: like the other C compilers.
1844:
1845: @itemize @bullet
1846: @item
1847: GNU CC normally makes string constants read-only. If several
1848: identical-looking string constants are used, GNU CC stores only one
1849: copy of the string.
1850:
1851: One consequence is that you cannot call @code{mktemp} with a string
1852: constant argument. The function @code{mktemp} always alters the
1853: string its argument points to.
1854:
1855: Another consequence is that @code{sscanf} does not work on some
1856: systems when passed a string constant as its format control string.
1857: This is because @code{sscanf} incorrectly tries to write into the
1.1.1.4 root 1858: string constant. Likewise @code{fscanf} and @code{scanf}.
1.1 root 1859:
1860: The best solution to these problems is to change the program to use
1861: @code{char}-array variables with initialization strings for these
1862: purposes instead of string constants. But if this is not possible,
1863: you can use the @samp{-fwritable-strings} flag, which directs GNU CC
1864: to handle string constants the same way most C compilers do.
1865:
1866: @item
1867: GNU CC does not substitute macro arguments when they appear inside of
1868: string constants. For example, the following macro in GNU CC
1869:
1870: @example
1871: #define foo(a) "a"
1872: @end example
1873:
1874: @noindent
1875: will produce output @samp{"a"} regardless of what the argument @var{a} is.
1876:
1877: The @samp{-traditional} option directs GNU CC to handle such cases
1878: (among others) in the old-fashioned (non-ANSI) fashion.
1879:
1880: @item
1881: When you use @code{setjmp} and @code{longjmp}, the only automatic
1882: variables guaranteed to remain valid are those declared
1883: @code{volatile}. This is a consequence of automatic register
1884: allocation. Consider this function:
1885:
1886: @example
1887: jmp_buf j;
1888:
1889: foo ()
1890: @{
1891: int a, b;
1892:
1893: a = fun1 ();
1894: if (setjmp (j))
1895: return a;
1896:
1897: a = fun2 ();
1898: /* @r{@code{longjmp (j)} may be occur in @code{fun3}.} */
1899: return a + fun3 ();
1900: @}
1901: @end example
1902:
1903: Here @code{a} may or may not be restored to its first value when the
1904: @code{longjmp} occurs. If @code{a} is allocated in a register, then
1905: its first value is restored; otherwise, it keeps the last value stored
1906: in it.
1907:
1908: If you use the @samp{-W} option with the @samp{-O} option, you will
1909: get a warning when GNU CC thinks such a problem might be possible.
1910:
1.1.1.2 root 1911: The @samp{-traditional} option directs GNU C to put variables in
1912: the stack by default, rather than in registers, in functions that
1913: call @code{setjmp}. This results in the behavior found in
1914: traditional C compilers.
1915:
1.1 root 1916: @item
1917: Declarations of external variables and functions within a block apply
1918: only to the block containing the declaration. In other words, they
1919: have the same scope as any other declaration in the same place.
1920:
1921: In some other C compilers, a @code{extern} declaration affects all the
1922: rest of the file even if it happens within a block.
1923:
1924: The @samp{-traditional} option directs GNU C to treat all @code{extern}
1925: declarations as global, like traditional compilers.
1926:
1927: @item
1928: In traditional C, you can combine @code{long}, etc., with a typedef name,
1929: as shown here:
1930:
1931: @example
1932: typedef int foo;
1933: typedef long foo bar;
1934: @end example
1935:
1936: In ANSI C, this is not allowed: @code{long} and other type modifiers
1937: require an explicit @code{int}. Because this criterion is expressed
1938: by Bison grammar rules rather than C code, the @samp{-traditional}
1939: flag cannot alter it.
1940:
1941: @item
1942: PCC allows typedef names to be used as function parameters. The
1943: difficulty described immediately above applies here too.
1944:
1945: @item
1946: PCC allows whitespace in the middle of compound assignment operators
1947: such as @samp{+=}. GNU CC, following the ANSI standard, does not
1948: allow this. The difficulty described immediately above applies here
1949: too.
1950:
1951: @item
1952: GNU CC will flag unterminated character constants inside of preprocessor
1953: conditionals that fail. Some programs have English comments enclosed in
1954: conditionals that are guaranteed to fail; if these comments contain
1955: apostrophes, GNU CC will probably report an error. For example,
1956: this code would produce an error:
1957:
1958: @example
1959: #if 0
1960: You can't expect this to work.
1961: #endif
1962: @end example
1963:
1964: The best solution to such a problem is to put the text into an actual
1965: C comment delimited by @samp{/*@dots{}*/}. However,
1966: @samp{-traditional} suppresses these error messages.
1967:
1968: @item
1969: When compiling functions that return @code{float}, PCC converts it to
1970: a double. GNU CC actually returns a @code{float}. If you are concerned
1971: with PCC compatibility, you should declare your functions to return
1972: @code{double}; you might as well say what you mean.
1973:
1974: @item
1975: When compiling functions that return structures or unions, GNU CC
1.1.1.6 root 1976: output code normally uses a method different from that used on most
1977: versions of Unix. As a result, code compiled with GNU CC cannot call
1978: a structure-returning function compiled with PCC, and vice versa.
1.1 root 1979:
1.1.1.6 root 1980: The method used by GNU CC is as follows: a structure or union which is 1,
1.1 root 1981: 2, 4 or 8 bytes long is returned like a scalar. A structure or union
1982: with any other size is stored into an address supplied by the caller
1983: in a special, fixed register.
1984:
1985: PCC usually handles all sizes of structures and unions by returning
1986: the address of a block of static storage containing the value. This
1.1.1.6 root 1987: method is not used in GNU CC because it is slower and nonreentrant.
1.1.1.5 root 1988:
1.1.1.6 root 1989: You can tell GNU CC to use the PCC convention with the option
1990: @samp{-fpcc-struct-return}.
1.1 root 1991: @end itemize
1992:
1993: @node Extensions, Bugs, Incompatibilities, Top
1994: @chapter GNU Extensions to the C Language
1995:
1996: GNU C provides several language features not found in ANSI standard C.
1997: (The @samp{-pedantic} option directs GNU CC to print a warning message if
1998: any of these features is used.) To test for the availability of these
1999: features in conditional compilation, check for a predefined macro
2000: @code{__GNUC__}, which is always defined under GNU CC.
2001:
2002: @menu
2003: * Statement Exprs:: Putting statements and declarations inside expressions.
2004: * Naming Types:: Giving a name to the type of some expression.
2005: * Typeof:: @code{typeof}: referring to the type of an expression.
2006: * Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues.
2007: * Conditionals:: Omitting the middle operand of a @samp{?:} expression.
2008: * Zero-Length:: Zero-length arrays.
2009: * Variable-Length:: Arrays whose length is computed at run time.
2010: * Subscripting:: Any array can be subscripted, even if not an lvalue.
2011: * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
1.1.1.5 root 2012: * Initializers:: Non-constant initializers.
1.1 root 2013: * Constructors:: Constructor expressions give structures, unions
2014: or arrays as values.
1.1.1.5 root 2015: * Function Attributes:: Declaring that functions have no side effects,
2016: or that they can never return.
1.1 root 2017: * Dollar Signs:: Dollar sign is allowed in identifiers.
2018: * Alignment:: Inquiring about the alignment of a type or variable.
2019: * Inline:: Defining inline functions (as fast as macros).
2020: * Extended Asm:: Assembler instructions with C expressions as operands.
2021: (With them you can define ``built-in'' functions.)
2022: * Asm Labels:: Specifying the assembler name to use for a C symbol.
1.1.1.5 root 2023: * Global Reg Vars:: Defining global variables which reside in registers.
1.1.1.7 ! root 2024: * Alternate Keywords:: @code{__const}, @code{__asm}, etc., for header files.
1.1 root 2025: @end menu
2026:
2027: @node Statement Exprs, Naming Types, Extensions, Extensions
2028: @section Statements and Declarations inside of Expressions
2029:
2030: A compound statement in parentheses may appear inside an expression in GNU
2031: C. This allows you to declare variables within an expression. For
2032: example:
2033:
2034: @example
2035: (@{ int y = foo (); int z;
2036: if (y > 0) z = y;
2037: else z = - y;
2038: z; @})
2039: @end example
2040:
2041: @noindent
2042: is a valid (though slightly more complex than necessary) expression
2043: for the absolute value of @code{foo ()}.
2044:
2045: This feature is especially useful in making macro definitions ``safe'' (so
2046: that they evaluate each operand exactly once). For example, the
2047: ``maximum'' function is commonly defined as a macro in standard C as
2048: follows:
2049:
2050: @example
2051: #define max(a,b) ((a) > (b) ? (a) : (b))
2052: @end example
2053:
2054: @noindent
2055: But this definition computes either @var{a} or @var{b} twice, with bad
2056: results if the operand has side effects. In GNU C, if you know the
2057: type of the operands (here let's assume @code{int}), you can define
2058: the macro safely as follows:
2059:
2060: @example
2061: #define maxint(a,b) \
2062: (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
2063: @end example
2064:
2065: Embedded statements are not allowed in constant expressions, such as
2066: the value of an enumeration constant, the width of a bit field, or
2067: the initial value of a static variable.
2068:
2069: If you don't know the type of the operand, you can still do this, but you
2070: must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming
2071: Types}).
2072:
2073: @node Naming Types, Typeof, Statement Exprs, Extensions
2074: @section Naming an Expression's Type
2075:
2076: You can give a name to the type of an expression using a @code{typedef}
2077: declaration with an initializer. Here is how to define @var{name} as a
2078: type name for the type of @var{exp}:
2079:
2080: @example
2081: typedef @var{name} = @var{exp};
2082: @end example
2083:
2084: This is useful in conjunction with the statements-within-expressions
2085: feature. Here is how the two together can be used to define a safe
2086: ``maximum'' macro that operates on any arithmetic type:
2087:
2088: @example
2089: #define max(a,b) \
2090: (@{typedef _ta = (a), _tb = (b); \
2091: _ta _a = (a); _tb _b = (b); \
2092: _a > _b ? _a : _b; @})
2093: @end example
2094:
2095: The reason for using names that start with underscores for the local
2096: variables is to avoid conflicts with variable names that occur within the
2097: expressions that are substituted for @code{a} and @code{b}. Eventually we
2098: hope to design a new form of declaration syntax that allows you to declare
2099: variables whose scopes start only after their initializers; this will be a
2100: more reliable way to prevent such conflicts.
2101:
2102: @node Typeof, Lvalues, Naming Types, Extensions
2103: @section Referring to a Type with @code{typeof}
2104:
2105: Another way to refer to the type of an expression is with @code{typeof}.
2106: The syntax of using of this keyword looks like @code{sizeof}, but the
2107: construct acts semantically like a type name defined with @code{typedef}.
2108:
2109: There are two ways of writing the argument to @code{typeof}: with an
2110: expression or with a type. Here is an example with an expression:
2111:
2112: @example
2113: typeof (x[0](1))
2114: @end example
2115:
2116: @noindent
2117: This assumes that @code{x} is an array of functions; the type described
2118: is that of the values of the functions.
2119:
2120: Here is an example with a typename as the argument:
2121:
2122: @example
2123: typeof (int *)
2124: @end example
2125:
2126: @noindent
2127: Here the type described is that of pointers to @code{int}.
2128:
1.1.1.7 ! root 2129: If you are writing a header file that must work when included in ANSI C
! 2130: programs, write @code{__typedef} instead of @code{typedef}.
! 2131: @xref{Alternate Keywords}.
! 2132:
1.1 root 2133: A @code{typeof}-construct can be used anywhere a typedef name could be
2134: used. For example, you can use it in a declaration, in a cast, or inside
2135: of @code{sizeof} or @code{typeof}.
2136:
2137: @itemize @bullet
2138: @item
2139: This declares @code{y} with the type of what @code{x} points to.
2140:
2141: @example
2142: typeof (*x) y;
2143: @end example
2144:
2145: @item
2146: This declares @code{y} as an array of such values.
2147:
2148: @example
2149: typeof (*x) y[4];
2150: @end example
2151:
2152: @item
2153: This declares @code{y} as an array of pointers to characters:
2154:
2155: @example
2156: typeof (typeof (char *)[4]) y;
2157: @end example
2158:
2159: @noindent
2160: It is equivalent to the following traditional C declaration:
2161:
2162: @example
2163: char *y[4];
2164: @end example
2165:
2166: To see the meaning of the declaration using @code{typeof}, and why it
2167: might be a useful way to write, let's rewrite it with these macros:
2168:
2169: @example
2170: #define pointer(T) typeof(T *)
2171: #define array(T, N) typeof(T [N])
2172: @end example
2173:
2174: @noindent
2175: Now the declaration can be rewritten this way:
2176:
2177: @example
2178: array (pointer (char), 4) y;
2179: @end example
2180:
2181: @noindent
2182: Thus, @samp{array (pointer (char), 4)} is the type of arrays of 4
2183: pointers to @code{char}.
2184: @end itemize
2185:
2186: @node Lvalues, Conditionals, Typeof, Extensions
2187: @section Generalized Lvalues
2188:
2189: Compound expressions, conditional expressions and casts are allowed as
2190: lvalues provided their operands are lvalues. This means that you can take
2191: their addresses or store values into them.
2192:
2193: For example, a compound expression can be assigned, provided the last
2194: expression in the sequence is an lvalue. These two expressions are
2195: equivalent:
2196:
2197: @example
2198: (a, b) += 5
2199: a, (b += 5)
2200: @end example
2201:
2202: Similarly, the address of the compound expression can be taken. These two
2203: expressions are equivalent:
2204:
2205: @example
2206: &(a, b)
2207: a, &b
2208: @end example
2209:
2210: A conditional expression is a valid lvalue if its type is not void and the
2211: true and false branches are both valid lvalues. For example, these two
2212: expressions are equivalent:
2213:
2214: @example
2215: (a ? b : c) = 5
2216: (a ? b = 5 : (c = 5))
2217: @end example
2218:
2219: A cast is a valid lvalue if its operand is valid. Taking the address of
2220: the cast is the same as taking the address without a cast, except for the
2221: type of the result. For example, these two expressions are equivalent (but
2222: the second may be valid when the type of @samp{a} does not permit a cast to
2223: @samp{int *}).
2224:
2225: @example
2226: &(int *)a
2227: (int **)&a
2228: @end example
2229:
2230: A simple assignment whose left-hand side is a cast works by converting the
2231: right-hand side first to the specified type, then to the type of the inner
2232: left-hand side expression. After this is stored, the value is converter
2233: back to the specified type to become the value of the assignment. Thus, if
2234: @samp{a} has type @samp{char *}, the following two expressions are
2235: equivalent:
2236:
2237: @example
2238: (int)a = 5
2239: (int)(a = (char *)5)
2240: @end example
2241:
2242: An assignment-with-arithmetic operation such as @samp{+=} applied to a cast
2243: performs the arithmetic using the type resulting from the cast, and then
2244: continues as in the previous case. Therefore, these two expressions are
2245: equivalent:
2246:
2247: @example
2248: (int)a += 5
2249: (int)(a = (char *) ((int)a + 5))
2250: @end example
2251:
2252: @node Conditionals, Zero-Length, Lvalues, Extensions
2253: @section Conditional Expressions with Omitted Middle-Operands
2254:
2255: The middle operand in a conditional expression may be omitted. Then
2256: if the first operand is nonzero, its value is the value of the conditional
2257: expression.
2258:
2259: Therefore, the expression
2260:
2261: @example
2262: x ? : y
2263: @end example
2264:
2265: @noindent
2266: has the value of @code{x} if that is nonzero; otherwise, the value of
2267: @code{y}.
2268:
2269: This example is perfectly equivalent to
2270:
2271: @example
2272: x ? x : y
2273: @end example
2274:
2275: @noindent
2276: In this simple case, the ability to omit the middle operand is not
2277: especially useful. When it becomes useful is when the first operand does,
2278: or may (if it is a macro argument), contain a side effect. Then repeating
2279: the operand in the middle would perform the side effect twice. Omitting
2280: the middle operand uses the value already computed without the undesirable
2281: effects of recomputing it.
2282:
2283: @node Zero-Length, Variable-Length, Conditionals, Extensions
2284: @section Arrays of Length Zero
2285:
2286: Zero-length arrays are allowed in GNU C. They are very useful as the last
2287: element of a structure which is really a header for a variable-length
2288: object:
2289:
2290: @example
2291: struct line @{
2292: int length;
2293: char contents[0];
2294: @};
2295:
2296: @{
2297: struct line *thisline
2298: = (struct line *) malloc (sizeof (struct line) + this_length);
2299: thisline->length = this_length;
2300: @}
2301: @end example
2302:
2303: In standard C, you would have to give @code{contents} a length of 1, which
2304: means either you waste space or complicate the argument to @code{malloc}.
2305:
2306: @node Variable-Length, Subscripting, Zero-Length, Extensions
2307: @section Arrays of Variable Length
2308:
2309: Variable-length automatic arrays are allowed in GNU C. These arrays are
2310: declared like any other automatic arrays, but with a length that is not a
2311: constant expression. The storage is allocated at that time and
2312: deallocated when the brace-level is exited. For example:
2313:
2314: @example
2315: FILE *concat_fopen (char *s1, char *s2, char *mode)
2316: @{
2317: char str[strlen (s1) + strlen (s2) + 1];
2318: strcpy (str, s1);
2319: strcat (str, s2);
2320: return fopen (str, mode);
2321: @}
2322: @end example
2323:
1.1.1.7 ! root 2324: You can also use variable-length arrays as arguments to functions:
1.1 root 2325:
2326: @example
2327: struct entry
1.1.1.7 ! root 2328: tester (int len, char data[len])
1.1 root 2329: @{
1.1.1.7 ! root 2330: @dots{}
1.1 root 2331: @}
2332: @end example
2333:
2334: The length of an array is computed on entry to the brace-level where the
2335: array is declared and is remembered for the scope of the array in case you
2336: access it with @code{sizeof}.
2337:
2338: Jumping or breaking out of the scope of the array name will also deallocate
2339: the storage. Jumping into the scope is not allowed; you will get an error
2340: message for it.
2341:
2342: You can use the function @code{alloca} to get an effect much like
2343: variable-length arrays. The function @code{alloca} is available in
2344: many other C implementations (but not in all). On the other hand,
2345: variable-length arrays are more elegant.
2346:
2347: There are other differences between these two methods. Space allocated
2348: with @code{alloca} exists until the containing @emph{function} returns.
2349: The space for a variable-length array is deallocated as soon as the array
2350: name's scope ends. (If you use both variable-length arrays and
2351: @code{alloca} in the same function, deallocation of a variable-length array
2352: will also deallocate anything more recently allocated with @code{alloca}.)
2353:
2354: @node Subscripting, Pointer Arith, Variable-Length, Extensions
2355: @section Non-Lvalue Arrays May Have Subscripts
2356:
2357: Subscripting is allowed on arrays that are not lvalues, even though the
2358: unary @samp{&} operator is not. For example, this is valid in GNU C though
2359: not valid in other C dialects:
2360:
2361: @example
2362: struct foo @{int a[4];@};
2363:
2364: struct foo f();
2365:
2366: bar (int index)
2367: @{
2368: return f().a[index];
2369: @}
2370: @end example
2371:
2372: @node Pointer Arith, Initializers, Subscripting, Extensions
2373: @section Arithmetic on @code{void}-Pointers and Function Pointers
2374:
2375: In GNU C, addition and subtraction operations are supported on pointers to
2376: @code{void} and on pointers to functions. This is done by treating the
2377: size of a @code{void} or of a function as 1.
2378:
2379: A consequence of this is that @code{sizeof} is also allowed on @code{void}
2380: and on function types, and returns 1.
2381:
2382: @node Initializers, Constructors, Pointer Arith, Extensions
2383: @section Non-Constant Initializers
2384:
2385: The elements of an aggregate initializer are not required to be constant
2386: expressions in GNU C. Here is an example of an initializer with run-time
2387: varying elements:
2388:
2389: @example
2390: foo (float f, float g)
2391: @{
2392: float beat_freqs[2] = @{ f-g, f+g @};
2393: @dots{}
2394: @}
2395: @end example
2396:
1.1.1.5 root 2397: @node Constructors, Function Attributes, Initializers, Extensions
1.1 root 2398: @section Constructor Expressions
2399:
2400: GNU C supports constructor expressions. A constructor looks like a cast
2401: containing an initializer. Its value is an object of the type specified in
2402: the cast, containing the elements specified in the initializer. The type
2403: must be a structure, union or array type.
2404:
2405: Assume that @code{struct foo} and @code{structure} are declared as shown:
2406:
2407: @example
2408: struct foo @{int a; char b[2];@} structure;
2409: @end example
2410:
2411: @noindent
2412: Here is an example of constructing a @samp{struct foo} with a constructor:
2413:
2414: @example
2415: structure = ((struct foo) @{x + y, 'a', 0@});
2416: @end example
2417:
2418: @noindent
2419: This is equivalent to writing the following:
2420:
2421: @example
2422: @{
2423: struct foo temp = @{x + y, 'a', 0@};
2424: structure = temp;
2425: @}
2426: @end example
2427:
2428: You can also construct an array. If all the elements of the constructor
2429: are (made up of) simple constant expressions, suitable for use in
2430: initializers, then the constructor is an lvalue and can be coerced to a
2431: pointer to its first element, as shown here:
2432:
2433: @example
2434: char **foo = (char *[]) @{ "x", "y", "z" @};
2435: @end example
2436:
2437: Array constructors whose elements are not simple constants are not very
2438: useful, because the constructor is not an lvalue. There are only two valid
2439: ways to use it: to subscript it, or initialize an array variable with it.
2440: The former is probably slower than a @code{switch} statement, while the
2441: latter does the same thing an ordinary C initializer would do.
2442:
2443: @example
2444: output = ((int[]) @{ 2, x, 28 @}) [input];
2445: @end example
2446:
1.1.1.5 root 2447: @node Function Attributes, Dollar Signs, Constructors
2448: @section Declaring Attributes of Functions
2449:
2450: In GNU C, you declare certain things about functions called in your program
2451: which help the compiler optimize function calls.
2452:
2453: A few functions, such as @code{abort} and @code{exit}, cannot return.
2454: These functions should be declared @code{volatile}. For example,
2455:
2456: @example
2457: extern volatile void abort ();
2458: @end example
2459:
2460: @noindent
2461: tells the compiler that it can assume that @code{abort} will not return.
2462: This makes slightly better code, but more importantly it helps avoid
2463: spurious warnings of uninitialized variables.
2464:
2465: Many functions do not examine any values except their arguments, and
2466: have no effects except the return value. Such a function can be subject
2467: to common subexpression elimination and loop optimization just as an
2468: arithmetic operator would be. These functions should be declared
2469: @code{const}. For example,
2470:
2471: @example
2472: extern const void square ();
2473: @end example
2474:
2475: @noindent
2476: says that the hypothetical function @code{square} is safe to call
2477: fewer times than the program says.
2478:
2479: Note that a function that has pointer arguments and examines the data
2480: pointed to must @emph{not} be declared @code{const}. Likewise, a
2481: function that calls a non-@code{const} function must not be
2482: @code{const}.
2483:
2484: Some people object to this feature, claiming that ANSI C's @code{#pragma}
2485: should be used instead. There are two reasons I did not do this.
2486:
2487: @enumerate
2488: @item
2489: It is impossible to generate @code{#pragma} commands from a macro.
2490:
2491: @item
2492: The @code{#pragma} command is just as likely as these keywords to mean
2493: something else in another compiler.
2494: @end enumerate
2495:
2496: These two reasons apply to @emph{any} application whatever: as far as
2497: I can see, @code{#pragma} is never useful.
2498:
2499: @node Dollar Signs, Alignment, Function Attributes, Extensions
1.1 root 2500: @section Dollar Signs in Identifier Names
2501:
2502: In GNU C, you may use dollar signs in identifier names. This is because
2503: many traditional C implementations allow such identifiers.
2504:
2505: @node Alignment, Inline, Dollar Signs, Extensions
2506: @section Inquiring about the Alignment of a Type or Variable
2507:
2508: The keyword @code{__alignof} allows you to inquire about how an object
2509: is aligned, or the minimum alignment usually required by a type. Its
2510: syntax is just like @code{sizeof}.
2511:
2512: For example, if the target machine requires a @code{double} value to be
2513: aligned on an 8-byte boundary, then @code{__alignof (double)} is 8. This
2514: is true on many RISC machines. On more traditional machine designs,
2515: @code{__alignof (double)} is 4 or even 2.
2516:
2517: Some machines never actually require alignment; they allow reference to any
2518: data type even at an odd addresses. For these machines, @code{__alignof}
2519: reports the @emph{recommended} alignment of a type.
2520:
2521: When the operand of @code{__alignof} is an lvalue rather than a type, the
2522: value is the largest alignment that the lvalue is known to have. It may
2523: have this alignment as a result of its data type, or because it is part of
2524: a structure and inherits alignment from that structure. For example, after
2525: this declaration:
2526:
2527: @example
2528: struct foo @{ int x; char y; @} foo1;
2529: @end example
2530:
2531: @noindent
2532: the value of @code{__alignof (foo1.y)} is probably 2 or 4, the same as
2533: @code{__alignof (int)}, even though the data type of @code{foo1.y} does not
2534: itself demand any alignment.@refill
2535:
2536: @node Inline, Extended Asm, Alignment, Extensions
2537: @section An Inline Function is As Fast As a Macro
2538:
2539: By declaring a function @code{inline}, you can direct GNU CC to integrate
2540: that function's code into the code for its callers. This makes execution
2541: faster by eliminating the function-call overhead; in addition, if any of
2542: the actual argument values are constant, their known values may permit
2543: simplifications at compile time so that not all of the inline function's
2544: code needs to be included.
2545:
2546: To declare a function inline, use the @code{inline} keyword in its
2547: declaration, like this:
2548:
2549: @example
2550: inline int
2551: inc (int *a)
2552: @{
2553: (*a)++;
2554: @}
2555: @end example
2556:
1.1.1.7 ! root 2557: (If you are writing a header file to be included in ANSI C programs, write
! 2558: @code{__inline} instead of @code{inline}. @xref{Alternate Keywords}.)
! 2559:
! 2560: You can also make all ``simple enough'' functions inline with the option
! 2561: @samp{-finline-functions}. Note that certain usages in a function
! 2562: definition can make it unsuitable for inline substitution.
1.1 root 2563:
2564: When a function is both inline and @code{static}, if all calls to the
2565: function are integrated into the caller, then the function's own assembler
2566: code is never referenced. In this case, GNU CC does not actually output
2567: assembler code for the function, unless you specify the option
2568: @samp{-fkeep-inline-functions}. Some calls cannot be integrated for
2569: various reasons (in particular, calls that precede the function's
2570: definition cannot be integrated, and neither can recursive calls within the
2571: definition). If there is a nonintegrated call, then the function is
2572: compiled to assembler code as usual.
2573:
2574: When an inline function is not @code{static}, then the compiler must assume
2575: that there may be calls from other source files; since a global symbol can
2576: be defined only once in any program, the function must not be defined in
2577: the other source files, so the calls therein cannot be integrated.
2578: Therefore, a non-@code{static} inline function is always compiled on its
2579: own in the usual fashion.
2580:
2581: @node Extended Asm, Asm Labels, Inline, Extensions
2582: @section Assembler Instructions with C Expression Operands
2583:
2584: In an assembler instruction using @code{asm}, you can now specify the
2585: operands of the instruction using C expressions. This means no more
2586: guessing which registers or memory locations will contain the data you want
2587: to use.
2588:
2589: You must specify an assembler instruction template much like what appears
2590: in a machine description, plus an operand constraint string for each
2591: operand.
2592:
2593: For example, here is how to use the 68881's @code{fsinx} instruction:
2594:
2595: @example
2596: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
2597: @end example
2598:
2599: @noindent
2600: Here @code{angle} is the C expression for the input operand while
2601: @code{result} is that of the output operand. Each has @samp{"f"} as its
2602: operand constraint, saying that a floating-point register is required. The
1.1.1.5 root 2603: @samp{=} in @samp{=f} indicates that the operand is an output; all output
1.1.1.4 root 2604: operands' constraints must use @samp{=}. The constraints use the same
2605: language used in the machine description (@pxref{Constraints}).
1.1 root 2606:
2607: Each operand is described by an operand-constraint string followed by the C
2608: expression in parentheses. A colon separates the assembler template from
2609: the first output operand, and another separates the last output operand
2610: from the first input, if any. Commas separate output operands and separate
1.1.1.4 root 2611: inputs. The total number of operands is limited to the maximum number of
1.1 root 2612: operands in any instruction pattern in the machine description.
2613:
1.1.1.4 root 2614: If there are no output operands, and there are input operands, then there
2615: must be two consecutive colons surrounding the place where the output
2616: operands would go.
2617:
1.1 root 2618: Output operand expressions must be lvalues; the compiler can check this.
2619: The input operands need not be lvalues. The compiler cannot check whether
2620: the operands have data types that are reasonable for the instruction being
2621: executed. It does not parse the assembler instruction template and does
2622: not know what it means, or whether it is valid assembler input. The
2623: extended @code{asm} feature is most often used for machine instructions
2624: that the compiler itself does not know exist.
2625:
2626: The output operands must be write-only; GNU CC will assume that the values
2627: in these operands before the instruction are dead and need not be
2628: generated. For an operand that is read-write, or in which not all bits are
2629: written and the other bits contain useful information, you must logically
2630: split its function into two separate operands, one input operand and one
2631: write-only output operand. The connection between them is expressed by
2632: constraints which say they need to be in the same location when the
2633: instruction executes. You can use the same C expression for both operands,
2634: or different expressions. For example, here we write the (fictitious)
2635: @samp{combine} instruction with @code{bar} as its read-only source operand
2636: and @code{foo} as its read-write destination:
2637:
2638: @example
2639: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
2640: @end example
2641:
2642: @noindent
2643: The constraint @samp{"0"} for operand 1 says that it must occupy the same
1.1.1.5 root 2644: location as operand 0. A digit in constraint is allowed only in an input
2645: operand, and it must refer to an output operand.
1.1 root 2646:
2647: Only a digit in the constraint can guarantee that one operand will be in
2648: the same place as another. The mere fact that @code{foo} is the value of
2649: both operands is not enough to guarantee that they will be in the same
2650: place in the generated assembler code. The following would not work:
2651:
2652: @example
2653: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
2654: @end example
2655:
2656: Various optimizations or reloading could cause operands 0 and 1 to be in
2657: different registers; GNU CC knows no reason not to do so. For example, the
2658: compiler might find a copy of the value of @code{foo} in one register and
2659: use it for operand 1, but generate the output operand 0 in a different
2660: register (copying it afterward to @code{foo}'s own address). Of course,
2661: since the register for operand 1 is not even mentioned in the assembler
2662: code, the result will not work, but GNU CC can't tell that.
2663:
2664: Unless an output operand has the @samp{&} constraint modifier, GNU CC may
2665: allocate it in the same register as an unrelated input operand, on the
2666: assumption that the inputs are consumed before the outputs are produced.
2667: This assumption may be false if the assembler code actually consists of
2668: more than one instruction. In such a case, use @samp{&} for each output
2669: operand that may not overlap an input. @xref{Modifiers}.
2670:
1.1.1.4 root 2671: Some instructions clobber specific hard registers. To describe this, write
2672: a third colon after the input operands, followed by the names of the
2673: clobbered hard registers (given as strings). Here is a realistic example
2674: for the vax:
1.1 root 2675:
2676: @example
2677: asm volatile ("movc3 %0,%1,%2"
2678: : /* no outputs */
2679: : "g" (from), "g" (to), "g" (count)
2680: : "r0", "r1", "r2", "r3", "r4", "r5");
2681: @end example
2682:
1.1.1.4 root 2683: You can put multiple assembler instructions together in a single @code{asm}
1.1.1.7 ! root 2684: template, separated either with newlines (written as @samp{\n}) or with
! 2685: semicolons if the assembler allows such semicolons. The GNU assembler
! 2686: allows semicolons and all Unix assemblers seem to do so. The input
! 2687: operands are guaranteed not to use any of the clobbered registers, and
! 2688: neither will the output operands' addresses, so you can read and write the
! 2689: clobbered registers as many times as you like. Here is an example of
! 2690: multiple instructions in a template; it assumes that the subroutine
! 2691: @code{_foo} accepts arguments in registers 9 and 10:
1.1.1.4 root 2692:
2693: @example
2694: asm ("movl %0,r9;movl %1,r10;call _foo"
2695: : /* no outputs */
2696: : "g" (from), "g" (to)
2697: : "r9", "r10");
2698: @end example
2699:
1.1.1.7 ! root 2700: If you want to test the condition code produced by an assembler instruction,
! 2701: you must include a branch and a label in the @code{asm} construct, as follows:
! 2702:
! 2703: @example
! 2704: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
! 2705: : "g" (result)
! 2706: : "g" (input));
! 2707: @end example
! 2708:
! 2709: @noindent
! 2710: This assumes your assembler supports local labels, as the GNU assembler
! 2711: and most Unix assemblers do.
! 2712:
1.1 root 2713: Usually the most convenient way to use these @code{asm} instructions is to
2714: encapsulate them in macros that look like functions. For example,
2715:
2716: @example
2717: #define sin(x) \
2718: (@{ double __value, __arg = (x); \
2719: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
2720: __value; @})
2721: @end example
2722:
2723: @noindent
2724: Here the variable @code{__arg} is used to make sure that the instruction
2725: operates on a proper @code{double} value, and to accept only those
2726: arguments @code{x} which can convert automatically to a @code{double}.
2727:
2728: Another way to make sure the instruction operates on the correct data type
2729: is to use a cast in the @code{asm}. This is different from using a
2730: variable @code{__arg} in that it converts more different types. For
2731: example, if the desired type were @code{int}, casting the argument to
2732: @code{int} would accept a pointer with no complaint, while assigning the
2733: argument to an @code{int} variable named @code{__arg} would warn about
2734: using a pointer unless the caller explicitly casts it.
2735:
1.1.1.4 root 2736: If an @code{asm} has output operands, GNU CC assumes for optimization
2737: purposes that the instruction has no side effects except to change the
2738: output operands. This does not mean that instructions with a side effect
2739: cannot be used, but you must be careful, because the compiler may eliminate
2740: them if the output operands aren't used, or move them out of loops, or
2741: replace two with one if they constitute a common subexpression. Also, if
2742: your instruction does have a side effect on a variable that otherwise
2743: appears not to change, the old value of the variable may be reused later if
2744: it happens to be found in a register.
1.1 root 2745:
2746: You can prevent an @code{asm} instruction from being deleted, moved or
2747: combined by writing the keyword @code{volatile} after the @code{asm}. For
2748: example:
2749:
2750: @example
2751: #define set_priority(x) \
2752: asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
2753: @end example
2754:
1.1.1.7 ! root 2755: @noindent
! 2756: (However, an instruction without output operands will not be deleted
! 2757: or moved, regardless, unless it is unreachable.)
1.1.1.4 root 2758:
1.1 root 2759: It is a natural idea to look for a way to give access to the condition
2760: code left by the assembler instruction. However, when we attempted to
2761: implement this, we found no way to make it work reliably. The problem
2762: is that output operands might need reloading, which would result in
2763: additional following ``store'' instructions. On most machines, these
2764: instructions would alter the condition code before there was time to
2765: test it. This problem doesn't arise for ordinary ``test'' and
2766: ``compare'' instructions because they don't have any output operands.
2767:
1.1.1.7 ! root 2768: If you are writing a header file that should be includable in ANSI C
! 2769: programs, write @code{__asm} instead of @code{asm}. @xref{Alternate
! 2770: Keywords}.
! 2771:
1.1.1.5 root 2772: @node Asm Labels, Global Reg Vars, Extended Asm, Extensions
1.1 root 2773: @section Controlling Names Used in Assembler Code
2774:
2775: You can specify the name to be used in the assembler code for a C function
1.1.1.7 ! root 2776: or variable by writing the @code{asm} (or @code{__asm}) keyword after the
! 2777: declarator as follows:
1.1 root 2778:
2779: @example
2780: int foo asm ("myfoo") = 2;
2781: @end example
2782:
2783: @noindent
2784: This specifies that the name to be used for the variable @code{foo} in
2785: the assembler code should be @samp{myfoo} rather than the usual
2786: @samp{_foo}.
2787:
2788: On systems where an underscore is normally prepended to the name of a C
2789: function or variable, this feature allows you to define names for the
2790: linker that do not start with an underscore.
2791:
2792: You cannot use @code{asm} in this way in a function @emph{definition}; but
2793: you can get the same effect by writing a declaration for the function
2794: before its definition and putting @code{asm} there, like this:
2795:
2796: @example
2797: extern func () asm ("FUNC");
2798:
2799: func (x, y)
2800: int x, y;
2801: @dots{}
2802: @end example
2803:
2804: It is up to you to make sure that the assembler names you choose do not
2805: conflict with any other assembler symbols. Also, you must not use a
2806: register name; that would produce completely invalid assembler code. GNU
2807: CC does not as yet have the ability to store static variables in registers.
2808: Perhaps that will be added.
2809:
1.1.1.7 ! root 2810: @node Global Reg Vars, Alternate Keywords, Asm Labels, Extensions
1.1.1.5 root 2811: @section Global Variables in Registers
2812:
2813: A few programs, such as programming language interpreters, may have a
2814: couple of global variables that are accessed so often that it is worth
2815: while to reserve registers throughout the program just for them.
2816:
2817: You can define a global register variable in GNU C like this:
2818:
2819: @example
2820: register int *foo asm ("a5");
2821: @end example
2822:
2823: @noindent
2824: Here @code{a5} is the name of the register which should be used. Choose a
2825: register which is normally saved and restored by function calls on your
2826: machine, so that library routines will not clobber it.
2827:
2828: Naturally the register name is cpu-dependent, so you would need to
2829: conditionalize your program according to cpu type. The register
2830: @code{a5} would be a good choice on a 68000 for a variable of pointer
2831: type. On machines with register windows, be sure to choose a ``global''
2832: register that is not affected by the function call mechanism.
2833:
2834: In addition, operating systems on one type of cpu may differ in how they
2835: name the registers; then you would need additional conditionals. For
2836: example, some 68000 operating systems call this register @code{%a5}.
2837:
2838: Eventually there may be a way of asking the compiler to choose a register
2839: automatically, but first we need to figure out how it should choose and
1.1.1.6 root 2840: how to enable you to guide the choice. No solution is evident.
1.1.1.5 root 2841:
2842: Defining a global register variable in a certain register reserves that
2843: register entirely for this use, at least within the current compilation.
2844: The register will not be allocated for any other purpose in the functions
2845: in the current compilation. The register will not be saved and restored by
2846: these functions. Stores into this register are never deleted even if they
2847: would appear to be dead, but references may be deleted or moved or
2848: simplified.
2849:
2850: It is not safe to access the global register variables from signal
2851: handlers, or from more than one thread of control, because the system
2852: library routines may temporarily use the register for other things (unless
2853: you recompile them specially for the task at hand).
2854:
2855: It is not safe for one function that uses a global register variable to
2856: call another such function @code{foo} by way of a third function
2857: @code{lose} that was compiled without knowledge of this variable (i.e. in a
2858: different source file in which the variable wasn't declared). This is
2859: because @code{lose} might save the register and put some other value there.
2860: For example, you can't expect a global register variable to be available in
2861: the comparison-function that you pass to @code{qsort}, since @code{qsort}
2862: might have put something else in that register. (If you are prepared to
2863: recompile @code{qsort} with the same global register variable, you can
2864: solve this problem.)
2865:
2866: If you want to recompile @code{qsort} or other source files which do not
2867: actually use your global register variable, so that they will not use that
2868: register for any other purpose, then it suffices to specify the compiler
2869: option @samp{-ffixed-@var{reg}}. You need not actually add a global
2870: register declaration to their source code.
2871:
2872: A function which can alter the value of a global register variable cannot
2873: safely be called from a function compiled without this variable, because it
2874: could clobber the value the caller expects to find there on return.
2875: Therefore, the function which is the entry point into the part of the
2876: program that uses the global register variable must explicitly save and
2877: restore the value which belongs to its caller.
2878:
2879: On most machines, @code{longjmp} will restore to each global register
2880: variable the value it had at the time of the @code{setjmp}. On some
2881: machines, however, @code{longjmp} will not change the value of global
2882: register variables. To be portable, the function that called @code{setjmp}
2883: should make other arrangements to save the values of the global register
2884: variables, and to restore them if a @code{longjmp}. This way, the the same
2885: thing will happen regardless of what @code{longjmp} does.
2886:
2887: All global register variable declarations must precede all function
2888: definitions. If such a declaration could appear after function
2889: definitions, the declaration would be too late to prevent the register from
2890: being used for other purposes in the preceding functions.
2891:
1.1.1.6 root 2892: Global register variables may not have initial values, because an
2893: executable file has no means to supply initial contents for a register.
2894:
1.1.1.7 ! root 2895: @node Alternate Keywords,, Global Reg Vars, Extensions
! 2896: @section Alternate Keywords
! 2897:
! 2898: The option @samp{-traditional} disables certain keywords; @samp{-ansi}
! 2899: disables certain others. This causes trouble when you want to use GNU C
! 2900: extensions, or ANSI C features, in a general-purpose header file that
! 2901: should be usable by all programs, including ANSI C programs and traditional
! 2902: ones. The keywords @code{asm}, @code{typeof} and @code{inline} cannot be
! 2903: used since they won't work in a program compiled with @samp{-ansi}, while
! 2904: the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof}
! 2905: and @code{inline} won't work in a program compiled with
! 2906: @samp{-traditional}.@refill
! 2907:
! 2908: The way to solve these problems is to put @samp{__} in front of each
! 2909: problematical keyword. For example, use @code{__asm} instead of @code{asm},
! 2910: @code{__const} instead of @code{const}, and @code{__inline} instead of
! 2911: @code{inline}.
! 2912:
! 2913: Other C compilers won't accept these alternative keywords; if you want to
! 2914: compile with another compiler, you can define the alternate keywords as
! 2915: macros to replace them with the customary keywords. It looks like this:
! 2916:
! 2917: @example
! 2918: #ifndef __GNUC__
! 2919: #define __asm asm
! 2920: #endif
! 2921: @end example
! 2922:
1.1 root 2923: @node Bugs, Portability, Extensions, Top
2924: @chapter Reporting Bugs
2925:
2926: Your bug reports play an essential role in making GNU CC reliable.
2927:
2928: Reporting a bug may help you by bringing a solution to your problem, or it
2929: may not. But in any case the important function of a bug report is to help
2930: the entire community by making the next version of GNU CC work better. Bug
2931: reports are your contribution to the maintenance of GNU CC.
2932:
2933: In order for a bug report to serve its purpose, you must include the
2934: information that makes for fixing the bug.
2935:
2936: @menu
2937: * Criteria: Bug Criteria. Have you really found a bug?
2938: * Reporting: Bug Reporting. How to report a bug effectively.
2939: @end menu
2940:
2941: @node Bug Criteria, Bug Reporting, Bugs, Bugs
2942: @section Have You Found a Bug?
2943:
2944: If you are not sure whether you have found a bug, here are some guidelines:
2945:
2946: @itemize @bullet
2947: @item
2948: If the compiler gets a fatal signal, for any input whatever, that is a
2949: compiler bug. Reliable compilers never crash.
2950:
2951: @item
2952: If the compiler produces invalid assembly code, for any input whatever
2953: (except an @code{asm} statement), that is a compiler bug, unless the
2954: compiler reports errors (not just warnings) which would ordinarily
2955: prevent the assembler from being run.
2956:
2957: @item
2958: If the compiler produces valid assembly code that does not correctly
2959: execute the input source code, that is a compiler bug.
2960:
2961: However, you must double-check to make sure, because you may have run
2962: into an incompatibility between GNU C and traditional C
2963: (@pxref{Incompatibilities}). These incompatibilities might be considered
2964: bugs, but they are inescapable consequences of valuable features.
2965:
2966: Or you may have a program whose behavior is undefined, which happened
2967: by chance to give the desired results with another C compiler.
2968:
2969: For example, in many nonoptimizing compilers, you can write @samp{x;}
2970: at the end of a function instead of @samp{return x;}, with the same
2971: results. But the value of the function is undefined if @samp{return}
2972: is omitted; it is not a bug when GNU CC produces different results.
2973:
2974: Problems often result from expressions with two increment operators,
2975: as in @samp{f (*p++, *p++)}. Your previous compiler might have
2976: interpreted that expression the way you intended; GNU CC might
2977: interpret it another way; neither compiler is wrong.
2978:
2979: After you have localized the error to a single source line, it should
2980: be easy to check for these things. If your program is correct and
2981: well defined, you have found a compiler bug.
2982:
2983: @item
2984: If the compiler produces an error message for valid input, that is a
2985: compiler bug.
2986:
2987: Note that the following is not valid input, and the error message for
2988: it is not a bug:
2989:
2990: @example
2991: int foo (char);
2992:
2993: int
2994: foo (x)
2995: char x;
2996: @{ @dots{} @}
2997: @end example
2998:
2999: @noindent
3000: The prototype says to pass a @code{char}, while the definition says to
3001: pass an @code{int} and treat the value as a @code{char}. This is what
3002: the ANSI standard says, and it makes sense.
3003:
3004: @item
3005: If the compiler does not produce an error message for invalid input,
3006: that is a compiler bug. However, you should note that your idea of
3007: ``invalid input'' might be my idea of ``an extension'' or ``support
3008: for traditional practice''.
3009:
3010: @item
3011: If you are an experienced user of C compilers, your suggestions
3012: for improvement of GNU CC are welcome in any case.
3013: @end itemize
3014:
3015: @node Bug Reporting,, Bug Criteria, Bugs
3016: @section How to Report Bugs
3017:
3018: Send bug reports for GNU C to one of these addresses:
3019:
3020: @example
3021: bug-gcc@@prep.ai.mit.edu
3022: @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gcc
3023: @end example
3024:
3025: As a last resort, snail them to:
3026:
3027: @example
3028: GNU Compiler Bugs
3029: 545 Tech Sq
3030: Cambridge, MA 02139
3031: @end example
3032:
3033: The fundamental principle of reporting bugs usefully is this:
3034: @strong{report all the facts}. If you are not sure whether to mention a
3035: fact or leave it out, mention it!
3036:
3037: Often people omit facts because they think they know what causes the
3038: problem and they conclude that some details don't matter. Thus, you might
3039: assume that the name of the variable you use in an example does not matter.
3040: Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
3041: stray memory reference which happens to fetch from the location where that
3042: name is stored in memory; perhaps, if the name were different, the contents
3043: of that location would fool the compiler into doing the right thing despite
3044: the bug. Play it safe and give an exact example.
3045:
3046: If you want to enable me to fix the bug, you should include all these
3047: things:
3048:
3049: @itemize @bullet
3050: @item
3051: The version of GNU CC. You can get this by running it with the
3052: @samp{-v} option.
3053:
3054: Without this, I won't know whether there is any point in looking for
3055: the bug in the current version of GNU CC.
3056:
3057: @item
3058: A complete input file that will reproduce the bug. If the bug is in
3059: the C preprocessor, send me a source file and any header files that it
3060: requires. If the bug is in the compiler proper (@file{cc1}), run your
3061: source file through the C preprocessor by doing @samp{gcc -E
3062: @var{sourcefile} > @var{outfile}}, then include the contents of
3063: @var{outfile} in the bug report. (Any @samp{-I}, @samp{-D} or
3064: @samp{-U} options that you used in actual compilation should also be
3065: used when doing this.)
3066:
3067: A single statement is not enough of an example. In order to compile
3068: it, it must be embedded in a function definition; and the bug might
3069: depend on the details of how this is done.
3070:
3071: Without a real example I can compile, all I can do about your bug
3072: report is wish you luck. It would be futile to try to guess how to
3073: provoke the bug. For example, bugs in register allocation and
3074: reloading frequently depend on every little detail of the function
3075: they happen in.
3076:
3077: @item
3078: The command arguments you gave GNU CC to compile that example and
3079: observe the bug. For example, did you use @samp{-O}? To guarantee
3080: you won't omit something important, list them all.
3081:
3082: If I were to try to guess the arguments, I would probably guess wrong
3083: and then I would not encounter the bug.
3084:
3085: @item
3086: The names of the files that you used for @file{tm.h} and @file{md}
3087: when you installed the compiler.
3088:
3089: @item
3090: The type of machine you are using, and the operating system name and
3091: version number.
3092:
3093: @item
3094: A description of what behavior you observe that you believe is
3095: incorrect. For example, ``It gets a fatal signal,'' or, ``There is an
3096: incorrect assembler instruction in the output.''
3097:
3098: Of course, if the bug is that the compiler gets a fatal signal, then I
3099: will certainly notice it. But if the bug is incorrect output, I might
3100: not notice unless it is glaringly wrong. I won't study all the
3101: assembler code from a 50-line C program just on the off chance that it
3102: might be wrong.
3103:
3104: Even if the problem you experience is a fatal signal, you should still
3105: say so explicitly. Suppose something strange is going on, such as,
3106: your copy of the compiler is out of synch, or you have encountered a
3107: bug in the C library on your system. (This has happened!) Your copy
3108: might crash and mine would not. If you @i{told} me to expect a crash,
3109: then when mine fails to crash, I would know that the bug was not
3110: happening for me. If you had not told me to expect a crash, then I
3111: would not be able to draw any conclusion from my observations.
3112:
3113: In cases where GNU CC generates incorrect code, if you send me a small
3114: complete sample program I will find the error myself by running the
3115: program under a debugger. If you send me a large example or a part of
3116: a larger program, I cannot do this; you must debug the compiled
3117: program and narrow the problem down to one source line. Tell me which
3118: source line it is, and what you believe is incorrect about the code
3119: generated for that line.
3120:
3121: @item
3122: If you send me examples of output from GNU CC, please use @samp{-g}
3123: when you make them. The debugging information includes source line
3124: numbers which are essential for correlating the output with the input.
3125:
3126: @item
3127: If you wish to suggest changes to the GNU CC source, send me context
3128: diffs. If you even discuss something in the GNU CC source, refer to
3129: it by context, not by line number.
3130:
3131: The line numbers in my development sources don't match those in your
3132: sources. Your line numbers would convey no useful information to me.
3133:
3134: @item
3135: Additional information from a debugger might enable me to find
3136: a problem on a machine which I do not have available myself.
3137: However, you need to think when you collect this information if
3138: you want it to have any chance of being useful.
3139:
3140: For example, many people send just a backtrace, but that is never
3141: useful by itself. A simple backtrace with arguments conveys little
3142: about GNU CC because the compiler is largely data-driven; the same
3143: functions are called over and over for different RTL insns, doing
3144: different things depending on the details of the insn.
3145:
3146: Most of the arguments listed in the backtrace are useless because they
3147: are pointers to RTL list structure. The numeric values of the
3148: pointers, which the debugger prints in the backtrace, have no
3149: significance whatever; all that matters is the contents of the objects
3150: they point to (and most of the contents are other such pointers).
3151:
3152: In addition, most compiler passes consist of one or more loops that
3153: scan the RTL insn sequence. The most vital piece of information about
3154: such a loop--which insn it has reached--is usually in a local variable,
3155: not in an argument.
3156:
3157: What you need to provide in addition to a backtrace are the values of
3158: the local variables for several stack frames up. When a local
3159: variable or an argument is an RTX, first print its value and then use
3160: the GDB command @code{pr} to print the RTL expression that it points
3161: to. (If GDB doesn't run on your machine, use your debugger to call
3162: the function @code{debug_rtx} with the RTX as an argument.) In
3163: general, whenever a variable is a pointer, its value is no use
3164: without the data it points to.
3165:
3166: In addition, include a debugging dump from just before the pass
3167: in which the crash happens. Most bugs involve a series of insns,
3168: not just one.
3169: @end itemize
3170:
3171: Here are some things that are not necessary:
3172:
3173: @itemize @bullet
3174: @item
3175: A description of the envelope of the bug.
3176:
3177: Often people who encounter a bug spend a lot of time investigating
3178: which changes to the input file will make the bug go away and which
3179: changes will not affect it.
3180:
3181: This is often time consuming and not very useful, because the way I
3182: will find the bug is by running a single example under the debugger
3183: with breakpoints, not by pure deduction from a series of examples.
3184:
3185: Of course, if you can find a simpler example to report @emph{instead}
3186: of the original one, that is a convenience for me. Errors in the
3187: output will be easier to spot, running under the debugger will take
3188: less time, etc. Most GNU CC bugs involve just one function, so the
3189: most straightforward way to simplify an example is to delete all the
3190: function definitions except the one where the bug occurs. Those
3191: earlier in the file may be replaced by external declarations if the
3192: crucial function depends on them.
3193:
3194: However, simplification is not vital; if you don't want to do this,
3195: report the bug anyway.
3196:
3197: @item
3198: A patch for the bug.
3199:
3200: A patch for the bug does help me if it is a good one. But don't omit
3201: the necessary information, such as the test case, because I might see
3202: problems with your patch and decide to fix the problem another way.
3203:
3204: Sometimes with a program as complicated as GNU CC it is very hard to
3205: construct an example that will make the program follow a certain path
3206: through the code. If you don't send me the example, I won't be able
3207: to construct one, so I won't be able to verify that the bug is fixed.
3208:
3209: @item
3210: A guess about what the bug is or what it depends on.
3211:
3212: Such guesses are usually wrong. Even I can't guess right about such
3213: things without using the debugger to find the facts.
3214: @end itemize
3215:
3216: @node Portability, Interface, Bugs, Top
3217: @chapter GNU CC and Portability
3218:
3219: The main goal of GNU CC was to make a good, fast compiler for machines in
3220: the class that the GNU system aims to run on: 32-bit machines that address
3221: 8-bit bytes and have several general registers. Elegance, theoretical
3222: power and simplicity are only secondary.
3223:
3224: GNU CC gets most of the information about the target machine from a machine
3225: description which gives an algebraic formula for each of the machine's
3226: instructions. This is a very clean way to describe the target. But when
3227: the compiler needs information that is difficult to express in this
3228: fashion, I have not hesitated to define an ad-hoc parameter to the machine
3229: description. The purpose of portability is to reduce the total work needed
3230: on the compiler; it was not of interest for its own sake.
3231:
3232: GNU CC does not contain machine dependent code, but it does contain code
3233: that depends on machine parameters such as endianness (whether the most
3234: significant byte has the highest or lowest address of the bytes in a word)
3235: and the availability of autoincrement addressing. In the RTL-generation
3236: pass, it is often necessary to have multiple strategies for generating code
3237: for a particular kind of syntax tree, strategies that are usable for different
3238: combinations of parameters. Often I have not tried to address all possible
3239: cases, but only the common ones or only the ones that I have encountered.
3240: As a result, a new target may require additional strategies. You will know
3241: if this happens because the compiler will call @code{abort}. Fortunately,
3242: the new strategies can be added in a machine-independent fashion, and will
3243: affect only the target machines that need them.
3244:
3245: @node Interface, Passes, Portability, Top
3246: @chapter Interfacing to GNU CC Output
3247:
3248: GNU CC is normally configured to use the same function calling convention
3249: normally in use on the target system. This is done with the
3250: machine-description macros described (@pxref{Machine Macros}).
3251:
3252: However, returning of structure and union values is done differently on
3253: some target machines. As a result, functions compiled with PCC
3254: returning such types cannot be called from code compiled with GNU CC,
3255: and vice versa. This does not cause trouble often because few Unix
3256: library routines return structures or unions.
3257:
3258: GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes
3259: long in the same registers used for @code{int} or @code{double} return
3260: values. (GNU CC typically allocates variables of such types in
3261: registers also.) Structures and unions of other sizes are returned by
3262: storing them into an address passed by the caller (usually in a
3263: register). The machine-description macros @code{STRUCT_VALUE} and
3264: @code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address.
3265:
3266: By contrast, PCC on most target machines returns structures and unions
3267: of any size by copying the data into an area of static storage, and then
3268: returning the address of that storage as if it were a pointer value.
3269: The caller must copy the data from that memory area to the place where
3270: the value is wanted. This is slower than the method used by GNU CC, and
3271: fails to be reentrant.
3272:
3273: On some target machines, such as RISC machines and the 80386, the
3274: standard system convention is to pass to the subroutine the address of
3275: where to return the value. On these machines, GNU CC has been
3276: configured to be compatible with the standard compiler, when this method
3277: is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3278:
3279: GNU CC uses the system's standard convention for passing arguments. On
3280: some machines, the first few arguments are passed in registers; in
3281: others, all are passed on the stack. It would be possible to use
3282: registers for argument passing on any machine, and this would probably
3283: result in a significant speedup. But the result would be complete
3284: incompatibility with code that follows the standard convention. So this
3285: change is practical only if you are switching to GNU CC as the sole C
3286: compiler for the system. We may implement register argument passing on
3287: certain machines once we have a complete GNU system so that we can
3288: compile the libraries with GNU CC.
3289:
3290: If you use @code{longjmp}, beware of automatic variables. ANSI C says that
3291: automatic variables that are not declared @code{volatile} have undefined
3292: values after a @code{longjmp}. And this is all GNU CC promises to do,
3293: because it is very difficult to restore register variables correctly, and
3294: one of GNU CC's features is that it can put variables in registers without
3295: your asking it to.
3296:
3297: If you want a variable to be unaltered by @code{longjmp}, and you don't
3298: want to write @code{volatile} because old C compilers don't accept it,
3299: just take the address of the variable. If a variable's address is ever
3300: taken, even if just to compute it and ignore it, then the variable cannot
3301: go in a register:
3302:
3303: @example
3304: @{
3305: int careful;
3306: &careful;
3307: @dots{}
3308: @}
3309: @end example
3310:
3311: Code compiled with GNU CC may call certain library routines. Most of
3312: them handle arithmetic for which there are no instructions. This
3313: includes multiply and divide on some machines, and floating point
3314: operations on any machine for which floating point support is disabled
3315: with @samp{-msoft-float}. Some standard parts of the C library, such as
3316: @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3317: function call interface is used for calling the library routines.
3318:
3319: These library routines should be defined in the library @file{gnulib},
3320: which GNU CC automatically searches whenever it links a program. On
3321: machines that have multiply and divide instructions, if hardware
3322: floating point is in use, normally @file{gnulib} is not needed, but it
3323: is searched just in case.
3324:
3325: Each arithmetic function is defined in @file{gnulib.c} to use the
3326: corresponding C arithmetic operator. As long as the file is compiled
3327: with another C compiler, which supports all the C arithmetic operators,
3328: this file will work portably. However, @file{gnulib.c} does not work if
3329: compiled with GNU CC, because each arithmetic function would compile
3330: into a call to itself!
3331:
3332: @node Passes, RTL, Interface, Top
3333: @chapter Passes and Files of the Compiler
3334:
3335: The overall control structure of the compiler is in @file{toplev.c}. This
3336: file is responsible for initialization, decoding arguments, opening and
3337: closing files, and sequencing the passes.
3338:
3339: The parsing pass is invoked only once, to parse the entire input. The RTL
3340: intermediate code for a function is generated as the function is parsed, a
3341: statement at a time. Each statement is read in as a syntax tree and then
3342: converted to RTL; then the storage for the tree for the statement is
3343: reclaimed. Storage for types (and the expressions for their sizes),
3344: declarations, and a representation of the binding contours and how they nest,
3345: remains until the function is finished being compiled; these are all needed
3346: to output the debugging information.
3347:
3348: Each time the parsing pass reads a complete function definition or
3349: top-level declaration, it calls the function
3350: @code{rest_of_compilation} or @code{rest_of_decl_compilation} in
3351: @file{toplev.c}, which are responsible for all further processing
3352: necessary, ending with output of the assembler language. All other
3353: compiler passes run, in sequence, within @code{rest_of_compilation}.
3354: When that function returns from compiling a function definition, the
3355: storage used for that function definition's compilation is entirely
3356: freed, unless it is an inline function (@pxref{Inline}).
3357:
3358: Here is a list of all the passes of the compiler and their source files.
3359: Also included is a description of where debugging dumps can be requested
3360: with @samp{-d} options.
3361:
3362: @itemize @bullet
3363: @item
3364: Parsing. This pass reads the entire text of a function definition,
3365: constructing partial syntax trees. This and RTL generation are no longer
3366: truly separate passes (formerly they were), but it is easier to think
3367: of them as separate.
3368:
3369: The tree representation does not entirely follow C syntax, because it is
3370: intended to support other languages as well.
3371:
3372: C data type analysis is also done in this pass, and every tree node
3373: that represents an expression has a data type attached. Variables are
3374: represented as declaration nodes.
3375:
3376: Constant folding and associative-law simplifications are also done
3377: during this pass.
3378:
3379: The source files for parsing are @file{c-parse.y}, @file{c-decl.c},
3380: @file{c-typeck.c}, @file{c-convert.c}, @file{stor-layout.c},
3381: @file{fold-const.c}, and @file{tree.c}. The last three files are
3382: intended to be language-independent. There are also header files
3383: @file{c-parse.h}, @file{c-tree.h}, @file{tree.h} and @file{tree.def}.
3384: The last two define the format of the tree representation.@refill
3385:
3386: @item
3387: RTL generation. This is the conversion of syntax tree into RTL code.
3388: It is actually done statement-by-statement during parsing, but for
3389: most purposes it can be thought of as a separate pass.
3390:
3391: This is where the bulk of target-parameter-dependent code is found,
3392: since often it is necessary for strategies to apply only when certain
3393: standard kinds of instructions are available. The purpose of named
3394: instruction patterns is to provide this information to the RTL
3395: generation pass.
3396:
3397: Optimization is done in this pass for @code{if}-conditions that are
3398: comparisons, boolean operations or conditional expressions. Tail
3399: recursion is detected at this time also. Decisions are made about how
3400: best to arrange loops and how to output @code{switch} statements.
3401:
3402: The source files for RTL generation are @file{stmt.c}, @file{expr.c},
3403: @file{explow.c}, @file{expmed.c}, @file{optabs.c} and @file{emit-rtl.c}.
3404: Also, the file @file{insn-emit.c}, generated from the machine description
3405: by the program @code{genemit}, is used in this pass. The header files
3406: @file{expr.h} is used for communication within this pass.@refill
3407:
3408: The header files @file{insn-flags.h} and @file{insn-codes.h},
3409: generated from the machine description by the programs @code{genflags}
3410: and @code{gencodes}, tell this pass which standard names are available
3411: for use and which patterns correspond to them.@refill
3412:
3413: Aside from debugging information output, none of the following passes
3414: refers to the tree structure representation of the function (only
3415: part of which is saved).
3416:
3417: The decision of whether the function can and should be expanded inline
3418: in its subsequent callers is made at the end of rtl generation. The
3419: function must meet certain criteria, currently related to the size of
3420: the function and the types and number of parameters it has. Note that
3421: this function may contain loops, recursive calls to itself
3422: (tail-recursive functions can be inlined!), gotos, in short, all
3423: constructs supported by GNU CC.
3424:
3425: The option @samp{-dr} causes a debugging dump of the RTL code after
3426: this pass. This dump file's name is made by appending @samp{.rtl} to
3427: the input file name.
3428:
3429: @item
3430: Jump optimization. This pass simplifies jumps to the following
3431: instruction, jumps across jumps, and jumps to jumps. It deletes
3432: unreferenced labels and unreachable code, except that unreachable code
3433: that contains a loop is not recognized as unreachable in this pass.
3434: (Such loops are deleted later in the basic block analysis.)
3435:
3436: Jump optimization is performed two or three times. The first time is
3437: immediately following RTL generation. The second time is after CSE,
3438: but only if CSE says repeated jump optimization is needed. The
3439: last time is right before the final pass. That time, cross-jumping
3440: and deletion of no-op move instructions are done together with the
3441: optimizations described above.
3442:
3443: The source file of this pass is @file{jump.c}.
3444:
3445: The option @samp{-dj} causes a debugging dump of the RTL code after
3446: this pass is run for the first time. This dump file's name is made by
3447: appending @samp{.jump} to the input file name.
3448:
3449: @item
3450: Register scan. This pass finds the first and last use of each
3451: register, as a guide for common subexpression elimination. Its source
3452: is in @file{regclass.c}.
3453:
3454: @item
3455: Common subexpression elimination. This pass also does constant
3456: propagation. Its source file is @file{cse.c}. If constant
3457: propagation causes conditional jumps to become unconditional or to
3458: become no-ops, jump optimization is run again when CSE is finished.
3459:
3460: The option @samp{-ds} causes a debugging dump of the RTL code after
3461: this pass. This dump file's name is made by appending @samp{.cse} to
3462: the input file name.
3463:
3464: @item
3465: Loop optimization. This pass moves constant expressions out of loops.
3466: Its source file is @file{loop.c}.
3467:
3468: The option @samp{-dL} causes a debugging dump of the RTL code after
3469: this pass. This dump file's name is made by appending @samp{.loop} to
3470: the input file name.
3471:
3472: @item
3473: Stupid register allocation is performed at this point in a
3474: nonoptimizing compilation. It does a little data flow analysis as
3475: well. When stupid register allocation is in use, the next pass
3476: executed is the reloading pass; the others in between are skipped.
3477: The source file is @file{stupid.c}.
3478:
3479: @item
3480: Data flow analysis (@file{flow.c}). This pass divides the program
3481: into basic blocks (and in the process deletes unreachable loops); then
3482: it computes which pseudo-registers are live at each point in the
3483: program, and makes the first instruction that uses a value point at
3484: the instruction that computed the value.
3485:
3486: This pass also deletes computations whose results are never used, and
3487: combines memory references with add or subtract instructions to make
3488: autoincrement or autodecrement addressing.
3489:
3490: The option @samp{-df} causes a debugging dump of the RTL code after
3491: this pass. This dump file's name is made by appending @samp{.flow} to
3492: the input file name. If stupid register allocation is in use, this
3493: dump file reflects the full results of such allocation.
3494:
3495: @item
3496: Instruction combination (@file{combine.c}). This pass attempts to
3497: combine groups of two or three instructions that are related by data
3498: flow into single instructions. It combines the RTL expressions for
3499: the instructions by substitution, simplifies the result using algebra,
3500: and then attempts to match the result against the machine description.
3501:
3502: The option @samp{-dc} causes a debugging dump of the RTL code after
3503: this pass. This dump file's name is made by appending @samp{.combine}
3504: to the input file name.
3505:
3506: @item
3507: Register class preferencing. The RTL code is scanned to find out
3508: which register class is best for each pseudo register. The source
3509: file is @file{regclass.c}.
3510:
3511: @item
3512: Local register allocation (@file{local-alloc.c}). This pass allocates
3513: hard registers to pseudo registers that are used only within one basic
3514: block. Because the basic block is linear, it can use fast and
3515: powerful techniques to do a very good job.
3516:
3517: The option @samp{-dl} causes a debugging dump of the RTL code after
3518: this pass. This dump file's name is made by appending @samp{.lreg} to
3519: the input file name.
3520:
3521: @item
3522: Global register allocation (@file{global-alloc.c}). This pass
3523: allocates hard registers for the remaining pseudo registers (those
3524: whose life spans are not contained in one basic block).
3525:
3526: @item
3527: Reloading. This pass renumbers pseudo registers with the hardware
3528: registers numbers they were allocated. Pseudo registers that did not
3529: get hard registers are replaced with stack slots. Then it finds
3530: instructions that are invalid because a value has failed to end up in
3531: a register, or has ended up in a register of the wrong kind. It fixes
3532: up these instructions by reloading the problematical values
3533: temporarily into registers. Additional instructions are generated to
3534: do the copying.
3535:
3536: Source files are @file{reload.c} and @file{reload1.c}, plus the header
3537: @file{reload.h} used for communication between them.
3538:
3539: The option @samp{-dg} causes a debugging dump of the RTL code after
3540: this pass. This dump file's name is made by appending @samp{.greg} to
3541: the input file name.
3542:
3543: @item
3544: Jump optimization is repeated, this time including cross-jumping
1.1.1.5 root 3545: and deletion of no-op move instructions.
1.1 root 3546:
3547: The option @samp{-dJ} causes a debugging dump of the RTL code after
3548: this pass. This dump file's name is made by appending @samp{.jump2}
3549: to the input file name.
3550:
3551: @item
3552: Final. This pass outputs the assembler code for the function. It is
3553: also responsible for identifying spurious test and compare
1.1.1.5 root 3554: instructions. Machine-specific peephole optimizations are performed
3555: at the same time. The function entry and exit sequences are generated
1.1 root 3556: directly as assembler code in this pass; they never exist as RTL.
3557:
3558: The source files are @file{final.c} plus @file{insn-output.c}; the
3559: latter is generated automatically from the machine description by the
3560: tool @file{genoutput}. The header file @file{conditions.h} is used
3561: for communication between these files.
3562:
3563: @item
3564: Debugging information output. This is run after final because it must
3565: output the stack slot offsets for pseudo registers that did not get
3566: hard registers. Source files are @file{dbxout.c} for DBX symbol table
3567: format and @file{symout.c} for GDB's own symbol table format.
3568: @end itemize
3569:
3570: Some additional files are used by all or many passes:
3571:
3572: @itemize @bullet
3573: @item
3574: Every pass uses @file{machmode.def}, which defines the machine modes.
3575:
3576: @item
3577: All the passes that work with RTL use the header files @file{rtl.h}
3578: and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
3579: @code{gen*} also use these files to read and work with the machine
3580: description RTL.
3581:
3582: @item
3583: Several passes refer to the header file @file{insn-config.h} which
3584: contains a few parameters (C macro definitions) generated
3585: automatically from the machine description RTL by the tool
3586: @code{genconfig}.
3587:
3588: @item
3589: Several passes use the instruction recognizer, which consists of
3590: @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3591: and @file{insn-extract.c} that are generated automatically from the
3592: machine description by the tools @file{genrecog} and
3593: @file{genextract}.@refill
3594:
3595: @item
3596: Several passes use the header files @file{regs.h} which defines the
3597: information recorded about pseudo register usage, and @file{basic-block.h}
3598: which defines the information recorded about basic blocks.
3599:
3600: @item
3601: @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3602: with a bit for each hard register, and some macros to manipulate it.
3603: This type is just @code{int} if the machine has few enough hard registers;
3604: otherwise it is an array of @code{int} and some of the macros expand
3605: into loops.
3606: @end itemize
3607:
3608: @node RTL, Machine Desc, Passes, Top
3609: @chapter RTL Representation
3610:
3611: Most of the work of the compiler is done on an intermediate representation
3612: called register transfer language. In this language, the instructions to be
3613: output are described, pretty much one by one, in an algebraic form that
3614: describes what the instruction does.
3615:
3616: RTL is inspired by Lisp lists. It has both an internal form, made up of
3617: structures that point at other structures, and a textual form that is used
3618: in the machine description and in printed debugging dumps. The textual
3619: form uses nested parentheses to indicate the pointers in the internal form.
3620:
3621: @menu
3622: * RTL Objects:: Expressions vs vectors vs strings vs integers.
3623: * Accessors:: Macros to access expression operands or vector elts.
3624: * Flags:: Other flags in an RTL expression.
3625: * Machine Modes:: Describing the size and format of a datum.
3626: * Constants:: Expressions with constant values.
3627: * Regs and Memory:: Expressions representing register contents or memory.
3628: * Arithmetic:: Expressions representing arithmetic on other expressions.
3629: * Comparisons:: Expressions representing comparison of expressions.
3630: * Bit Fields:: Expressions representing bit-fields in memory or reg.
3631: * Conversions:: Extending, truncating, floating or fixing.
3632: * RTL Declarations:: Declaring volatility, constancy, etc.
3633: * Side Effects:: Expressions for storing in registers, etc.
3634: * Incdec:: Embedded side-effects for autoincrement addressing.
3635: * Assembler:: Representing @code{asm} with operands.
3636: * Insns:: Expression types for entire insns.
3637: * Calls:: RTL representation of function call insns.
3638: * Sharing:: Some expressions are unique; others *must* be copied.
3639: @end menu
3640:
3641: @node RTL Objects, Accessors, RTL, RTL
3642: @section RTL Object Types
3643:
3644: RTL uses four kinds of objects: expressions, integers, strings and vectors.
3645: Expressions are the most important ones. An RTL expression (``RTX'', for
3646: short) is a C structure, but it is usually referred to with a pointer; a
3647: type that is given the typedef name @code{rtx}.
3648:
3649: An integer is simply an @code{int}, and a string is a @code{char *}.
3650: Within RTL code, strings appear only inside @samp{symbol_ref} expressions,
3651: but they appear in other contexts in the RTL expressions that make up
3652: machine descriptions. Their written form uses decimal digits.
3653:
3654: A string is a sequence of characters. In core it is represented as a
3655: @code{char *} in usual C fashion, and it is written in C syntax as well.
3656: However, strings in RTL may never be null. If you write an empty string in
3657: a machine description, it is represented in core as a null pointer rather
3658: than as a pointer to a null character. In certain contexts, these null
3659: pointers instead of strings are valid.
3660:
3661: A vector contains an arbitrary, specified number of pointers to
3662: expressions. The number of elements in the vector is explicitly present in
3663: the vector. The written form of a vector consists of square brackets
3664: (@samp{[@dots{}]}) surrounding the elements, in sequence and with
3665: whitespace separating them. Vectors of length zero are not created; null
3666: pointers are used instead.
3667:
3668: Expressions are classified by @dfn{expression codes} (also called RTX
3669: codes). The expression code is a name defined in @file{rtl.def}, which is
3670: also (in upper case) a C enumeration constant. The possible expression
3671: codes and their meanings are machine-independent. The code of an RTX can
3672: be extracted with the macro @code{GET_CODE (@var{x})} and altered with
3673: @code{PUT_CODE (@var{x}, @var{newcode})}.
3674:
3675: The expression code determines how many operands the expression contains,
3676: and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
3677: by looking at an operand what kind of object it is. Instead, you must know
3678: from its context---from the expression code of the containing expression.
3679: For example, in an expression of code @samp{subreg}, the first operand is
3680: to be regarded as an expression and the second operand as an integer. In
3681: an expression of code @samp{plus}, there are two operands, both of which
3682: are to be regarded as expressions. In a @samp{symbol_ref} expression,
3683: there is one operand, which is to be regarded as a string.
3684:
3685: Expressions are written as parentheses containing the name of the
3686: expression type, its flags and machine mode if any, and then the operands
3687: of the expression (separated by spaces).
3688:
3689: Expression code names in the @samp{md} file are written in lower case,
3690: but when they appear in C code they are written in upper case. In this
3691: manual, they are shown as follows: @samp{const_int}.
3692:
3693: In a few contexts a null pointer is valid where an expression is normally
1.1.1.4 root 3694: wanted. The written form of this is @code{(nil)}.
1.1 root 3695:
3696: @node Accessors, Flags, RTL Objects, RTL
3697: @section Access to Operands
3698:
3699: For each expression type @file{rtl.def} specifies the number of contained
3700: objects and their kinds, with four possibilities: @samp{e} for expression
3701: (actually a pointer to an expression), @samp{i} for integer, @samp{s} for
3702: string, and @samp{E} for vector of expressions. The sequence of letters
3703: for an expression code is called its @dfn{format}. Thus, the format of
3704: @samp{subreg} is @samp{ei}.@refill
3705:
3706: Two other format characters are used occasionally: @samp{u} and @samp{0}.
3707: @samp{u} is equivalent to @samp{e} except that it is printed differently in
3708: debugging dumps, and @samp{0} means a slot whose contents do not fit any
3709: normal category. @samp{0} slots are not printed at all in dumps, and are
3710: often used in special ways by small parts of the compiler.@refill
3711:
3712: There are macros to get the number of operands and the format of an
3713: expression code:
3714:
3715: @table @code
3716: @item GET_RTX_LENGTH (@var{code})
3717: Number of operands of an RTX of code @var{code}.
3718:
3719: @item GET_RTX_FORMAT (@var{code})
3720: The format of an RTX of code @var{code}, as a C string.
3721: @end table
3722:
3723: Operands of expressions are accessed using the macros @code{XEXP},
3724: @code{XINT} and @code{XSTR}. Each of these macros takes two arguments: an
3725: expression-pointer (RTX) and an operand number (counting from zero).
3726: Thus,@refill
3727:
3728: @example
3729: XEXP (@var{x}, 2)
3730: @end example
3731:
3732: @noindent
3733: accesses operand 2 of expression @var{x}, as an expression.
3734:
3735: @example
3736: XINT (@var{x}, 2)
3737: @end example
3738:
3739: @noindent
3740: accesses the same operand as an integer. @code{XSTR}, used in the same
3741: fashion, would access it as a string.
3742:
3743: Any operand can be accessed as an integer, as an expression or as a string.
3744: You must choose the correct method of access for the kind of value actually
3745: stored in the operand. You would do this based on the expression code of
3746: the containing expression. That is also how you would know how many
3747: operands there are.
3748:
3749: For example, if @var{x} is a @samp{subreg} expression, you know that it has
3750: two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
3751: and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
3752: would get the address of the expression operand but cast as an integer;
3753: that might occasionally be useful, but it would be cleaner to write
3754: @code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
3755: compile without error, and would return the second, integer operand cast as
3756: an expression pointer, which would probably result in a crash when
3757: accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
3758: but this will access memory past the end of the expression with
3759: unpredictable results.@refill
3760:
3761: Access to operands which are vectors is more complicated. You can use the
3762: macro @code{XVEC} to get the vector-pointer itself, or the macros
3763: @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
3764: vector.
3765:
3766: @table @code
3767: @item XVEC (@var{exp}, @var{idx})
3768: Access the vector-pointer which is operand number @var{idx} in @var{exp}.
3769:
3770: @item XVECLEN (@var{exp}, @var{idx})
3771: Access the length (number of elements) in the vector which is
3772: in operand number @var{idx} in @var{exp}. This value is an @code{int}.
3773:
3774: @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
3775: Access element number @var{eltnum} in the vector which is
3776: in operand number @var{idx} in @var{exp}. This value is an RTX.
3777:
3778: It is up to you to make sure that @var{eltnum} is not negative
3779: and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
3780: @end table
3781:
3782: All the macros defined in this section expand into lvalues and therefore
3783: can be used to assign the operands, lengths and vector elements as well as
3784: to access them.
3785:
3786: @node Flags, Machine Modes, Accessors, RTL
3787: @section Flags in an RTL Expression
3788:
3789: RTL expressions contain several flags (one-bit bit-fields) that are used
3790: in certain types of expression. Most often they are accessed with the
3791: following macros:
3792:
3793: @table @code
3794: @item MEM_VOLATILE_P (@var{x})
3795: In @samp{mem} expressions, nonzero for volatile memory references.
3796: Stored in the @code{volatil} field and printed as @samp{/v}.
3797:
3798: @item MEM_IN_STRUCT_P (@var{x})
3799: In @samp{mem} expressions, nonzero for reference to an entire
3800: structure, union or array, or to a component of one. Zero for
3801: references to a scalar variable or through a pointer to a scalar.
3802: Stored in the @code{in_struct} field and printed as @samp{/s}.
3803:
3804: @item REG_USER_VAR_P (@var{x})
3805: In a @samp{reg}, nonzero if it corresponds to a variable present in
3806: the user's source code. Zero for temporaries generated internally by
3807: the compiler. Stored in the @code{volatil} field and printed as
3808: @samp{/v}.
3809:
3810: @item REG_FUNCTION_VALUE_P (@var{x})
3811: Nonzero in a @samp{reg} if it is the place in which this function's
3812: value is going to be returned. (This happens only in a hard
3813: register.) Stored in the @code{integrated} field and printed as
3814: @samp{/i}.
3815:
3816: The same hard register may be used also for collecting the values of
3817: functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
3818: in this kind of use.
3819:
3820: @item RTX_UNCHANGING_P (@var{x})
3821: Nonzero in a @samp{reg} or @samp{mem} if the value is not changed
3822: explicitly by the current function. (If it is a memory reference then
3823: it may be changed by other functions or by aliasing.) Stored in the
3824: @code{unchanging} field and printed as @samp{/u}.
3825:
3826: @item RTX_INTEGRATED_P (@var{insn})
3827: Nonzero in an insn if it resulted from an in-line function call.
3828: Stored in the @code{integrated} field and printed as @samp{/i}. This
3829: may be deleted; nothing currently depends on it.
3830:
3831: @item INSN_DELETED_P (@var{insn})
3832: In an insn, nonzero if the insn has been deleted. Stored in the
3833: @code{volatil} field and printed as @samp{/v}.
3834:
3835: @item CONSTANT_POOL_ADDRESS_P (@var{x})
3836: Nonzero in a @samp{symbol_ref} if it refers to part of the current
3837: function's ``constants pool''. These are addresses close to the
3838: beginning of the function, and GNU CC assumes they can be addressed
3839: directly (perhaps with the help of base registers). Stored in the
3840: @code{unchanging} field and printed as @samp{/u}.
3841: @end table
3842:
3843: These are the fields which the above macros refer to:
3844:
3845: @table @code
3846: @item used
3847: This flag is used only momentarily, at the end of RTL generation for a
3848: function, to count the number of times an expression appears in insns.
3849: Expressions that appear more than once are copied, according to the
3850: rules for shared structure (@pxref{Sharing}).
3851:
3852: @item volatil
3853: This flag is used in @samp{mem} and @samp{reg} expressions and in insns.
3854: In RTL dump files, it is printed as @samp{/v}.
3855:
3856: In a @samp{mem} expression, it is 1 if the memory reference is volatile.
3857: Volatile memory references may not be deleted, reordered or combined.
3858:
3859: In a @samp{reg} expression, it is 1 if the value is a user-level variable.
3860: 0 indicates an internal compiler temporary.
3861:
3862: In an insn, 1 means the insn has been deleted.
3863:
3864: @item in_struct
3865: This flag is used in @samp{mem} expressions. It is 1 if the memory
3866: datum referred to is all or part of a structure or array; 0 if it is (or
3867: might be) a scalar variable. A reference through a C pointer has 0
3868: because the pointer might point to a scalar variable.
3869:
3870: This information allows the compiler to determine something about possible
3871: cases of aliasing.
3872:
3873: In an RTL dump, this flag is represented as @samp{/s}.
3874:
3875: @item unchanging
3876: This flag is used in @samp{reg} and @samp{mem} expressions. 1 means
3877: that the value of the expression never changes (at least within the
3878: current function).
3879:
3880: In an RTL dump, this flag is represented as @samp{/u}.
3881:
3882: @item integrated
3883: In some kinds of expressions, including insns, this flag means the
3884: rtl was produced by procedure integration.
3885:
3886: In a @samp{reg} expression, this flag indicates the register
3887: containing the value to be returned by the current function. On
3888: machines that pass parameters in registers, the same register number
3889: may be used for parameters as well, but this flag is not set on such
3890: uses.
3891: @end table
3892:
3893: @node Machine Modes, Constants, Flags, RTL
3894: @section Machine Modes
3895:
3896: A machine mode describes a size of data object and the representation used
3897: for it. In the C code, machine modes are represented by an enumeration
3898: type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
3899: expression has room for a machine mode and so do certain kinds of tree
3900: expressions (declarations and types, to be precise).
3901:
3902: In debugging dumps and machine descriptions, the machine mode of an RTL
3903: expression is written after the expression code with a colon to separate
3904: them. The letters @samp{mode} which appear at the end of each machine mode
3905: name are omitted. For example, @code{(reg:SI 38)} is a @samp{reg}
3906: expression with machine mode @code{SImode}. If the mode is
3907: @code{VOIDmode}, it is not written at all.
3908:
3909: Here is a table of machine modes.
3910:
3911: @table @code
3912: @item QImode
3913: ``Quarter-Integer'' mode represents a single byte treated as an integer.
3914:
3915: @item HImode
3916: ``Half-Integer'' mode represents a two-byte integer.
3917:
1.1.1.7 ! root 3918: @item PSImode
! 3919: ``Partial Single Integer'' mode represents an integer which occupies
! 3920: four bytes but which doesn't really use all four. On some machines,
! 3921: this is the right mode to use for pointers.
! 3922:
1.1 root 3923: @item SImode
3924: ``Single Integer'' mode represents a four-byte integer.
3925:
1.1.1.7 ! root 3926: @item PDImode
! 3927: ``Partial Double Integer'' mode represents an integer which occupies
! 3928: eight bytes but which doesn't really use all eight. On some machines,
! 3929: this is the right mode to use for certain pointers.
! 3930:
1.1 root 3931: @item DImode
3932: ``Double Integer'' mode represents an eight-byte integer.
3933:
3934: @item TImode
3935: ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
3936:
3937: @item SFmode
3938: ``Single Floating'' mode represents a single-precision (four byte) floating
3939: point number.
3940:
3941: @item DFmode
3942: ``Double Floating'' mode represents a double-precision (eight byte) floating
3943: point number.
3944:
1.1.1.7 ! root 3945: @item XFmode
! 3946: ``Extended Floating'' mode represents a triple-precision (twelve byte)
! 3947: floating point number. This mode is used for IEEE extended floating
! 3948: point.
! 3949:
1.1 root 3950: @item TFmode
3951: ``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
3952: floating point number.
3953:
3954: @item BLKmode
3955: ``Block'' mode represents values that are aggregates to which none of
3956: the other modes apply. In RTL, only memory references can have this mode,
3957: and only if they appear in string-move or vector instructions. On machines
3958: which have no such instructions, @code{BLKmode} will not appear in RTL.
3959:
3960: @item VOIDmode
3961: Void mode means the absence of a mode or an unspecified mode.
3962: For example, RTL expressions of code @samp{const_int} have mode
3963: @code{VOIDmode} because they can be taken to have whatever mode the context
3964: requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
3965: the absence of any mode.
3966:
3967: @item EPmode
3968: ``Entry Pointer'' mode is intended to be used for function variables in
3969: Pascal and other block structured languages. Such values contain
3970: both a function address and a static chain pointer for access to
3971: automatic variables of outer levels. This mode is only partially
3972: implemented since C does not use it.
3973:
3974: @item CSImode@r{, @dots{}}
3975: ``Complex Single Integer'' mode stands for a complex number represented
3976: as a pair of @code{SImode} integers. Any of the integer and floating modes
3977: may have @samp{C} prefixed to its name to obtain a complex number mode.
3978: For example, there are @code{CQImode}, @code{CSFmode}, and @code{CDFmode}.
3979: Since C does not support complex numbers, these machine modes are only
3980: partially implemented.
3981:
3982: @item BImode
3983: This is the machine mode of a bit-field in a structure. It is used
3984: only in the syntax tree, never in RTL, and in the syntax tree it appears
3985: only in declaration nodes. In C, it appears only in @code{FIELD_DECL}
3986: nodes for structure fields defined with a bit size.
3987: @end table
3988:
3989: The machine description defines @code{Pmode} as a C macro which expands
3990: into the machine mode used for addresses. Normally this is @code{SImode}.
3991:
3992: The only modes which a machine description @i{must} support are
3993: @code{QImode}, @code{SImode}, @code{SFmode} and @code{DFmode}. The
3994: compiler will attempt to use @code{DImode} for two-word structures and
1.1.1.7 ! root 3995: unions, but this can be prevented by overriding the definition of
! 3996: @code{MAX_FIXED_MODE_SIZE}. Likewise, you can arrange for the C type
! 3997: @code{short int} to avoid using @code{HImode}. In the long term it
! 3998: might be desirable to make the set of available machine modes
! 3999: machine-dependent and eliminate all assumptions about specific machine
! 4000: modes or their uses from the machine-independent code of the compiler.
1.1 root 4001:
1.1.1.4 root 4002: To help begin this process, the machine modes are divided into mode
4003: classes. These are represented by the enumeration type @code{enum
4004: mode_class} defined in @file{rtl.h}. The possible mode classes are:
4005:
4006: @table @code
4007: @item MODE_INT
4008: Integer modes. By default these are @code{QImode}, @code{HImode},
4009: @code{SImode}, @code{DImode}, @code{TImode}, and also @code{BImode}.
4010:
4011: @item MODE_FLOAT
4012: Floating-point modes. By default these are @code{QFmode},
4013: @code{HFmode}, @code{SFmode}, @code{DFmode} and @code{TFmode}, but the
4014: MC68881 also defines @code{XFmode} to be an 80-bit extended-precision
4015: floating-point mode.
4016:
4017: @item MODE_COMPLEX_INT
4018: Complex integer modes. By default these are @code{CQImode},
4019: @code{CHImode}, @code{CSImode}, @code{CDImode} and @code{CTImode}.
4020:
4021: @item MODE_COMPLEX_FLOAT
4022: Complex floating-point modes. By default these are @code{CQFmode},
4023: @code{CHFmode}, @code{CSFmode}, @code{CDFmode} and @code{CTFmode},
4024:
4025: @item MODE_FUNCTION
4026: Algol or Pascal function variables including a static chain.
4027: (These are not currently implemented).
4028:
4029: @item MODE_RANDOM
4030: This is a catchall mode class for modes which don't fit into the above
4031: classes. Currently @code{VOIDmode}, @code{BLKmode} and @code{EPmode}
4032: are in @code{MODE_RANDOM}.
4033: @end table
4034:
1.1 root 4035: Here are some C macros that relate to machine modes:
4036:
4037: @table @code
4038: @item GET_MODE (@var{x})
4039: Returns the machine mode of the RTX @var{x}.
4040:
4041: @item PUT_MODE (@var{x}, @var{newmode})
4042: Alters the machine mode of the RTX @var{x} to be @var{newmode}.
4043:
1.1.1.4 root 4044: @item NUM_MACHINE_MODES
4045: Stands for the number of machine modes available on the target
4046: machine. This is one greater than the largest numeric value of any
4047: machine mode.
4048:
4049: @item GET_MODE_NAME (@var{m})
4050: Returns the name of mode @var{m} as a string.
4051:
4052: @item GET_MODE_CLASS (@var{m})
4053: Returns the mode class of mode @var{m}.
4054:
1.1 root 4055: @item GET_MODE_SIZE (@var{m})
4056: Returns the size in bytes of a datum of mode @var{m}.
4057:
4058: @item GET_MODE_BITSIZE (@var{m})
4059: Returns the size in bits of a datum of mode @var{m}.
4060:
4061: @item GET_MODE_UNIT_SIZE (@var{m})
4062: Returns the size in bits of the subunits of a datum of mode @var{m}.
4063: This is the same as @code{GET_MODE_SIZE} except in the case of
4064: complex modes and @code{EPmode}. For them, the unit size is the
4065: size of the real or imaginary part, or the size of the function
4066: pointer or the context pointer.
4067: @end table
4068:
4069: @node Constants, Regs and Memory, Machine Modes, RTL
4070: @section Constant Expression Types
4071:
4072: The simplest RTL expressions are those that represent constant values.
4073:
4074: @table @code
4075: @item (const_int @var{i})
4076: This type of expression represents the integer value @var{i}. @var{i}
4077: is customarily accessed with the macro @code{INTVAL} as in
4078: @code{INTVAL (@var{exp})}, which is equivalent to @code{XINT (@var{exp}, 0)}.
4079:
4080: There is only one expression object for the integer value zero;
4081: it is the value of the variable @code{const0_rtx}. Likewise, the
4082: only expression for integer value one is found in @code{const1_rtx}.
4083: Any attempt to create an expression of code @samp{const_int} and
4084: value zero or one will return @code{const0_rtx} or @code{const1_rtx}
4085: as appropriate.
4086:
4087: @item (const_double:@var{m} @var{i0} @var{i1})
1.1.1.6 root 4088: Represents a 64-bit constant of mode @var{m}. All floating point
1.1 root 4089: constants are represented in this way, and so are 64-bit @code{DImode}
4090: integer constants.
4091:
4092: The two integers @var{i0} and @var{i1} together contain the bits of
4093: the value. If the constant is floating point (either single or double
4094: precision), then they represent a @code{double}. To convert them to a
4095: @code{double}, do
4096:
4097: @example
4098: union @{ double d; int i[2];@} u;
4099: u.i[0] = XINT (x, 0);
4100: u.i[1] = XINT (x, 1);
4101: @end example
4102:
4103: @noindent
4104: and then refer to @code{u.d}.
4105:
4106: The global variables @code{dconst0_rtx} and @code{fconst0_rtx} hold
1.1.1.7 ! root 4107: @samp{const_double} expressions with value 0, in modes @code{DFmode}
! 4108: and @code{SFmode}, respectively. The macro @code{CONST0_RTX
! 4109: (@var{mode})} refers to a @samp{const_double} expression with value 0
! 4110: in mode @var{mode}. The mode @var{mode} must be of mode class
! 4111: @code{MODE_FLOAT}.
1.1 root 4112:
4113: @item (symbol_ref @var{symbol})
4114: Represents the value of an assembler label for data. @var{symbol} is
4115: a string that describes the name of the assembler label. If it starts
4116: with a @samp{*}, the label is the rest of @var{symbol} not including
4117: the @samp{*}. Otherwise, the label is @var{symbol}, prefixed with
4118: @samp{_}.
4119:
4120: @item (label_ref @var{label})
4121: Represents the value of an assembler label for code. It contains one
4122: operand, an expression, which must be a @samp{code_label} that appears
4123: in the instruction sequence to identify the place where the label
4124: should go.
4125:
4126: The reason for using a distinct expression type for code label
4127: references is so that jump optimization can distinguish them.
4128:
4129: @item (const @var{exp})
4130: Represents a constant that is the result of an assembly-time
4131: arithmetic computation. The operand, @var{exp}, is an expression that
4132: contains only constants (@samp{const_int}, @samp{symbol_ref} and
4133: @samp{label_ref} expressions) combined with @samp{plus} and
4134: @samp{minus}. However, not all combinations are valid, since the
4135: assembler cannot do arbitrary arithmetic on relocatable symbols.
4136: @end table
4137:
4138: @node Regs and Memory, Arithmetic, Constants, RTL
4139: @section Registers and Memory
4140:
4141: Here are the RTL expression types for describing access to machine
4142: registers and to main memory.
4143:
4144: @table @code
4145: @item (reg:@var{m} @var{n})
4146: For small values of the integer @var{n} (less than
4147: @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
4148: register number @var{n}: a @dfn{hard register}. For larger values of
4149: @var{n}, it stands for a temporary value or @dfn{pseudo register}.
4150: The compiler's strategy is to generate code assuming an unlimited
4151: number of such pseudo registers, and later convert them into hard
4152: registers or into memory references.
4153:
4154: The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
4155: description, since the number of hard registers on the machine is an
4156: invariant characteristic of the machine. Note, however, that not
4157: all of the machine registers must be general registers. All the
4158: machine registers that can be used for storage of data are given
4159: hard register numbers, even those that can be used only in certain
4160: instructions or can hold only certain types of data.
4161:
4162: Each pseudo register number used in a function's RTL code is
4163: represented by a unique @samp{reg} expression.
4164:
4165: @var{m} is the machine mode of the reference. It is necessary because
4166: machines can generally refer to each register in more than one mode.
4167: For example, a register may contain a full word but there may be
4168: instructions to refer to it as a half word or as a single byte, as
4169: well as instructions to refer to it as a floating point number of
4170: various precisions.
4171:
4172: Even for a register that the machine can access in only one mode,
4173: the mode must always be specified.
4174:
4175: A hard register may be accessed in various modes throughout one
4176: function, but each pseudo register is given a natural mode
4177: and is accessed only in that mode. When it is necessary to describe
4178: an access to a pseudo register using a nonnatural mode, a @samp{subreg}
4179: expression is used.
4180:
4181: A @samp{reg} expression with a machine mode that specifies more than
4182: one word of data may actually stand for several consecutive registers.
4183: If in addition the register number specifies a hardware register, then
4184: it actually represents several consecutive hardware registers starting
4185: with the specified one.
4186:
1.1.1.5 root 4187: Such multi-word hardware register @samp{reg} expressions must not be live
1.1 root 4188: across the boundary of a basic block. The lifetime analysis pass does not
4189: know how to record properly that several consecutive registers are
4190: actually live there, and therefore register allocation would be confused.
4191: The CSE pass must go out of its way to make sure the situation does
4192: not arise.
4193:
4194: @item (subreg:@var{m} @var{reg} @var{wordnum})
4195: @samp{subreg} expressions are used to refer to a register in a machine
4196: mode other than its natural one, or to refer to one register of
4197: a multi-word @samp{reg} that actually refers to several registers.
4198:
4199: Each pseudo-register has a natural mode. If it is necessary to
4200: operate on it in a different mode---for example, to perform a fullword
4201: move instruction on a pseudo-register that contains a single byte---
4202: the pseudo-register must be enclosed in a @samp{subreg}. In such
4203: a case, @var{wordnum} is zero.
4204:
4205: The other use of @samp{subreg} is to extract the individual registers
4206: of a multi-register value. Machine modes such as @code{DImode} and
4207: @code{EPmode} indicate values longer than a word, values which usually
4208: require two consecutive registers. To access one of the registers,
4209: use a @samp{subreg} with mode @code{SImode} and a @var{wordnum} that
4210: says which register.
4211:
4212: The compilation parameter @code{WORDS_BIG_ENDIAN}, if defined, says
4213: that word number zero is the most significant part; otherwise, it is
4214: the least significant part.
4215:
4216: Between the combiner pass and the reload pass, it is possible to have
4217: a @samp{subreg} which contains a @samp{mem} instead of a @samp{reg} as
4218: its first operand. The reload pass eliminates these cases by
4219: reloading the @samp{mem} into a suitable register.
4220:
4221: Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
4222: using a @samp{subreg}. On some machines the most significant part of a
4223: @code{DFmode} value does not have the same format as a single-precision
4224: floating value.
4225:
4226: @item (cc0)
4227: This refers to the machine's condition code register. It has no
4228: operands and may not have a machine mode. It may be validly used in
4229: only two contexts: as the destination of an assignment (in test and
4230: compare instructions) and in comparison operators comparing against
4231: zero (@samp{const_int} with value zero; that is to say,
4232: @code{const0_rtx}).
4233:
4234: There is only one expression object of code @samp{cc0}; it is the
4235: value of the variable @code{cc0_rtx}. Any attempt to create an
4236: expression of code @samp{cc0} will return @code{cc0_rtx}.
4237:
4238: One special thing about the condition code register is that
4239: instructions can set it implicitly. On many machines, nearly all
4240: instructions set the condition code based on the value that they
4241: compute or store. It is not necessary to record these actions
4242: explicitly in the RTL because the machine description includes a
4243: prescription for recognizing the instructions that do so (by means of
4244: the macro @code{NOTICE_UPDATE_CC}). Only instructions whose sole
4245: purpose is to set the condition code, and instructions that use the
4246: condition code, need mention @code{(cc0)}.
4247:
4248: @item (pc)
4249: This represents the machine's program counter. It has no operands and
4250: may not have a machine mode. @code{(pc)} may be validly used only in
4251: certain specific contexts in jump instructions.
4252:
4253: There is only one expression object of code @samp{pc}; it is the value
4254: of the variable @code{pc_rtx}. Any attempt to create an expression of
4255: code @samp{pc} will return @code{pc_rtx}.
4256:
4257: All instructions that do not jump alter the program counter implicitly
4258: by incrementing it, but there is no need to mention this in the RTL.
4259:
4260: @item (mem:@var{m} @var{addr})
4261: This RTX represents a reference to main memory at an address
4262: represented by the expression @var{addr}. @var{m} specifies how large
4263: a unit of memory is accessed.
4264: @end table
4265:
4266: @node Arithmetic, Comparisons, Regs and Memory, RTL
4267: @section RTL Expressions for Arithmetic
4268:
4269: @table @code
4270: @item (plus:@var{m} @var{x} @var{y})
4271: Represents the sum of the values represented by @var{x} and @var{y}
4272: carried out in machine mode @var{m}. This is valid only if
4273: @var{x} and @var{y} both are valid for mode @var{m}.
4274:
4275: @item (minus:@var{m} @var{x} @var{y})
4276: Like @samp{plus} but represents subtraction.
4277:
1.1.1.6 root 4278: @item (compare @var{x} @var{y})
1.1 root 4279: Represents the result of subtracting @var{y} from @var{x}
4280: for purposes of comparison. The absence of a machine mode
1.1.1.6 root 4281: in the @samp{compare} expression indicates that the result is
1.1 root 4282: computed without overflow, as if with infinite precision.
4283:
4284: Of course, machines can't really subtract with infinite precision.
4285: However, they can pretend to do so when only the sign of the
4286: result will be used, which is the case when the result is stored
4287: in @code{(cc0)}. And that is the only way this kind of expression
4288: may validly be used: as a value to be stored in the condition codes.
4289:
4290: @item (neg:@var{m} @var{x})
4291: Represents the negation (subtraction from zero) of the value
4292: represented by @var{x}, carried out in mode @var{m}. @var{x} must be
4293: valid for mode @var{m}.
4294:
4295: @item (mult:@var{m} @var{x} @var{y})
4296: Represents the signed product of the values represented by @var{x} and
4297: @var{y} carried out in machine mode @var{m}. If
4298: @var{x} and @var{y} are both valid for mode @var{m}, this is ordinary
4299: size-preserving multiplication. Alternatively, both @var{x} and @var{y}
4300: may be valid for a different, narrower mode. This represents the
4301: kind of multiplication that generates a product wider than the operands.
4302: Widening multiplication and same-size multiplication are completely
4303: distinct and supported by different machine instructions; machines may
4304: support one but not the other.@refill
4305:
1.1.1.5 root 4306: @samp{mult} may be used for floating point multiplication as well.
1.1 root 4307: Then @var{m} is a floating point machine mode.
4308:
4309: @item (umult:@var{m} @var{x} @var{y})
4310: Like @samp{mult} but represents unsigned multiplication. It may be
4311: used in both same-size and widening forms, like @samp{mult}.
4312: @samp{umult} is used only for fixed-point multiplication.
4313:
4314: @item (div:@var{m} @var{x} @var{y})
4315: Represents the quotient in signed division of @var{x} by @var{y},
4316: carried out in machine mode @var{m}. If @var{m} is a floating-point
4317: mode, it represents the exact quotient; otherwise, the integerized
4318: quotient. If @var{x} and @var{y} are both valid for mode @var{m},
4319: this is ordinary size-preserving division. Some machines have
4320: division instructions in which the operands and quotient widths are
4321: not all the same; such instructions are represented by @samp{div}
4322: expressions in which the machine modes are not all the same.
4323:
4324: @item (udiv:@var{m} @var{x} @var{y})
4325: Like @samp{div} but represents unsigned division.
4326:
4327: @item (mod:@var{m} @var{x} @var{y})
4328: @itemx (umod:@var{m} @var{x} @var{y})
4329: Like @samp{div} and @samp{udiv} but represent the remainder instead of
4330: the quotient.
4331:
4332: @item (not:@var{m} @var{x})
4333: Represents the bitwise complement of the value represented by @var{x},
4334: carried out in mode @var{m}, which must be a fixed-point machine mode.
4335: @var{x} must be valid for mode @var{m}, which must be a fixed-point mode.
4336:
4337: @item (and:@var{m} @var{x} @var{y})
4338: Represents the bitwise logical-and of the values represented by
4339: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
4340: valid only if @var{x} and @var{y} both are valid for mode @var{m},
4341: which must be a fixed-point mode.
4342:
4343: @item (ior:@var{m} @var{x} @var{y})
4344: Represents the bitwise inclusive-or of the values represented by
4345: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
4346: valid only if @var{x} and @var{y} both are valid for mode @var{m},
4347: which must be a fixed-point mode.
4348:
4349: @item (xor:@var{m} @var{x} @var{y})
4350: Represents the bitwise exclusive-or of the values represented by
4351: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
4352: valid only if @var{x} and @var{y} both are valid for mode @var{m},
4353: which must be a fixed-point mode.
4354:
4355: @item (lshift:@var{m} @var{x} @var{c})
4356: Represents the result of logically shifting @var{x} left by @var{c}
4357: places. @var{x} must be valid for the mode @var{m}, a fixed-point
4358: machine mode. @var{c} must be valid for a fixed-point mode;
4359: which mode is determined by the mode called for in the machine
4360: description entry for the left-shift instruction. For example,
4361: on the Vax, the mode of @var{c} is @code{QImode} regardless of @var{m}.
4362:
4363: On some machines, negative values of @var{c} may be meaningful; this
4364: is why logical left shift and arithmetic left shift are distinguished.
4365: For example, Vaxes have no right-shift instructions, and right shifts
4366: are represented as left-shift instructions whose counts happen
4367: to be negative constants or else computed (in a previous instruction)
4368: by negation.
4369:
4370: @item (ashift:@var{m} @var{x} @var{c})
4371: Like @samp{lshift} but for arithmetic left shift.
4372:
4373: @item (lshiftrt:@var{m} @var{x} @var{c})
4374: @itemx (ashiftrt:@var{m} @var{x} @var{c})
4375: Like @samp{lshift} and @samp{ashift} but for right shift.
4376:
4377: @item (rotate:@var{m} @var{x} @var{c})
4378: @itemx (rotatert:@var{m} @var{x} @var{c})
4379: Similar but represent left and right rotate.
4380:
4381: @item (abs:@var{m} @var{x})
4382: Represents the absolute value of @var{x}, computed in mode @var{m}.
4383: @var{x} must be valid for @var{m}.
4384:
4385: @item (sqrt:@var{m} @var{x})
4386: Represents the square root of @var{x}, computed in mode @var{m}.
4387: @var{x} must be valid for @var{m}. Most often @var{m} will be
4388: a floating point mode.
4389:
4390: @item (ffs:@var{m} @var{x})
4391: Represents the one plus the index of the least significant 1-bit in
4392: @var{x}, represented as an integer of mode @var{m}. (The value is
4393: zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
4394: depending on the target machine, various mode combinations may be
4395: valid.
4396: @end table
4397:
4398: @node Comparisons, Bit Fields, Arithmetic, RTL
4399: @section Comparison Operations
4400:
4401: Comparison operators test a relation on two operands and are considered to
4402: represent the value 1 if the relation holds, or zero if it does not. The
4403: mode of the comparison is determined by the operands; they must both be
4404: valid for a common machine mode. A comparison with both operands constant
4405: would be invalid as the machine mode could not be deduced from it, but such
4406: a comparison should never exist in RTL due to constant folding.
4407:
4408: Inequality comparisons come in two flavors, signed and unsigned. Thus,
4409: there are distinct expression codes @samp{gt} and @samp{gtu} for signed and
4410: unsigned greater-than. These can produce different results for the same
4411: pair of integer values: for example, 1 is signed greater-than -1 but not
4412: unsigned greater-than, because -1 when regarded as unsigned is actually
4413: @code{0xffffffff} which is greater than 1.
4414:
4415: The signed comparisons are also used for floating point values. Floating
4416: point comparisons are distinguished by the machine modes of the operands.
4417:
4418: The comparison operators may be used to compare the condition codes
4419: @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such a
4420: construct actually refers to the result of the preceding instruction in
4421: which the condition codes were set. The above example stands for 1 if the
4422: condition codes were set to say ``zero'' or ``equal'', 0 otherwise.
4423: Although the same comparison operators are used for this as may be used in
4424: other contexts on actual data, no confusion can result since the machine
4425: description would never allow both kinds of uses in the same context.
4426:
4427: @table @code
4428: @item (eq @var{x} @var{y})
4429: 1 if the values represented by @var{x} and @var{y} are equal,
4430: otherwise 0.
4431:
4432: @item (ne @var{x} @var{y})
4433: 1 if the values represented by @var{x} and @var{y} are not equal,
4434: otherwise 0.
4435:
4436: @item (gt @var{x} @var{y})
4437: 1 if the @var{x} is greater than @var{y}. If they are fixed-point,
4438: the comparison is done in a signed sense.
4439:
4440: @item (gtu @var{x} @var{y})
4441: Like @samp{gt} but does unsigned comparison, on fixed-point numbers only.
4442:
4443: @item (lt @var{x} @var{y})
4444: @item (ltu @var{x} @var{y})
4445: Like @samp{gt} and @samp{gtu} but test for ``less than''.
4446:
4447: @item (ge @var{x} @var{y})
4448: @item (geu @var{x} @var{y})
4449: Like @samp{gt} and @samp{gtu} but test for ``greater than or equal''.
4450:
4451: @item (le @var{x} @var{y})
4452: @item (leu @var{x} @var{y})
4453: Like @samp{gt} and @samp{gtu} but test for ``less than or equal''.
4454:
4455: @item (if_then_else @var{cond} @var{then} @var{else})
4456: This is not a comparison operation but is listed here because it is
4457: always used in conjunction with a comparison operation. To be
4458: precise, @var{cond} is a comparison expression. This expression
4459: represents a choice, according to @var{cond}, between the value
4460: represented by @var{then} and the one represented by @var{else}.
4461:
4462: On most machines, @samp{if_then_else} expressions are valid only
4463: to express conditional jumps.
4464: @end table
4465:
4466: @node Bit Fields, Conversions, Comparisons, RTL
4467: @section Bit-fields
4468:
4469: Special expression codes exist to represent bit-field instructions.
4470: These types of expressions are lvalues in RTL; they may appear
4471: on the left side of a assignment, indicating insertion of a value
4472: into the specified bit field.
4473:
4474: @table @code
4475: @item (sign_extract:SI @var{loc} @var{size} @var{pos})
4476: This represents a reference to a sign-extended bit-field contained or
4477: starting in @var{loc} (a memory or register reference). The bit field
4478: is @var{size} bits wide and starts at bit @var{pos}. The compilation
4479: option @code{BITS_BIG_ENDIAN} says which end of the memory unit
4480: @var{pos} counts from.
4481:
4482: Which machine modes are valid for @var{loc} depends on the machine,
4483: but typically @var{loc} should be a single byte when in memory
4484: or a full word in a register.
4485:
4486: @item (zero_extract:SI @var{loc} @var{size} @var{pos})
4487: Like @samp{sign_extract} but refers to an unsigned or zero-extended
4488: bit field. The same sequence of bits are extracted, but they
4489: are filled to an entire word with zeros instead of by sign-extension.
4490: @end table
4491:
4492: @node Conversions, RTL Declarations, Bit Fields, RTL
4493: @section Conversions
4494:
4495: All conversions between machine modes must be represented by
4496: explicit conversion operations. For example, an expression
4497: which is the sum of a byte and a full word cannot be written as
4498: @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @samp{plus}
4499: operation requires two operands of the same machine mode.
4500: Therefore, the byte-sized operand is enclosed in a conversion
4501: operation, as in
4502:
4503: @example
4504: (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
4505: @end example
4506:
4507: The conversion operation is not a mere placeholder, because there
4508: may be more than one way of converting from a given starting mode
4509: to the desired final mode. The conversion operation code says how
4510: to do it.
4511:
4512: @table @code
4513: @item (sign_extend:@var{m} @var{x})
4514: Represents the result of sign-extending the value @var{x}
4515: to machine mode @var{m}. @var{m} must be a fixed-point mode
4516: and @var{x} a fixed-point value of a mode narrower than @var{m}.
4517:
4518: @item (zero_extend:@var{m} @var{x})
4519: Represents the result of zero-extending the value @var{x}
4520: to machine mode @var{m}. @var{m} must be a fixed-point mode
4521: and @var{x} a fixed-point value of a mode narrower than @var{m}.
4522:
4523: @item (float_extend:@var{m} @var{x})
4524: Represents the result of extending the value @var{x}
4525: to machine mode @var{m}. @var{m} must be a floating point mode
4526: and @var{x} a floating point value of a mode narrower than @var{m}.
4527:
4528: @item (truncate:@var{m} @var{x})
4529: Represents the result of truncating the value @var{x}
4530: to machine mode @var{m}. @var{m} must be a fixed-point mode
4531: and @var{x} a fixed-point value of a mode wider than @var{m}.
4532:
4533: @item (float_truncate:@var{m} @var{x})
4534: Represents the result of truncating the value @var{x}
4535: to machine mode @var{m}. @var{m} must be a floating point mode
4536: and @var{x} a floating point value of a mode wider than @var{m}.
4537:
4538: @item (float:@var{m} @var{x})
4539: Represents the result of converting fixed point value @var{x},
4540: regarded as signed, to floating point mode @var{m}.
4541:
4542: @item (unsigned_float:@var{m} @var{x})
4543: Represents the result of converting fixed point value @var{x},
4544: regarded as unsigned, to floating point mode @var{m}.
4545:
4546: @item (fix:@var{m} @var{x})
4547: When @var{m} is a fixed point mode, represents the result of
4548: converting floating point value @var{x} to mode @var{m}, regarded as
4549: signed. How rounding is done is not specified, so this operation may
4550: be used validly in compiling C code only for integer-valued operands.
4551:
4552: @item (unsigned_fix:@var{m} @var{x})
4553: Represents the result of converting floating point value @var{x} to
4554: fixed point mode @var{m}, regarded as unsigned. How rounding is done
4555: is not specified.
4556:
4557: @item (fix:@var{m} @var{x})
4558: When @var{m} is a floating point mode, represents the result of
4559: converting floating point value @var{x} (valid for mode @var{m}) to an
4560: integer, still represented in floating point mode @var{m}, by rounding
4561: towards zero.
4562: @end table
4563:
4564: @node RTL Declarations, Side Effects, Conversions, RTL
4565: @section Declarations
4566:
4567: Declaration expression codes do not represent arithmetic operations
4568: but rather state assertions about their operands.
4569:
4570: @table @code
4571: @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
4572: This expression code is used in only one context: operand 0 of a
4573: @samp{set} expression. In addition, the operand of this expression
4574: must be a @samp{subreg} expression.
4575:
4576: The presence of @samp{strict_low_part} says that the part of the
4577: register which is meaningful in mode @var{n}, but is not part of
4578: mode @var{m}, is not to be altered. Normally, an assignment to such
4579: a subreg is allowed to have undefined effects on the rest of the
4580: register when @var{m} is less than a word.
4581: @end table
4582:
4583: @node Side Effects, Incdec, RTL Declarations, RTL
4584: @section Side Effect Expressions
4585:
4586: The expression codes described so far represent values, not actions.
4587: But machine instructions never produce values; they are meaningful
4588: only for their side effects on the state of the machine. Special
4589: expression codes are used to represent side effects.
4590:
4591: The body of an instruction is always one of these side effect codes;
4592: the codes described above, which represent values, appear only as
4593: the operands of these.
4594:
4595: @table @code
4596: @item (set @var{lval} @var{x})
4597: Represents the action of storing the value of @var{x} into the place
4598: represented by @var{lval}. @var{lval} must be an expression
4599: representing a place that can be stored in: @samp{reg} (or
4600: @samp{subreg} or @samp{strict_low_part}), @samp{mem}, @samp{pc} or
4601: @samp{cc0}.@refill
4602:
4603: If @var{lval} is a @samp{reg}, @samp{subreg} or @samp{mem}, it has a
4604: machine mode; then @var{x} must be valid for that mode.@refill
4605:
4606: If @var{lval} is a @samp{reg} whose machine mode is less than the full
4607: width of the register, then it means that the part of the register
4608: specified by the machine mode is given the specified value and the
4609: rest of the register receives an undefined value. Likewise, if
4610: @var{lval} is a @samp{subreg} whose machine mode is narrower than
4611: @code{SImode}, the rest of the register can be changed in an undefined way.
4612:
4613: If @var{lval} is a @samp{strict_low_part} of a @samp{subreg}, then the
4614: part of the register specified by the machine mode of the
4615: @samp{subreg} is given the value @var{x} and the rest of the register
4616: is not changed.@refill
4617:
4618: If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
4619: have any mode. This represents a ``test'' or ``compare'' instruction.@refill
4620:
4621: If @var{lval} is @code{(pc)}, we have a jump instruction, and the
4622: possibilities for @var{x} are very limited. It may be a
4623: @samp{label_ref} expression (unconditional jump). It may be an
4624: @samp{if_then_else} (conditional jump), in which case either the
4625: second or the third operand must be @code{(pc)} (for the case which
4626: does not jump) and the other of the two must be a @samp{label_ref}
4627: (for the case which does jump). @var{x} may also be a @samp{mem} or
4628: @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @samp{reg} or a
4629: @samp{mem}; these unusual patterns are used to represent jumps through
4630: branch tables.@refill
4631:
4632: @item (return)
4633: Represents a return from the current function, on machines where this
4634: can be done with one instruction, such as Vaxes. On machines where a
4635: multi-instruction ``epilogue'' must be executed in order to return
4636: from the function, returning is done by jumping to a label which
4637: precedes the epilogue, and the @samp{return} expression code is never
4638: used.
4639:
4640: @item (call @var{function} @var{nargs})
4641: Represents a function call. @var{function} is a @samp{mem} expression
4642: whose address is the address of the function to be called.
4643: @var{nargs} is an expression which can be used for two purposes: on
4644: some machines it represents the number of bytes of stack argument; on
4645: others, it represents the number of argument registers.
4646:
4647: Each machine has a standard machine mode which @var{function} must
4648: have. The machine description defines macro @code{FUNCTION_MODE} to
4649: expand into the requisite mode name. The purpose of this mode is to
4650: specify what kind of addressing is allowed, on machines where the
4651: allowed kinds of addressing depend on the machine mode being
4652: addressed.
4653:
4654: @item (clobber @var{x})
4655: Represents the storing or possible storing of an unpredictable,
4656: undescribed value into @var{x}, which must be a @samp{reg} or
4657: @samp{mem} expression.
4658:
4659: One place this is used is in string instructions that store standard
4660: values into particular hard registers. It may not be worth the
4661: trouble to describe the values that are stored, but it is essential to
4662: inform the compiler that the registers will be altered, lest it
4663: attempt to keep data in them across the string instruction.
4664:
4665: @var{x} may also be null---a null C pointer, no expression at all.
4666: Such a @code{(clobber (null))} expression means that all memory
4667: locations must be presumed clobbered.
4668:
4669: Note that the machine description classifies certain hard registers as
4670: ``call-clobbered''. All function call instructions are assumed by
4671: default to clobber these registers, so there is no need to use
4672: @samp{clobber} expressions to indicate this fact. Also, each function
1.1.1.6 root 4673: call is assumed to have the potential to alter any memory location,
4674: unless the function is declared @code{const}.
1.1 root 4675:
1.1.1.4 root 4676: When a @samp{clobber} expression for a register appears inside a
4677: @samp{parallel} with other side effects, GNU CC guarantees that the
4678: register is unoccupied both before and after that insn. Therefore, it
4679: is safe for the assembler code produced by the insn to use the
4680: register as a temporary. You can clobber either a specific hard
4681: register or a pseudo register; in the latter case, GNU CC will
4682: allocate a hard register that is available there for use as a
4683: temporary.
4684:
1.1 root 4685: @item (use @var{x})
4686: Represents the use of the value of @var{x}. It indicates that the
4687: value in @var{x} at this point in the program is needed, even though
4688: it may not be apparent why this is so. Therefore, the compiler will
1.1.1.4 root 4689: not attempt to delete previous instructions whose only effect is to
4690: store a value in @var{x}. @var{x} must be a @samp{reg} expression.
1.1 root 4691:
4692: @item (parallel [@var{x0} @var{x1} @dots{}])
4693: Represents several side effects performed in parallel. The square
4694: brackets stand for a vector; the operand of @samp{parallel} is a
4695: vector of expressions. @var{x0}, @var{x1} and so on are individual
1.1.1.4 root 4696: side effect expressions---expressions of code @samp{set}, @samp{call},
1.1 root 4697: @samp{return}, @samp{clobber} or @samp{use}.@refill
4698:
4699: ``In parallel'' means that first all the values used in the individual
4700: side-effects are computed, and second all the actual side-effects are
4701: performed. For example,
4702:
4703: @example
4704: (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
4705: (set (mem:SI (reg:SI 1)) (reg:SI 1))])
4706: @end example
4707:
4708: @noindent
4709: says unambiguously that the values of hard register 1 and the memory
4710: location addressed by it are interchanged. In both places where
4711: @code{(reg:SI 1)} appears as a memory address it refers to the value
1.1.1.4 root 4712: in register 1 @emph{before} the execution of the insn.
4713:
4714: It follows that it is @emph{incorrect} to use @samp{parallel} and
4715: expect the result of one @samp{set} to be available for the next one.
4716: For example, people sometimes attempt to represent a jump-if-zero
4717: instruction this way:
4718:
4719: @example
4720: (parallel [(set (cc0) (reg:SI 34))
4721: (set (pc) (if_then_else
4722: (eq (cc0) (const_int 0))
4723: (label_ref @dots{})
4724: (pc)))])
4725: @end example
4726:
4727: @noindent
4728: But this is incorrect, because it says that the jump condition depends
4729: on the condition code value @emph{before} this instruction, not on the
4730: new value that is set by this instruction.
1.1 root 4731:
1.1.1.5 root 4732: Peephole optimization, which takes place in together with final assembly
4733: code output, can produce insns whose patterns consist of a @samp{parallel}
1.1 root 4734: whose elements are the operands needed to output the resulting
4735: assembler code--often @samp{reg}, @samp{mem} or constant expressions.
4736: This would not be well-formed RTL at any other stage in compilation,
4737: but it is ok then because no further optimization remains to be done.
1.1.1.4 root 4738: However, the definition of the macro @code{NOTICE_UPDATE_CC} must
4739: deal with such insns if you define any peephole optimizations.
1.1 root 4740:
4741: @item (sequence [@var{insns} @dots{}])
4742: Represents a sequence of insns. Each of the @var{insns} that appears
4743: in the vector is suitable for appearing in the chain of insns, so it
4744: must be an @samp{insn}, @samp{jump_insn}, @samp{call_insn},
4745: @samp{code_label}, @samp{barrier} or @samp{note}.
4746:
4747: A @samp{sequence} RTX never appears in an actual insn. It represents
4748: the sequence of insns that result from a @samp{define_expand}
4749: @emph{before} those insns are passed to @code{emit_insn} to insert
4750: them in the chain of insns. When actually inserted, the individual
4751: sub-insns are separated out and the @samp{sequence} is forgotten.
4752: @end table
4753:
4754: Three expression codes appear in place of a side effect, as the body of an
4755: insn, though strictly speaking they do not describe side effects as such:
4756:
4757: @table @code
4758: @item (asm_input @var{s})
4759: Represents literal assembler code as described by the string @var{s}.
4760:
4761: @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
4762: Represents a table of jump addresses. The vector elements @var{lr0},
4763: etc., are @samp{label_ref} expressions. The mode @var{m} specifies
4764: how much space is given to each address; normally @var{m} would be
4765: @code{Pmode}.
4766:
4767: @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
4768: Represents a table of jump addresses expressed as offsets from
4769: @var{base}. The vector elements @var{lr0}, etc., are @samp{label_ref}
4770: expressions and so is @var{base}. The mode @var{m} specifies how much
4771: space is given to each address-difference.@refill
4772: @end table
4773:
4774: @node Incdec, Assembler, Side Effects, RTL
4775: @section Embedded Side-Effects on Addresses
4776:
4777: Four special side-effect expression codes appear as memory addresses.
4778:
4779: @table @code
4780: @item (pre_dec:@var{m} @var{x})
4781: Represents the side effect of decrementing @var{x} by a standard
4782: amount and represents also the value that @var{x} has after being
4783: decremented. @var{x} must be a @samp{reg} or @samp{mem}, but most
4784: machines allow only a @samp{reg}. @var{m} must be the machine mode
4785: for pointers on the machine in use. The amount @var{x} is decremented
4786: by is the length in bytes of the machine mode of the containing memory
4787: reference of which this expression serves as the address. Here is an
4788: example of its use:@refill
4789:
4790: @example
4791: (mem:DF (pre_dec:SI (reg:SI 39)))
4792: @end example
4793:
4794: @noindent
4795: This says to decrement pseudo register 39 by the length of a @code{DFmode}
4796: value and use the result to address a @code{DFmode} value.
4797:
4798: @item (pre_inc:@var{m} @var{x})
4799: Similar, but specifies incrementing @var{x} instead of decrementing it.
4800:
4801: @item (post_dec:@var{m} @var{x})
4802: Represents the same side effect as @samp{pre_decrement} but a different
4803: value. The value represented here is the value @var{x} has @i{before}
4804: being decremented.
4805:
4806: @item (post_inc:@var{m} @var{x})
4807: Similar, but specifies incrementing @var{x} instead of decrementing it.
4808: @end table
4809:
4810: These embedded side effect expressions must be used with care. Instruction
4811: patterns may not use them. Until the @samp{flow} pass of the compiler,
4812: they may occur only to represent pushes onto the stack. The @samp{flow}
4813: pass finds cases where registers are incremented or decremented in one
4814: instruction and used as an address shortly before or after; these cases are
4815: then transformed to use pre- or post-increment or -decrement.
4816:
4817: Explicit popping of the stack could be represented with these embedded
4818: side effect operators, but that would not be safe; the instruction
4819: combination pass could move the popping past pushes, thus changing
4820: the meaning of the code.
4821:
4822: An instruction that can be represented with an embedded side effect
4823: could also be represented using @samp{parallel} containing an additional
4824: @samp{set} to describe how the address register is altered. This is not
4825: done because machines that allow these operations at all typically
4826: allow them wherever a memory address is called for. Describing them as
4827: additional parallel stores would require doubling the number of entries
4828: in the machine description.
4829:
4830: @node Assembler, Insns, IncDec, RTL
4831: @section Assembler Instructions as Expressions
4832:
4833: The RTX code @samp{asm_operands} represents a value produced by a
4834: user-specified assembler instruction. It is used to represent
4835: an @code{asm} statement with arguments. An @code{asm} statement with
4836: a single output operand, like this:
4837:
4838: @example
1.1.1.6 root 4839: asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
1.1 root 4840: @end example
4841:
4842: @noindent
4843: is represented using a single @samp{asm_operands} RTX which represents
4844: the value that is stored in @code{outputvar}:
4845:
4846: @example
4847: (set @var{rtx-for-outputvar}
4848: (asm_operands "foo %1,%2,%0" "a" 0
4849: [@var{rtx-for-addition-result} @var{rtx-for-*z}]
4850: [(asm_input:@var{m1} "g")
4851: (asm_input:@var{m2} "di")]))
4852: @end example
4853:
4854: @noindent
4855: Here the operands of the @samp{asm_operands} RTX are the assembler
4856: template string, the output-operand's constraint, the index-number of the
4857: output operand among the output operands specified, a vector of input
4858: operand RTX's, and a vector of input-operand modes and constraints. The
4859: mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
4860: @code{*z}.
4861:
4862: When an @code{asm} statement has multiple output values, its insn has
4863: several such @samp{set} RTX's inside of a @samp{parallel}. Each @samp{set}
4864: contains a @samp{asm_operands}; all of these share the same assembler
4865: template and vectors, but each contains the constraint for the respective
4866: output operand. They are also distinguished by the output-operand index
4867: number, which is 0, 1, @dots{} for successive output operands.
4868:
4869: @node Insns, Calls, Assembler, RTL
4870: @section Insns
4871:
4872: The RTL representation of the code for a function is a doubly-linked
4873: chain of objects called @dfn{insns}. Insns are expressions with
4874: special codes that are used for no other purpose. Some insns are
4875: actual instructions; others represent dispatch tables for @code{switch}
4876: statements; others represent labels to jump to or various sorts of
4877: declarative information.
4878:
4879: In addition to its own specific data, each insn must have a unique id-number
4880: that distinguishes it from all other insns in the current function, and
4881: chain pointers to the preceding and following insns. These three fields
4882: occupy the same position in every insn, independent of the expression code
4883: of the insn. They could be accessed with @code{XEXP} and @code{XINT},
4884: but instead three special macros are always used:
4885:
4886: @table @code
4887: @item INSN_UID (@var{i})
4888: Accesses the unique id of insn @var{i}.
4889:
4890: @item PREV_INSN (@var{i})
4891: Accesses the chain pointer to the insn preceding @var{i}.
4892: If @var{i} is the first insn, this is a null pointer.
4893:
4894: @item NEXT_INSN (@var{i})
4895: Accesses the chain pointer to the insn following @var{i}.
4896: If @var{i} is the last insn, this is a null pointer.
4897: @end table
4898:
4899: The @code{NEXT_INSN} and @code{PREV_INSN} pointers must always
1.1.1.6 root 4900: correspond: if @var{insn} is not the first insn,
1.1 root 4901:
4902: @example
4903: NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
4904: @end example
4905:
4906: @noindent
4907: is always true.
4908:
4909: Every insn has one of the following six expression codes:
4910:
4911: @table @samp
4912: @item insn
4913: The expression code @samp{insn} is used for instructions that do not jump
4914: and do not do function calls. Insns with code @samp{insn} have four
4915: additional fields beyond the three mandatory ones listed above.
4916: These four are described in a table below.
4917:
4918: @item jump_insn
4919: The expression code @samp{jump_insn} is used for instructions that may jump
4920: (or, more generally, may contain @samp{label_ref} expressions).
4921: @samp{jump_insn} insns have the same extra fields as @samp{insn} insns,
4922: accessed in the same way.
4923:
4924: @item call_insn
4925: The expression code @samp{call_insn} is used for instructions that may do
4926: function calls. It is important to distinguish these instructions because
4927: they imply that certain registers and memory locations may be altered
4928: unpredictably.
4929:
4930: @samp{call_insn} insns have the same extra fields as @samp{insn} insns,
4931: accessed in the same way.
4932:
4933: @item code_label
4934: A @samp{code_label} insn represents a label that a jump insn can jump to.
4935: It contains one special field of data in addition to the three standard ones.
4936: It is used to hold the @dfn{label number}, a number that identifies this
4937: label uniquely among all the labels in the compilation (not just in the
4938: current function). Ultimately, the label is represented in the assembler
4939: output as an assembler label @samp{L@var{n}} where @var{n} is the label number.
4940:
4941: @item barrier
4942: Barriers are placed in the instruction stream after unconditional
4943: jump instructions to indicate that the jumps are unconditional.
4944: They contain no information beyond the three standard fields.
4945:
4946: @item note
4947: @samp{note} insns are used to represent additional debugging and
4948: declarative information. They contain two nonstandard fields, an
4949: integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
4950: string accessed with @code{NOTE_SOURCE_FILE}.
4951:
4952: If @code{NOTE_LINE_NUMBER} is positive, the note represents the
4953: position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
4954: that the line came from. These notes control generation of line
4955: number data in the assembler output.
4956:
4957: Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
4958: code with one of the following values (and @code{NOTE_SOURCE_FILE}
4959: must contain a null pointer):
4960:
4961: @table @code
4962: @item NOTE_INSN_DELETED
4963: Such a note is completely ignorable. Some passes of the compiler
4964: delete insns by altering them into notes of this kind.
4965:
4966: @item NOTE_INSN_BLOCK_BEG
4967: @itemx NOTE_INSN_BLOCK_END
4968: These types of notes indicate the position of the beginning and end
4969: of a level of scoping of variable names. They control the output
4970: of debugging information.
4971:
4972: @item NOTE_INSN_LOOP_BEG
4973: @itemx NOTE_INSN_LOOP_END
4974: These types of notes indicate the position of the beginning and end
4975: of a @code{while} or @code{for} loop. They enable the loop optimizer
4976: to find loops quickly.
1.1.1.6 root 4977: @item NOTE_INSN_FUNCTION_END
4978: Appears near the end of the function body, just before the label that
4979: @code{return} statements jump to (on machine where a single instruction
4980: does not suffice for returning). This note may be deleted by jump
4981: optimization.
4982: @item NOTE_INSN_SETJMP
4983: Appears following each call to @code{setjmp} or a related function.
1.1.1.7 ! root 4984:
! 4985: @item NOTE_INSN_LOOP_BEG
! 4986: Appears at the place in a loop that @code{continue} statements jump to.
1.1 root 4987: @end table
1.1.1.7 ! root 4988:
! 4989: These codes are printed symbolically when they appear in debugging dumps.
1.1 root 4990: @end table
4991:
1.1.1.6 root 4992: The machine mode of an insn is normally zero (@code{VOIDmode}), but the
4993: reload pass sets it to @code{QImode} if the insn needs reloading.
4994:
1.1 root 4995: Here is a table of the extra fields of @samp{insn}, @samp{jump_insn}
4996: and @samp{call_insn} insns:
4997:
4998: @table @code
4999: @item PATTERN (@var{i})
5000: An expression for the side effect performed by this insn.
5001:
1.1.1.6 root 5002: @item INSN_CODE (@var{i})
5003: An integer that says which pattern in the machine description matches
5004: this insn, or -1 if the matching has not yet been attempted.
5005:
5006: Such matching is never attempted and this field is not used on an insn
5007: whose pattern consists of a single @samp{use}, @samp{clobber},
5008: @samp{asm}, @samp{addr_vec} or @samp{addr_diff_vec} expression.
1.1 root 5009:
5010: @item LOG_LINKS (@var{i})
5011: A list (chain of @samp{insn_list} expressions) of previous ``related''
5012: insns: insns which store into registers values that are used for the
5013: first time in this insn. (An additional constraint is that neither a
5014: jump nor a label may come between the related insns). This list is
5015: set up by the flow analysis pass; it is a null pointer until then.
5016:
1.1.1.6 root 5017: @item REG_NOTES (@var{i})
5018: A list (chain of @samp{expr_list} expressions) giving information
5019: about the usage of registers in this insn. This list is set up by the
5020: flow analysis pass; it is a null pointer until then.
1.1 root 5021: @end table
5022:
5023: The @code{LOG_LINKS} field of an insn is a chain of @samp{insn_list}
5024: expressions. Each of these has two operands: the first is an insn,
5025: and the second is another @samp{insn_list} expression (the next one in
5026: the chain). The last @samp{insn_list} in the chain has a null pointer
5027: as second operand. The significant thing about the chain is which
5028: insns appear in it (as first operands of @samp{insn_list}
5029: expressions). Their order is not significant.
5030:
5031: The @code{REG_NOTES} field of an insn is a similar chain but of
1.1.1.5 root 5032: @samp{expr_list} expressions instead of @samp{insn_list}. There are
5033: several kinds of register notes, which are distinguished by the machine
5034: mode of the @samp{expr_list}, which in a register note is really
5035: understood as being an @code{enum reg_note}. The first operand @var{op}
5036: of the @samp{expr_list} is data whose meaning depends on the kind of
5037: note. Here are the kinds of register note:
1.1 root 5038:
5039: @table @code
5040: @item REG_DEAD
5041: The register @var{op} dies in this insn; that is to say, altering the
5042: value immediately after this insn would not affect the future behavior
5043: of the program.
5044:
5045: @item REG_INC
5046: The register @var{op} is incremented (or decremented; at this level
5047: there is no distinction) by an embedded side effect inside this insn.
5048: This means it appears in a @code{POST_INC}, @code{PRE_INC},
5049: @code{POST_DEC} or @code{PRE_DEC} RTX.
5050:
5051: @item REG_EQUIV
5052: The register that is set by this insn will be equal to @var{op} at run
5053: time, and could validly be replaced in all its occurrences by
5054: @var{op}. (``Validly'' here refers to the data flow of the program;
5055: simple replacement may make some insns invalid.)
5056:
5057: The value which the insn explicitly copies into the register may look
5058: different from @var{op}, but they will be equal at run time.
5059:
5060: For example, when a constant is loaded into a register that is never
5061: assigned any other value, this kind of note is used.
5062:
5063: When a parameter is copied into a pseudo-register at entry to a function,
5064: a note of this kind records that the register is equivalent to the stack
5065: slot where the parameter was passed. Although in this case the register
5066: may be set by other insns, it is still valid to replace the register
5067: by the stack slot throughout the function.
5068:
5069: @item REG_EQUAL
5070: The register that is set by this insn will be equal to @var{op} at run
5071: time at the end of this insn (but not necessarily elsewhere in the
5072: function).
5073:
5074: The RTX @var{op} is typically an arithmetic expression. For example,
5075: when a sequence of insns such as a library call is used to perform an
5076: arithmetic operation, this kind of note is attached to the insn that
5077: produces or copies the final value. It tells the CSE pass how to
5078: think of that value.
5079:
5080: @item REG_RETVAL
5081: This insn copies the value of a library call, and @var{op} is the
5082: first insn that was generated to set up the arguments for the library
5083: call.
5084:
5085: Flow analysis uses this note to delete all of a library call whose
5086: result is dead.
5087:
5088: @item REG_WAS_0
5089: The register @var{op} contained zero before this insn. You can rely
5090: on this note if it is present; its absence implies nothing.
5091:
5092: @item REG_LIBCALL
5093: This is the inverse of @code{REG_RETVAL}: it is placed on the first
5094: insn of a library call, and it points to the last one.
5095:
5096: Loop optimization uses this note to move an entire library call out
5097: of a loop when its value is constant.
5098:
5099: @item REG_NONNEG
5100: The register @var{op} is known to have nonnegative value when this
5101: insn is reached.
5102: @end table
5103:
1.1.1.7 ! root 5104: For convenience, the machine mode in an @samp{insn_list} or
! 5105: @samp{expr_list} is printed using these symbolic codes in debugging dumps.
! 5106:
! 5107: The only difference between the expression codes @samp{insn_list} and
1.1 root 5108: @samp{expr_list} is that the first operand of an @samp{insn_list} is
5109: assumed to be an insn and is printed in debugging dumps as the insn's
5110: unique id; the first operand of an @samp{expr_list} is printed in the
1.1.1.7 ! root 5111: ordinary way as an expression.
1.1 root 5112:
5113: @node Calls, Sharing, Insns, RTL
5114: @section RTL Representation of Function-Call Insns
5115:
5116: Insns that call subroutines have the RTL expression code @samp{call_insn}.
5117: These insns must satisfy special rules, and their bodies must use a special
5118: RTL expression code, @samp{call}.
5119:
5120: A @samp{call} expression has two operands, as follows:
5121:
5122: @example
1.1.1.6 root 5123: (call (mem:@var{fm} @var{addr}) @var{nbytes})
1.1 root 5124: @end example
5125:
5126: @noindent
5127: Here @var{nbytes} is an operand that represents the number of bytes of
5128: argument data being passed to the subroutine, @var{fm} is a machine mode
5129: (which must equal as the definition of the @code{FUNCTION_MODE} macro in
5130: the machine description) and @var{addr} represents the address of the
5131: subroutine.
5132:
5133: For a subroutine that returns no value, the @samp{call} RTX as shown above
5134: is the entire body of the insn.
5135:
5136: For a subroutine that returns a value whose mode is not @code{BLKmode},
5137: the value is returned in a hard register. If this register's number is
5138: @var{r}, then the body of the call insn looks like this:
5139:
5140: @example
5141: (set (reg:@var{m} @var{r})
5142: (call @var{nbytes} (mem:@var{fm} @var{addr})))
5143: @end example
5144:
5145: @noindent
5146: This RTL expression makes it clear (to the optimizer passes) that the
5147: appropriate register receives a useful value in this insn.
5148:
5149: Immediately after RTL generation, if the value of the subroutine is
5150: actually used, this call insn is always followed closely by an insn which
5151: refers to the register @var{r}. This remains true through all the
5152: optimizer passes until cross jumping occurs.
5153:
5154: The following insn has one of two forms. Either it copies the value into a
5155: pseudo-register, like this:
5156:
5157: @example
5158: (set (reg:@var{m} @var{p}) (reg:@var{m} @var{r}))
5159: @end example
5160:
5161: @noindent
5162: or (in the case where the calling function will simply return whatever
5163: value the call produced, and no operation is needed to do this):
5164:
5165: @example
5166: (use (reg:@var{m} @var{r}))
5167: @end example
5168:
5169: @noindent
5170: Between the call insn and this following insn there may intervene only a
5171: stack-adjustment insn (and perhaps some @samp{note} insns).
5172:
5173: When a subroutine returns a @code{BLKmode} value, it is handled by
5174: passing to the subroutine the address of a place to store the value.
5175: So the call insn itself does not ``return'' any value, and it has the
5176: same RTL form as a call that returns nothing.
5177:
5178: @node Sharing,, Calls, RTL
5179: @section Structure Sharing Assumptions
5180:
5181: The compiler assumes that certain kinds of RTL expressions are unique;
5182: there do not exist two distinct objects representing the same value.
5183: In other cases, it makes an opposite assumption: that no RTL expression
5184: object of a certain kind appears in more than one place in the
5185: containing structure.
5186:
5187: These assumptions refer to a single function; except for the RTL
5188: objects that describe global variables and external functions,
5189: no RTL objects are common to two functions.
5190:
5191: @itemize @bullet
5192: @item
5193: Each pseudo-register has only a single @samp{reg} object to represent it,
5194: and therefore only a single machine mode.
5195:
5196: @item
5197: For any symbolic label, there is only one @samp{symbol_ref} object
5198: referring to it.
5199:
5200: @item
5201: There is only one @samp{const_int} expression with value zero,
5202: and only one with value one.
5203:
5204: @item
5205: There is only one @samp{pc} expression.
5206:
5207: @item
5208: There is only one @samp{cc0} expression.
5209:
5210: @item
5211: There is only one @samp{const_double} expression with mode
5212: @code{SFmode} and value zero, and only one with mode @code{DFmode} and
5213: value zero.
5214:
5215: @item
5216: No @samp{label_ref} appears in more than one place in the RTL
5217: structure; in other words, it is safe to do a tree-walk of all the
5218: insns in the function and assume that each time a @samp{label_ref} is
5219: seen it is distinct from all others that are seen.
5220:
5221: @item
5222: Only one @samp{mem} object is normally created for each static
5223: variable or stack slot, so these objects are frequently shared in all
5224: the places they appear. However, separate but equal objects for these
5225: variables are occasionally made.
5226:
5227: @item
1.1.1.5 root 5228: When a single @code{asm} statement has multiple output operands,
5229: a distinct @code{asm_operands} RTX is made for each output operand.
5230: However, these all share the vector which contains the sequence of
5231: input operands. Because this sharing is used later on to test whether
5232: two @code{asm_operands} RTX's come from the same statement, the sharing
5233: must be guaranteed to be preserved.
5234:
5235: @item
1.1 root 5236: No RTL object appears in more than one place in the RTL structure
5237: except as described above. Many passes of the compiler rely on this
5238: by assuming that they can modify RTL objects in place without unwanted
5239: side-effects on other insns.
5240:
5241: @item
5242: During initial RTL generation, shared structure is freely introduced.
5243: After all the RTL for a function has been generated, all shared
5244: structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
5245: after which the above rules are guaranteed to be followed.
5246:
5247: @item
5248: During the combiner pass, shared structure with an insn can exist
5249: temporarily. However, the shared structure is copied before the
5250: combiner is finished with the insn. This is done by
5251: @code{copy_substitutions} in @samp{combine.c}.
5252: @end itemize
5253:
5254: @node Machine Desc, Machine Macros, RTL, Top
5255: @chapter Machine Descriptions
5256:
5257: A machine description has two parts: a file of instruction patterns
5258: (@file{.md} file) and a C header file of macro definitions.
5259:
5260: The @file{.md} file for a target machine contains a pattern for each
5261: instruction that the target machine supports (or at least each instruction
5262: that is worth telling the compiler about). It may also contain comments.
5263: A semicolon causes the rest of the line to be a comment, unless the semicolon
5264: is inside a quoted string.
5265:
5266: See the next chapter for information on the C header file.
5267:
5268: @menu
5269: * Patterns:: How to write instruction patterns.
5270: * Example:: An explained example of a @samp{define_insn} pattern.
5271: * RTL Template:: The RTL template defines what insns match a pattern.
5272: * Output Template:: The output template says how to make assembler code
5273: from such an insn.
5274: * Output Statement:: For more generality, write C code to output
5275: the assembler code.
5276: * Constraints:: When not all operands are general operands.
5277: * Standard Names:: Names mark patterns to use for code generation.
5278: * Pattern Ordering:: When the order of patterns makes a difference.
5279: * Dependent Patterns:: Having one pattern may make you need another.
5280: * Jump Patterns:: Special considerations for patterns for jump insns.
5281: * Peephole Definitions::Defining machine-specific peephole optimizations.
5282: * Expander Definitions::Generating a sequence of several RTL insns
5283: for a standard operation.
5284: @end menu
5285:
5286: @node Patterns, Example, Machine Desc, Machine Desc
5287: @section Everything about Instruction Patterns
5288:
5289: Each instruction pattern contains an incomplete RTL expression, with pieces
5290: to be filled in later, operand constraints that restrict how the pieces can
5291: be filled in, and an output pattern or C code to generate the assembler
5292: output, all wrapped up in a @samp{define_insn} expression.
5293:
5294: A @samp{define_insn} is an RTL expression containing four or five operands:
5295:
5296: @enumerate
5297: @item
5298: An optional name. The presence of a name indicate that this instruction
5299: pattern can perform a certain standard job for the RTL-generation
5300: pass of the compiler. This pass knows certain names and will use
5301: the instruction patterns with those names, if the names are defined
5302: in the machine description.
5303:
5304: The absence of a name is indicated by writing an empty string
5305: where the name should go. Nameless instruction patterns are never
5306: used for generating RTL code, but they may permit several simpler insns
5307: to be combined later on.
5308:
5309: Names that are not thus known and used in RTL-generation have no
5310: effect; they are equivalent to no name at all.
5311:
5312: @item
5313: The @dfn{RTL template} (@pxref{RTL Template}) is a vector of
5314: incomplete RTL expressions which show what the instruction should look
5315: like. It is incomplete because it may contain @samp{match_operand}
5316: and @samp{match_dup} expressions that stand for operands of the
5317: instruction.
5318:
5319: If the vector has only one element, that element is what the
5320: instruction should look like. If the vector has multiple elements,
5321: then the instruction looks like a @samp{parallel} expression
5322: containing that many elements as described.
5323:
5324: @item
5325: A condition. This is a string which contains a C expression that is
5326: the final test to decide whether an insn body matches this pattern.
5327:
5328: For a named pattern, the condition (if present) may not depend on
5329: the data in the insn being matched, but only the target-machine-type
5330: flags. The compiler needs to test these conditions during
5331: initialization in order to learn exactly which named instructions are
5332: available in a particular run.
5333:
5334: For nameless patterns, the condition is applied only when matching an
5335: individual insn, and only after the insn has matched the pattern's
5336: recognition template. The insn's operands may be found in the vector
5337: @code{operands}.
5338:
5339: @item
5340: The @dfn{output template}: a string that says how to output matching
5341: insns as assembler code. @samp{%} in this string specifies where
5342: to substitute the value of an operand. @xref{Output Template}.
5343:
5344: When simple substitution isn't general enough, you can specify a piece
5345: of C code to compute the output. @xref{Output Statement}.
5346:
5347: @item
5348: Optionally, some @dfn{machine-specific information}. The meaning
5349: of this information is defined only by an individual machine description;
5350: typically it might say whether this insn alters the condition codes,
5351: or how many bytes of output it generates.
5352:
5353: This operand is written as a string containing a C initializer
5354: (complete with braces) for the structure type @code{INSN_MACHINE_INFO},
5355: whose definition is up to you (@pxref{Misc}).
5356: @end enumerate
5357:
5358: @node Example, RTL Template, Patterns, Machine Desc
5359: @section Example of @samp{define_insn}
5360:
5361: Here is an actual example of an instruction pattern, for the 68000/68020.
5362:
5363: @example
5364: (define_insn "tstsi"
5365: [(set (cc0)
5366: (match_operand:SI 0 "general_operand" "rm"))]
5367: ""
5368: "*
5369: @{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
5370: return \"tstl %0\";
5371: return \"cmpl #0,%0\"; @}")
5372: @end example
5373:
5374: This is an instruction that sets the condition codes based on the value of
5375: a general operand. It has no condition, so any insn whose RTL description
5376: has the form shown may be handled according to this pattern. The name
5377: @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
5378: pass that, when it is necessary to test such a value, an insn to do so
5379: can be constructed using this pattern.
5380:
5381: The output control string is a piece of C code which chooses which
5382: output template to return based on the kind of operand and the specific
5383: type of CPU for which code is being generated.
5384:
5385: @samp{"rm"} is an operand constraint. Its meaning is explained below.
5386:
5387: @node RTL Template, Output Template, Example, Machine Desc
5388: @section RTL Template for Generating and Recognizing Insns
5389:
5390: The RTL template is used to define which insns match the particular pattern
5391: and how to find their operands. For named patterns, the RTL template also
5392: says how to construct an insn from specified operands.
5393:
5394: Construction involves substituting specified operands into a copy of the
5395: template. Matching involves determining the values that serve as the
5396: operands in the insn being matched. Both of these activities are
5397: controlled by special expression types that direct matching and
5398: substitution of the operands.
5399:
5400: @table @code
5401: @item (match_operand:@var{m} @var{n} @var{testfn} @var{constraint})
5402: This expression is a placeholder for operand number @var{n} of
5403: the insn. When constructing an insn, operand number @var{n}
5404: will be substituted at this point. When matching an insn, whatever
5405: appears at this position in the insn will be taken as operand
5406: number @var{n}; but it must satisfy @var{testfn} or this instruction
5407: pattern will not match at all.
5408:
5409: Operand numbers must be chosen consecutively counting from zero in
5410: each instruction pattern. There may be only one @samp{match_operand}
5411: expression in the pattern for each operand number. Usually operands
5412: are numbered in the order of appearance in @samp{match_operand}
5413: expressions.
5414:
5415: @var{testfn} is a string that is the name of a C function that accepts
5416: two arguments, a machine mode and an expression. During matching,
5417: the function will be called with @var{m} as the mode argument
5418: and the putative operand as the other argument. If it returns zero,
5419: this instruction pattern fails to match. @var{testfn} may be
5420: an empty string; then it means no test is to be done on the operand.
5421:
5422: @var{constraint} is explained later (@pxref{Constraints}).
5423:
5424: Most often, @var{testfn} is @code{"general_operand"}. It checks
5425: that the putative operand is either a constant, a register or a
5426: memory reference, and that it is valid for mode @var{m}.
5427:
5428: For an operand that must be a register, @var{testfn} should be
5429: @code{"register_operand"}. It would be valid to use
5430: @code{"general_operand"}, since the reload pass would copy any
5431: non-register operands through registers, but this would make GNU CC do
5432: extra work, and it would prevent the register allocator from doing the
5433: best possible job.
5434:
5435: For an operand that must be a constant, either @var{testfn} should be
5436: @code{"immediate_operand"}, or the instruction pattern's extra
5437: condition should check for constants, or both. You cannot expect the
5438: constraints to do this work! If the constraints allow only constants,
5439: but the predicate allows something else, the compiler will crash when
5440: that case arises.
5441:
5442: @item (match_dup @var{n})
5443: This expression is also a placeholder for operand number @var{n}.
5444: It is used when the operand needs to appear more than once in the
5445: insn.
5446:
5447: In construction, @samp{match_dup} behaves exactly like
5448: @samp{match_operand}: the operand is substituted into the insn being
5449: constructed. But in matching, @samp{match_dup} behaves differently.
5450: It assumes that operand number @var{n} has already been determined by
5451: a @samp{match_operand} appearing earlier in the recognition template,
5452: and it matches only an identical-looking expression.
5453:
1.1.1.4 root 5454: @item (match_operator:@var{m} @var{n} "@var{predicate}" [@var{operands}@dots{}])
5455: This pattern is a kind of placeholder for a variable RTL expression
5456: code.
5457:
5458: When constructing an insn, it stands for an RTL expression whose
5459: expression code is taken from that of operand @var{n}, and whose
5460: operands are constructed from the patterns @var{operands}.
5461:
5462: When matching an expression, it matches an expression if the function
5463: @var{predicate} returns nonzero on that expression @emph{and} the
5464: patterns @var{operands} match the operands of the expression.
5465:
5466: Suppose that the function @code{commutative_operator} is defined as
5467: follows, to match any expression whose operator is one of the six
5468: commutative arithmetic operators of RTL and whose mode is @var{mode}:
5469:
5470: @example
5471: int
5472: commutative_operator (x, mode)
5473: rtx x;
5474: enum machine_mode mode;
5475: @{
5476: enum rtx_code code = GET_CODE (x);
5477: if (GET_MODE (x) != mode)
5478: return 0;
5479: return (code == PLUS || code == MULT || code == UMULT
5480: || code == AND || code == IOR || code == XOR);
5481: @}
5482: @end example
5483:
5484: Then the following pattern will match any RTL expression consisting
5485: of a commutative operator applied to two general operands:
5486:
5487: @example
5488: (match_operator:SI 2 "commutative_operator"
5489: [(match_operand:SI 3 "general_operand" "g")
5490: (match_operand:SI 4 "general_operand" "g")])
5491: @end example
5492:
5493: Here the vector @code{[@var{operands}@dots{}]} contains two patterns
5494: because the expressions to be matched all contain two operands.
5495:
5496: When this pattern does match, the two operands of the commutative
5497: operator are recorded as operands 3 and 4 of the insn. (This is done
1.1.1.5 root 5498: by the two instances of @samp{match_operand}.) Operand 2 of the insn
1.1.1.4 root 5499: will be the entire commutative expression: use @code{GET_CODE
5500: (operands[2])} to see which commutative operator was used.
5501:
5502: The machine mode @var{m} of @samp{match_operator} works like that of
5503: @samp{match_operand}: it is passed as the second argument to the
5504: predicate function, and that function is solely responsible for
5505: deciding whether the expression to be matched ``has'' that mode.
5506:
5507: When constructing an insn, argument 2 of the gen-function will specify
5508: the operation (i.e. the expression code) for the expression to be
5509: made. It should be an RTL expression, whose expression code is copied
5510: into a new expression whose operands are arguments 3 and 4 of the
5511: gen-function. The subexpressions of argument 2 are not used;
5512: only its expression code matters.
5513:
5514: There is no way to specify constraints in @samp{match_operator}. The
5515: operand of the insn which corresponds to the @samp{match_operator}
5516: never has any constraints because it is never reloaded as a whole.
5517: However, if parts of its @var{operands} are matched by
5518: @samp{match_operand} patterns, those parts may have constraints of
5519: their own.
5520:
1.1 root 5521: @item (address (match_operand:@var{m} @var{n} "address_operand" ""))
5522: This complex of expressions is a placeholder for an operand number
5523: @var{n} in a ``load address'' instruction: an operand which specifies
5524: a memory location in the usual way, but for which the actual operand
5525: value used is the address of the location, not the contents of the
5526: location.
5527:
5528: @samp{address} expressions never appear in RTL code, only in machine
5529: descriptions. And they are used only in machine descriptions that do
5530: not use the operand constraint feature. When operand constraints are
5531: in use, the letter @samp{p} in the constraint serves this purpose.
5532:
5533: @var{m} is the machine mode of the @emph{memory location being
5534: addressed}, not the machine mode of the address itself. That mode is
5535: always the same on a given target machine (it is @code{Pmode}, which
5536: normally is @code{SImode}), so there is no point in mentioning it;
5537: thus, no machine mode is written in the @samp{address} expression. If
5538: some day support is added for machines in which addresses of different
5539: kinds of objects appear differently or are used differently (such as
5540: the PDP-10), different formats would perhaps need different machine
5541: modes and these modes might be written in the @samp{address}
5542: expression.
5543: @end table
5544:
5545: @node Output Template, Output Statement, RTL Template, Machine Desc
5546: @section Output Templates and Operand Substitution
5547:
1.1.1.6 root 5548: The @dfn{output template} is a string which specifies how to output the
5549: assembler code for an instruction pattern. Most of the template is a
5550: fixed string which is output literally. The character @samp{%} is used
5551: to specify where to substitute an operand; it can also be used to
5552: identify places where different variants of the assembler require
1.1 root 5553: different syntax.
5554:
5555: In the simplest case, a @samp{%} followed by a digit @var{n} says to output
5556: operand @var{n} at that point in the string.
5557:
5558: @samp{%} followed by a letter and a digit says to output an operand in an
5559: alternate fashion. Four letters have standard, built-in meanings described
5560: below. The machine description macro @code{PRINT_OPERAND} can define
5561: additional letters with nonstandard meanings.
5562:
5563: @samp{%c@var{digit}} can be used to substitute an operand that is a
5564: constant value without the syntax that normally indicates an immediate
5565: operand.
5566:
5567: @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
5568: the constant is negated before printing.
5569:
5570: @samp{%a@var{digit}} can be used to substitute an operand as if it were a
5571: memory reference, with the actual operand treated as the address. This may
5572: be useful when outputting a ``load address'' instruction, because often the
5573: assembler syntax for such an instruction requires you to write the operand
5574: as if it were a memory reference.
5575:
5576: @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
5577: instruction.
5578:
5579: @samp{%} followed by a punctuation character specifies a substitution that
5580: does not use an operand. Only one case is standard: @samp{%%} outputs a
5581: @samp{%} into the assembler code. Other nonstandard cases can be
5582: defined in the @code{PRINT_OPERAND} macro.
5583:
5584: The template may generate multiple assembler instructions. Write the text
5585: for the instructions, with @samp{\;} between them.
5586:
1.1.1.6 root 5587: When the RTL contains two operands which are required by constraint to match
1.1 root 5588: each other, the output template must refer only to the lower-numbered operand.
5589: Matching operands are not always identical, and the rest of the compiler
5590: arranges to put the proper RTL expression for printing into the lower-numbered
5591: operand.
5592:
5593: One use of nonstandard letters or punctuation following @samp{%} is to
5594: distinguish between different assembler languages for the same machine; for
5595: example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax
5596: requires periods in most opcode names, while MIT syntax does not. For
5597: example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
5598: syntax. The same file of patterns is used for both kinds of output syntax,
5599: but the character sequence @samp{%.} is used in each place where Motorola
5600: syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax
5601: defines the sequence to output a period; the macro for MIT syntax defines
5602: it to do nothing.
5603:
5604: @node Output Statement, Constraints, Output Template, Machine Desc
5605: @section C Statements for Generating Assembler Output
5606:
5607: Often a single fixed template string cannot produce correct and efficient
5608: assembler code for all the cases that are recognized by a single
5609: instruction pattern. For example, the opcodes may depend on the kinds of
5610: operands; or some unfortunate combinations of operands may require extra
5611: machine instructions.
5612:
5613: If the output control string starts with a @samp{*}, then it is not an
5614: output template but rather a piece of C program that should compute a
5615: template. It should execute a @code{return} statement to return the
5616: template-string you want. Most such templates use C string literals, which
5617: require doublequote characters to delimit them. To include these
5618: doublequote characters in the string, prefix each one with @samp{\}.
5619:
5620: The operands may be found in the array @code{operands}, whose C data type
5621: is @code{rtx []}.
5622:
5623: It is possible to output an assembler instruction and then go on to output
5624: or compute more of them, using the subroutine @code{output_asm_insn}. This
5625: receives two arguments: a template-string and a vector of operands. The
5626: vector may be @code{operands}, or it may be another array of @code{rtx}
5627: that you declare locally and initialize yourself.
5628:
5629: When an insn pattern has multiple alternatives in its constraints, often
1.1.1.5 root 5630: the appearance of the assembler code is determined mostly by which alternative
1.1 root 5631: was matched. When this is so, the C code can test the variable
5632: @code{which_alternative}, which is the ordinal number of the alternative
5633: that was actually satisfied (0 for the first, 1 for the second alternative,
5634: etc.).
5635:
5636: For example, suppose there are two opcodes for storing zero, @samp{clrreg}
5637: for registers and @samp{clrmem} for memory locations. Here is how
5638: a pattern could use @code{which_alternative} to choose between them:
5639:
5640: @example
5641: (define_insn ""
5642: [(set (match_operand:SI 0 "general_operand" "r,m")
5643: (const_int 0))]
5644: ""
5645: "*
5646: return (which_alternative == 0
5647: ? \"clrreg %0\" : \"clrmem %0\");
5648: ")
5649: @end example
5650:
5651: @node Constraints, Standard Names, Output Statement, Machine Desc
5652: @section Operand Constraints
5653:
5654: Each @samp{match_operand} in an instruction pattern can specify a
5655: constraint for the type of operands allowed. Constraints can say whether
5656: an operand may be in a register, and which kinds of register; whether the
5657: operand can be a memory reference, and which kinds of address; whether the
5658: operand may be an immediate constant, and which possible values it may
5659: have. Constraints can also require two operands to match.
5660:
5661: @menu
5662: * Simple Constraints:: Basic use of constraints.
5663: * Multi-Alternative:: When an insn has two alternative constraint-patterns.
5664: * Class Preferences:: Constraints guide which hard register to put things in.
5665: * Modifiers:: More precise control over effects of constraints.
5666: * No Constraints:: Describing a clean machine without constraints.
5667: @end menu
5668:
5669: @node Simple Constraints, Multi-Alternative, Constraints, Constraints
5670: @subsection Simple Constraints
5671:
5672: The simplest kind of constraint is a string full of letters, each of
5673: which describes one kind of operand that is permitted. Here are
5674: the letters that are allowed:
5675:
5676: @table @asis
5677: @item @samp{m}
5678: A memory operand is allowed, with any kind of address that the machine
5679: supports in general.
5680:
5681: @item @samp{o}
5682: A memory operand is allowed, but only if the address is
5683: @dfn{offsetable}. This means that adding a small integer (actually,
5684: the width in bytes of the operand, as determined by its machine mode)
5685: may be added to the address and the result is also a valid memory
5686: address.
5687:
5688: For example, an address which is constant is offsetable; so is an
5689: address that is the sum of a register and a constant (as long as a
5690: slightly larger constant is also within the range of address-offsets
5691: supported by the machine); but an autoincrement or autodecrement
5692: address is not offsetable. More complicated indirect/indexed
5693: addresses may or may not be offsetable depending on the other
5694: addressing modes that the machine supports.
5695:
5696: Note that in an output operand which can be matched by another
5697: operand, the constraint letter @samp{o} is valid only when accompanied
5698: by both @samp{<} (if the target machine has predecrement addressing)
5699: and @samp{>} (if the target machine has preincrement addressing).
5700:
5701: When the constraint letter @samp{o} is used, the reload pass may
5702: generate instructions which copy a nonoffsetable address into an index
5703: register. The idea is that the register can be used as a replacement
5704: offsetable address. But this method requires that there be patterns
5705: to copy any kind of address into a register. Auto-increment
5706: and auto-decrement addresses are an exception; there need not be an
5707: instruction that can copy such an address into a register, because
5708: reload handles these cases specially.
5709:
5710: Most older machine designs have ``load address'' instructions which do
5711: just what is needed here. Some RISC machines do not advertise such
5712: instructions, but the possible addresses on these machines are very
5713: limited, so it is easy to fake them.
5714:
5715: @item @samp{<}
5716: A memory operand with autodecrement addressing (either predecrement or
5717: postdecrement) is allowed.
5718:
5719: @item @samp{>}
5720: A memory operand with autoincrement addressing (either preincrement or
5721: postincrement) is allowed.
5722:
5723: @item @samp{r}
5724: A register operand is allowed provided that it is in a general
5725: register.
5726:
5727: @item @samp{d}, @samp{a}, @samp{f}, @dots{}
5728: Other letters can be defined in machine-dependent fashion to stand for
5729: particular classes of registers. @samp{d}, @samp{a} and @samp{f} are
5730: defined on the 68000/68020 to stand for data, address and floating
5731: point registers.
5732:
5733: @item @samp{i}
5734: An immediate integer operand (one with constant value) is allowed.
5735: This includes symbolic constants whose values will be known only at
5736: assembly time.
5737:
5738: @item @samp{n}
5739: An immediate integer operand with a known numeric value is allowed.
5740: Many systems cannot support assembly-time constants for operands less
5741: than a word wide. Constraints for these operands should use @samp{n}
5742: rather than @samp{i}.
5743:
5744: @item @samp{I}, @samp{J}, @samp{K}, @dots{}
5745: Other letters in the range @samp{I} through @samp{M} may be defined in
5746: a machine-dependent fashion to permit immediate integer operands with
5747: explicit integer values in specified ranges. For example, on the
5748: 68000, @samp{I} is defined to stand for the range of values 1 to 8.
5749: This is the range permitted as a shift count in the shift
5750: instructions.
5751:
5752: @item @samp{F}
5753: An immediate floating operand (expression code @samp{const_double}) is
5754: allowed.
5755:
5756: @item @samp{G}, @samp{H}
5757: @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
5758: permit immediate floating operands in particular ranges of values.
5759:
5760: @item @samp{s}
5761: An immediate integer operand whose value is not an explicit integer is
5762: allowed.
5763:
5764: This might appear strange; if an insn allows a constant operand with a
5765: value not known at compile time, it certainly must allow any known
5766: value. So why use @samp{s} instead of @samp{i}? Sometimes it allows
5767: better code to be generated.
5768:
5769: For example, on the 68000 in a fullword instruction it is possible to
5770: use an immediate operand; but if the immediate value is between -32
5771: and 31, better code results from loading the value into a register and
5772: using the register. This is because the load into the register can be
5773: done with a @samp{moveq} instruction. We arrange for this to happen
5774: by defining the letter @samp{K} to mean ``any integer outside the
5775: range -32 to 31'', and then specifying @samp{Ks} in the operand
5776: constraints.
5777:
5778: @item @samp{g}
5779: Any register, memory or immediate integer operand is allowed, except for
5780: registers that are not general registers.
5781:
5782: @item @samp{@var{n}} (a digit)
5783: An operand that matches operand number @var{n} is allowed.
5784: If a digit is used together with letters, the digit should come last.
5785:
5786: This is called a @dfn{matching constraint} and what it really means is
5787: that the assembler has only a single operand that fills two roles
5788: considered separate in the RTL insn. For example, an add insn has two
5789: input operands and one output operand in the RTL, but on most machines
5790: an add instruction really has only two operands, one of them an
5791: input-output operand.
5792:
5793: Matching constraints work only in circumstances like that add insn.
5794: More precisely, the matching constraint must appear in an input-only
5795: operand and the operand that it matches must be an output-only operand
1.1.1.5 root 5796: with a lower number. Thus, operand @var{n} must have @samp{=} in its
5797: constraint.
1.1 root 5798:
5799: For operands to match in a particular case usually means that they
5800: are identical-looking RTL expressions. But in a few special cases
5801: specific kinds of dissimilarity are allowed. For example, @code{*x}
5802: as an input operand will match @code{*x++} as an output operand.
5803: For proper results in such cases, the output template should always
5804: use the output-operand's number when printing the operand.
5805:
5806: @item @samp{p}
5807: An operand that is a valid memory address is allowed. This is
5808: for ``load address'' and ``push address'' instructions.
5809:
5810: If @samp{p} is used in the constraint, the test-function in the
5811: @samp{match_operand} must be @code{address_operand}.
5812: @end table
5813:
5814: In order to have valid assembler code, each operand must satisfy
5815: its constraint. But a failure to do so does not prevent the pattern
5816: from applying to an insn. Instead, it directs the compiler to modify
5817: the code so that the constraint will be satisfied. Usually this is
5818: done by copying an operand into a register.
5819:
5820: Contrast, therefore, the two instruction patterns that follow:
5821:
5822: @example
5823: (define_insn ""
5824: [(set (match_operand:SI 0 "general_operand" "r")
5825: (plus:SI (match_dup 0)
5826: (match_operand:SI 1 "general_operand" "r")))]
5827: ""
5828: "@dots{}")
5829: @end example
5830:
5831: @noindent
5832: which has two operands, one of which must appear in two places, and
5833:
5834: @example
5835: (define_insn ""
5836: [(set (match_operand:SI 0 "general_operand" "r")
5837: (plus:SI (match_operand:SI 1 "general_operand" "0")
5838: (match_operand:SI 2 "general_operand" "r")))]
5839: ""
5840: "@dots{}")
5841: @end example
5842:
5843: @noindent
5844: which has three operands, two of which are required by a constraint to be
5845: identical. If we are considering an insn of the form
5846:
5847: @example
5848: (insn @var{n} @var{prev} @var{next}
5849: (set (reg:SI 3)
5850: (plus:SI (reg:SI 6) (reg:SI 109)))
5851: @dots{})
5852: @end example
5853:
5854: @noindent
5855: the first pattern would not apply at all, because this insn does not
5856: contain two identical subexpressions in the right place. The pattern would
5857: say, ``That does not look like an add instruction; try other patterns.''
5858: The second pattern would say, ``Yes, that's an add instruction, but there
5859: is something wrong with it.'' It would direct the reload pass of the
5860: compiler to generate additional insns to make the constraint true. The
5861: results might look like this:
5862:
5863: @example
5864: (insn @var{n2} @var{prev} @var{n}
5865: (set (reg:SI 3) (reg:SI 6))
5866: @dots{})
5867:
5868: (insn @var{n} @var{n2} @var{next}
5869: (set (reg:SI 3)
5870: (plus:SI (reg:SI 3) (reg:SI 109)))
5871: @dots{})
5872: @end example
5873:
5874: It is up to you to make sure that each operand, in each pattern, has
5875: constraints that can handle any RTL expression that could be present for
5876: that operand. (When multiple alternatives are in use, each pattern must,
5877: for each possible combination of operand expressions, have at least one
5878: alternative which can handle that combination of operands.) The
5879: constraints don't need to @emph{allow} any possible operand---when this is
5880: the case, they do not constrain---but they must at least point the way to
5881: reloading any possible operand so that it will fit.
5882:
5883: @itemize @bullet
5884: @item
5885: If the constraint accepts whatever operands the predicate permits,
5886: there is no problem: reloading is never necessary for this operand.
5887:
5888: For example, an operand whose constraints permit everything except
5889: registers is safe provided its predicate rejects registers.
5890:
5891: An operand whose predicate accepts only constant values is safe
5892: provided its constraints include the letter @samp{i}. If any possible
5893: constant value is accepted, then nothing less than @samp{i} will do;
1.1.1.5 root 5894: if the predicate is more selective, then the constraints may also be
1.1 root 5895: more selective.
5896:
5897: @item
5898: Any operand expression can be reloaded by copying it into a register.
5899: So if an operand's constraints allow some kind of register, it is
5900: certain to be safe. It need not permit all classes of registers; the
5901: compiler knows how to copy a register into another register of the
5902: proper class in order to make an instruction valid.
5903:
5904: @item
5905: A nonoffsetable memory reference can be reloaded by copying the
5906: address into a register. So if the constraint uses the letter
5907: @samp{o}, all memory references are taken care of.
5908:
5909: @item
5910: A constant operand can be reloaded by storing it in memory; it then
5911: becomes an offsetable memory reference. So if the constraint uses the
5912: letters @samp{o} or @samp{m}, constant operands are not a problem.
5913: @end itemize
5914:
5915: If the operand's predicate can recognize registers, but the constraint does
5916: not permit them, it can make the compiler crash. When this operand happens
5917: to be a register, the reload pass will be stymied, because it does not know
5918: how to copy a register temporarily into memory.
5919:
5920: @node Multi-Alternative, Class Preferences, Simple Constraints, Constraints
5921: @subsection Multiple Alternative Constraints
5922:
5923: Sometimes a single instruction has multiple alternative sets of possible
5924: operands. For example, on the 68000, a logical-or instruction can combine
5925: register or an immediate value into memory, or it can combine any kind of
5926: operand into a register; but it cannot combine one memory location into
5927: another.
5928:
5929: These constraints are represented as multiple alternatives. An alternative
5930: can be described by a series of letters for each operand. The overall
5931: constraint for an operand is made from the letters for this operand
5932: from the first alternative, a comma, the letters for this operand from
5933: the second alternative, a comma, and so on until the last alternative.
5934: Here is how it is done for fullword logical-or on the 68000:
5935:
5936: @example
5937: (define_insn "iorsi3"
5938: [(set (match_operand:SI 0 "general_operand" "=%m,d")
5939: (ior:SI (match_operand:SI 1 "general_operand" "0,0")
5940: (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
5941: @dots{})
5942: @end example
5943:
5944: The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
5945: operand 1 (meaning it must match operand 0), and @samp{dKs} for operand 2.
5946: The second alternative has @samp{d} (data register) for operand 0, @samp{0}
5947: for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and @samp{%} in
5948: the constraint for operand 0 are not part of any alternative; their meaning
5949: is explained in the next section.
5950:
5951: If all the operands fit any one alternative, the instruction is valid.
5952: Otherwise, for each alternative, the compiler counts how many instructions
5953: must be added to copy the operands so that that alternative applies.
5954: The alternative requiring the least copying is chosen. If two alternatives
5955: need the same amount of copying, the one that comes first is chosen.
5956: These choices can be altered with the @samp{?} and @samp{!} characters:
5957:
5958: @table @samp
5959: @item ?
5960: Disparage slightly the alternative that the @samp{?} appears in,
5961: as a choice when no alternative applies exactly. The compiler regards
5962: this alternative as one unit more costly for each @samp{?} that appears
5963: in it.
5964:
5965: @item !
5966: Disparage severely the alternative that the @samp{!} appears in.
5967: When operands must be copied into registers, the compiler will
5968: never choose this alternative as the one to strive for.
5969: @end table
5970:
1.1.1.5 root 5971: When an insn pattern has multiple alternatives in its constraints, often
5972: the appearance of the assembler code is determined mostly by which
1.1 root 5973: alternative was matched. When this is so, the C code for writing the
5974: assembler code can use the variable @code{which_alternative}, which is
1.1.1.5 root 5975: the ordinal number of the alternative that was actually satisfied (0 for
5976: the first, 1 for the second alternative, etc.). For example:
1.1 root 5977:
5978: @example
5979: (define_insn ""
5980: [(set (match_operand:SI 0 "general_operand" "r,m")
5981: (const_int 0))]
5982: ""
5983: "*
5984: return (which_alternative == 0
5985: ? \"clrreg %0\" : \"clrmem %0\");
5986: ")
5987: @end example
5988:
5989: @node Class Preferences, Modifiers, Multi-Alternative, Constraints
5990: @subsection Register Class Preferences
5991:
5992: The operand constraints have another function: they enable the compiler
5993: to decide which kind of hardware register a pseudo register is best
5994: allocated to. The compiler examines the constraints that apply to the
5995: insns that use the pseudo register, looking for the machine-dependent
5996: letters such as @samp{d} and @samp{a} that specify classes of registers.
5997: The pseudo register is put in whichever class gets the most ``votes''.
5998: The constraint letters @samp{g} and @samp{r} also vote: they vote in
5999: favor of a general register. The machine description says which registers
6000: are considered general.
6001:
6002: Of course, on some machines all registers are equivalent, and no register
6003: classes are defined. Then none of this complexity is relevant.
6004:
6005: @node Modifiers, No Constraints, Class Preferences, Constraints
6006: @subsection Constraint Modifier Characters
6007:
6008: @table @samp
6009: @item =
6010: Means that this operand is write-only for this instruction: the previous
6011: value is discarded and replaced by output data.
6012:
6013: @item +
6014: Means that this operand is both read and written by the instruction.
6015:
6016: When the compiler fixes up the operands to satisfy the constraints,
6017: it needs to know which operands are inputs to the instruction and
6018: which are outputs from it. @samp{=} identifies an output; @samp{+}
6019: identifies an operand that is both input and output; all other operands
6020: are assumed to be input only.
6021:
6022: @item &
6023: Means (in a particular alternative) that this operand is written
6024: before the instruction is finished using the input operands.
6025: Therefore, this operand may not lie in a register that is used as an
6026: input operand or as part of any memory address.
6027:
6028: @samp{&} applies only to the alternative in which it is written. In
6029: constraints with multiple alternatives, sometimes one alternative
6030: requires @samp{&} while others do not. See, for example, the
6031: @samp{movdf} insn of the 68000.
6032:
6033: @samp{&} does not obviate the need to write @samp{=}.
6034:
6035: @item %
6036: Declares the instruction to be commutative for this operand and the
6037: following operand. This means that the compiler may interchange the
6038: two operands if that is the cheapest way to make all operands fit the
6039: constraints. This is often used in patterns for addition instructions
6040: that really have only two operands: the result must go in one of the
6041: arguments. Here for example, is how the 68000 halfword-add
6042: instruction is defined:
6043:
6044: @example
6045: (define_insn "addhi3"
6046: [(set (match_operand:HI 0 "general_operand" "=m,r")
6047: (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
6048: (match_operand:HI 2 "general_operand" "di,g")))]
6049: @dots{})
6050: @end example
6051:
6052: Note that in previous versions of GNU CC the @samp{%} constraint
6053: modifier always applied to operands 1 and 2 regardless of which
6054: operand it was written in. The usual custom was to write it in
6055: operand 0. Now it must be in operand 1 if the operands to be
6056: exchanged are 1 and 2.
6057:
6058: @item #
6059: Says that all following characters, up to the next comma, are to be
6060: ignored as a constraint. They are significant only for choosing
6061: register preferences.
6062:
6063: @item *
6064: Says that the following character should be ignored when choosing
6065: register preferences. @samp{*} has no effect on the meaning of the
6066: constraint as a constraint.
6067:
6068: Here is an example: the 68000 has an instruction to sign-extend a
6069: halfword in a data register, and can also sign-extend a value by
6070: copying it into an address register. While either kind of register is
6071: acceptable, the constraints on an address-register destination are
6072: less strict, so it is best if register allocation makes an address
6073: register its goal. Therefore, @samp{*} is used so that the @samp{d}
6074: constraint letter (for data register) is ignored when computing
6075: register preferences.
6076:
6077: @example
6078: (define_insn "extendhisi2"
6079: [(set (match_operand:SI 0 "general_operand" "=*d,a")
6080: (sign_extend:SI
6081: (match_operand:HI 1 "general_operand" "0,g")))]
6082: @dots{})
6083: @end example
6084: @end table
6085:
6086: @node No Constraints,, Modifiers, Constraints
6087: @subsection Not Using Constraints
6088:
6089: Some machines are so clean that operand constraints are not required. For
6090: example, on the Vax, an operand valid in one context is valid in any other
6091: context. On such a machine, every operand constraint would be @samp{g},
6092: excepting only operands of ``load address'' instructions which are
6093: written as if they referred to a memory location's contents but actual
6094: refer to its address. They would have constraint @samp{p}.
6095:
6096: For such machines, instead of writing @samp{g} and @samp{p} for all
6097: the constraints, you can choose to write a description with empty constraints.
6098: Then you write @samp{""} for the constraint in every @samp{match_operand}.
6099: Address operands are identified by writing an @samp{address} expression
6100: around the @samp{match_operand}, not by their constraints.
6101:
6102: When the machine description has just empty constraints, certain parts
1.1.1.6 root 6103: of compilation are skipped, making the compiler faster. However,
6104: few machines actually do not need constraints; all machine descriptions
6105: now in existence use constraints.
1.1 root 6106:
6107: @node Standard Names, Pattern Ordering, Constraints, Machine Desc
6108: @section Standard Names for Patterns Used in Generation
6109:
6110: Here is a table of the instruction names that are meaningful in the RTL
6111: generation pass of the compiler. Giving one of these names to an
6112: instruction pattern tells the RTL generation pass that it can use the
6113: pattern in to accomplish a certain task.
6114:
6115: @table @asis
6116: @item @samp{mov@var{m}}
6117: Here @var{m} is a two-letter machine mode name, in lower case. This
6118: instruction pattern moves data with that machine mode from operand 1 to
6119: operand 0. For example, @samp{movsi} moves full-word data.
6120:
6121: If operand 0 is a @samp{subreg} with mode @var{m} of a register whose
6122: natural mode is wider than @var{m}, the effect of this instruction is
6123: to store the specified value in the part of the register that corresponds
6124: to mode @var{m}. The effect on the rest of the register is undefined.
6125:
6126: This class of patterns is special in several ways. First of all, each
6127: of these names @emph{must} be defined, because there is no other way
6128: to copy a datum from one place to another.
6129:
6130: Second, these patterns are not used solely in the RTL generation pass.
6131: Even the reload pass can generate move insns to copy values from stack
6132: slots into temporary registers. When it does so, one of the operands
6133: is a hard register and the other is an operand that can have a reload.
6134:
6135: Therefore, when given such a pair of operands, the pattern must
6136: generate RTL which needs no temporary registers---no registers other
6137: than the operands. For example, if you support the pattern with a
6138: @code{define_expand}, then in such a case you mustn't call
6139: @code{force_reg} or any other such function which might generate new
6140: pseudo registers.
6141:
6142: This requirement exists even for subword modes on a RISC machine where
6143: fetching those modes from memory normally requires several insns and
6144: some temporary registers. Look in @file{spur.md} to see how the
6145: requirement is satisfied.
6146:
6147: The variety of operands that have reloads depends on the rest of the
6148: machine description, but typically on a RISC machine these can only be
6149: pseudo registers that did not get hard registers, while on other
6150: machines explicit memory references will get optional reloads.
6151:
6152: In addition, the constraints must allow any hard register to be moved
6153: to any other hard register (provided that @code{HARD_REGNO_MODE_OK}
6154: permits mode @var{m} in each of the registers).
6155:
6156: @item @samp{movstrict@var{m}}
6157: Like @samp{mov@var{m}} except that if operand 0 is a @samp{subreg}
6158: with mode @var{m} of a register whose natural mode is wider,
6159: the @samp{movstrict@var{m}} instruction is guaranteed not to alter
6160: any of the register except the part which belongs to mode @var{m}.
6161:
6162: @item @samp{add@var{m}3}
6163: Add operand 2 and operand 1, storing the result in operand 0. All operands
6164: must have mode @var{m}. This can be used even on two-address machines, by
6165: means of constraints requiring operands 1 and 0 to be the same location.
6166:
6167: @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}
6168: Similar, for other arithmetic operations.
6169:
6170: There are special considerations for register classes for logical-and
6171: instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}.
6172: They apply not only to the patterns with these standard names, but to
6173: any patterns that will match such an instruction. @xref{Register
6174: Classes}.
6175:
6176: @item @samp{mulhisi3}
6177: Multiply operands 1 and 2, which have mode @code{HImode}, and store
6178: a @code{SImode} product in operand 0.
6179:
6180: @item @samp{mulqihi3}, @samp{mulsidi3}
6181: Similar widening-multiplication instructions of other widths.
6182:
6183: @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
6184: Similar widening-multiplication instructions that do unsigned
6185: multiplication.
6186:
6187: @item @samp{divmod@var{m}4}
6188: Signed division that produces both a quotient and a remainder.
6189: Operand 1 is divided by operand 2 to produce a quotient stored
6190: in operand 0 and a remainder stored in operand 3.
6191:
6192: @item @samp{udivmod@var{m}4}
6193: Similar, but does unsigned division.
6194:
6195: @item @samp{divmod@var{m}@var{n}4}
6196: Like @samp{divmod@var{m}4} except that only the dividend has mode
6197: @var{m}; the divisor, quotient and remainder have mode @var{n}.
6198: For example, the Vax has a @samp{divmoddisi4} instruction
6199: (but it is omitted from the machine description, because it
6200: is so slow that it is faster to compute remainders by the
6201: circumlocution that the compiler will use if this instruction is
6202: not available).
6203:
6204: @item @samp{ashl@var{m}3}
6205: Arithmetic-shift operand 1 left by a number of bits specified by
6206: operand 2, and store the result in operand 0. Operand 2 has
6207: mode @code{SImode}, not mode @var{m}.
6208:
6209: @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}
6210: Other shift and rotate instructions.
6211:
6212: Logical and arithmetic left shift are the same. Machines that do not
6213: allow negative shift counts often have only one instruction for
6214: shifting left. On such machines, you should define a pattern named
6215: @samp{ashl@var{m}3} and leave @samp{lshl@var{m}3} undefined.
6216:
6217: There are special considerations for register classes for shift
6218: instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}.
6219: They apply not only to the patterns with these standard names, but to
6220: any patterns that will match such an instruction. @xref{Register
6221: Classes}.
6222:
6223: @item @samp{neg@var{m}2}
6224: Negate operand 1 and store the result in operand 0.
6225:
6226: @item @samp{abs@var{m}2}
6227: Store the absolute value of operand 1 into operand 0.
6228:
6229: @item @samp{sqrt@var{m}2}
6230: Store the square root of operand 1 into operand 0.
6231:
6232: @item @samp{ffs@var{m}2}
6233: Store into operand 0 one plus the index of the least significant 1-bit
6234: of operand 1. If operand 1 is zero, store zero. @var{m} is the mode
6235: of operand 0; operand 1's mode is specified by the instruction
6236: pattern, and the compiler will convert the operand to that mode before
6237: generating the instruction.
6238:
6239: @item @samp{one_cmpl@var{m}2}
6240: Store the bitwise-complement of operand 1 into operand 0.
6241:
6242: @item @samp{cmp@var{m}}
6243: Compare operand 0 and operand 1, and set the condition codes.
6244: The RTL pattern should look like this:
6245:
6246: @example
1.1.1.6 root 6247: (set (cc0) (compare (match_operand:@var{m} 0 @dots{})
6248: (match_operand:@var{m} 1 @dots{})))
1.1 root 6249: @end example
6250:
6251: Each such definition in the machine description, for integer mode
6252: @var{m}, must have a corresponding @samp{tst@var{m}} pattern, because
6253: optimization can simplify the compare into a test when operand 1 is
6254: zero.
6255:
6256: @item @samp{tst@var{m}}
6257: Compare operand 0 against zero, and set the condition codes.
6258: The RTL pattern should look like this:
6259:
6260: @example
6261: (set (cc0) (match_operand:@var{m} 0 @dots{}))
6262: @end example
6263:
6264: @item @samp{movstr@var{m}}
6265: Block move instruction. The addresses of the destination and source
6266: strings are the first two operands, and both are in mode @code{Pmode}.
6267: The number of bytes to move is the third operand, in mode @var{m}.
1.1.1.5 root 6268: The fourth operand is the known shared alignment of the source and
6269: destination, in the form of a @code{const_int} rtx.
1.1 root 6270:
6271: @item @samp{cmpstr@var{m}}
6272: Block compare instruction, with operands like @samp{movstr@var{m}}
6273: except that the two memory blocks are compared byte by byte
6274: in lexicographic order. The effect of the instruction is to set
6275: the condition codes.
6276:
6277: @item @samp{float@var{m}@var{n}2}
6278: Convert operand 1 (valid for fixed point mode @var{m}) to floating
6279: point mode @var{n} and store in operand 0 (which has mode @var{n}).
6280:
6281: @item @samp{fix@var{m}@var{n}2}
6282: Convert operand 1 (valid for floating point mode @var{m}) to fixed
6283: point mode @var{n} as a signed number and store in operand 0 (which
6284: has mode @var{n}). This instruction's result is defined only when
6285: the value of operand 1 is an integer.
6286:
6287: @item @samp{fixuns@var{m}@var{n}2}
6288: Convert operand 1 (valid for floating point mode @var{m}) to fixed
6289: point mode @var{n} as an unsigned number and store in operand 0 (which
6290: has mode @var{n}). This instruction's result is defined only when the
6291: value of operand 1 is an integer.
6292:
6293: @item @samp{ftrunc@var{m}2}
6294: Convert operand 1 (valid for floating point mode @var{m}) to an
6295: integer value, still represented in floating point mode @var{m}, and
6296: store it in operand 0 (valid for floating point mode @var{m}).
6297:
6298: @item @samp{fix_trunc@var{m}@var{n}2}
6299: Like @samp{fix@var{m}@var{n}2} but works for any floating point value
6300: of mode @var{m} by converting the value to an integer.
6301:
6302: @item @samp{fixuns_trunc@var{m}@var{n}2}
6303: Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
6304: value of mode @var{m} by converting the value to an integer.
6305:
6306: @item @samp{trunc@var{m}@var{n}}
6307: Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
6308: store in operand 0 (which has mode @var{n}). Both modes must be fixed
6309: point or both floating point.
6310:
6311: @item @samp{extend@var{m}@var{n}}
6312: Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
6313: store in operand 0 (which has mode @var{n}). Both modes must be fixed
6314: point or both floating point.
6315:
6316: @item @samp{zero_extend@var{m}@var{n}}
6317: Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
6318: store in operand 0 (which has mode @var{n}). Both modes must be fixed
6319: point.
6320:
6321: @item @samp{extv}
6322: Extract a bit-field from operand 1 (a register or memory operand),
6323: where operand 2 specifies the width in bits and operand 3 the starting
6324: bit, and store it in operand 0. Operand 0 must have @code{Simode}.
6325: Operand 1 may have mode @code{QImode} or @code{SImode}; often
6326: @code{SImode} is allowed only for registers. Operands 2 and 3 must be
6327: valid for @code{SImode}.
6328:
6329: The RTL generation pass generates this instruction only with constants
6330: for operands 2 and 3.
6331:
6332: The bit-field value is sign-extended to a full word integer
6333: before it is stored in operand 0.
6334:
6335: @item @samp{extzv}
6336: Like @samp{extv} except that the bit-field value is zero-extended.
6337:
6338: @item @samp{insv}
6339: Store operand 3 (which must be valid for @code{SImode}) into a
6340: bit-field in operand 0, where operand 1 specifies the width in bits
6341: and operand 2 the starting bit. Operand 0 may have mode @code{QImode}
6342: or @code{SImode}; often @code{SImode} is allowed only for registers.
6343: Operands 1 and 2 must be valid for @code{SImode}.
6344:
6345: The RTL generation pass generates this instruction only with constants
6346: for operands 1 and 2.
6347:
6348: @item @samp{s@var{cond}}
6349: Store zero or nonzero in the operand according to the condition codes.
6350: Value stored is nonzero iff the condition @var{cond} is true.
6351: @var{cond} is the name of a comparison operation expression code, such
6352: as @samp{eq}, @samp{lt} or @samp{leu}.
6353:
6354: You specify the mode that the operand must have when you write the
6355: @code{match_operand} expression. The compiler automatically sees
6356: which mode you have used and supplies an operand of that mode.
6357:
6358: The value stored for a true condition must have 1 as its low bit.
6359: Otherwise the instruction is not suitable and must be omitted from the
6360: machine description. You must tell the compiler exactly which value
6361: is stored by defining the macro @code{STORE_FLAG_VALUE}.
6362:
6363: @item @samp{b@var{cond}}
6364: Conditional branch instruction. Operand 0 is a @samp{label_ref}
6365: that refers to the label to jump to. Jump if the condition codes
6366: meet condition @var{cond}.
6367:
6368: @item @samp{call}
6369: Subroutine call instruction returning no value. Operand 0 is the
6370: function to call; operand 1 is the number of bytes of arguments pushed
6371: (in mode @code{SImode}, except it is normally a @samp{const_int});
6372: operand 2 is the number of registers used as operands.
6373:
6374: On most machines, operand 2 is not actually stored into the RTL
6375: pattern. It is supplied for the sake of some RISC machines which need
6376: to put this information into the assembler code; they can put it in
6377: the RTL instead of operand 1.
6378:
6379: Operand 0 should be a @samp{mem} RTX whose address is the address of
6380: the function.
6381:
6382: @item @samp{call_value}
6383: Subroutine call instruction returning a value. Operand 0 is the hard
6384: register in which the value is returned. There are three more
6385: operands, the same as the three operands of the @samp{call}
6386: instruction (but with numbers increased by one).
6387:
6388: Subroutines that return @code{BLKmode} objects use the @samp{call}
6389: insn.
6390:
6391: @item @samp{return}
6392: Subroutine return instruction. This instruction pattern name should be
6393: defined only if a single instruction can do all the work of returning
6394: from a function.
6395:
6396: @item @samp{casesi}
6397: Instruction to jump through a dispatch table, including bounds checking.
6398: This instruction takes five operands:
6399:
6400: @enumerate
6401: @item
6402: The index to dispatch on, which has mode @code{SImode}.
6403:
6404: @item
6405: The lower bound for indices in the table, an integer constant.
6406:
6407: @item
1.1.1.6 root 6408: The total range of indices in the table---the largest index
6409: minus the smallest one (both inclusive).
1.1 root 6410:
6411: @item
6412: A label to jump to if the index has a value outside the bounds.
6413: (If the machine-description macro @code{CASE_DROPS_THROUGH} is defined,
6414: then an out-of-bounds index drops through to the code following
6415: the jump table instead of jumping to this label. In that case,
6416: this label is not actually used by the @samp{casesi} instruction,
6417: but it is always provided as an operand.)
6418:
6419: @item
6420: A label that precedes the table itself.
6421: @end enumerate
6422:
6423: The table is a @samp{addr_vec} or @samp{addr_diff_vec} inside of a
6424: @samp{jump_insn}. The number of elements in the table is one plus the
6425: difference between the upper bound and the lower bound.
6426:
6427: @item @samp{tablejump}
6428: Instruction to jump to a variable address. This is a low-level
6429: capability which can be used to implement a dispatch table when there
6430: is no @samp{casesi} pattern.
6431:
6432: This pattern requires two operands: the address or offset, and a label
6433: which should immediately precede the jump table. If the macro
6434: @code{CASE_VECTOR_PC_RELATIVE} is defined then the first operand is an
6435: absolute address to jump to; otherwise, it is an offset which counts
6436: from the address of the table.
6437:
6438: The @samp{tablejump} insn is always the last insn before the jump
6439: table it uses. Its assembler code normally has no need to use the
6440: second operand, but you should incorporate it in the RTL pattern so
6441: that the jump optimizer will not delete the table as unreachable code.
6442: @end table
6443:
6444: @node Pattern Ordering, Dependent Patterns, Standard Names, Machine Desc
6445: @section When the Order of Patterns Matters
6446:
6447: Sometimes an insn can match more than one instruction pattern. Then the
6448: pattern that appears first in the machine description is the one used.
6449: Therefore, more specific patterns (patterns that will match fewer things)
6450: and faster instructions (those that will produce better code when they
6451: do match) should usually go first in the description.
6452:
6453: In some cases the effect of ordering the patterns can be used to hide
6454: a pattern when it is not valid. For example, the 68000 has an
6455: instruction for converting a fullword to floating point and another
6456: for converting a byte to floating point. An instruction converting
6457: an integer to floating point could match either one. We put the
6458: pattern to convert the fullword first to make sure that one will
6459: be used rather than the other. (Otherwise a large integer might
6460: be generated as a single-byte immediate quantity, which would not work.)
6461: Instead of using this pattern ordering it would be possible to make the
6462: pattern for convert-a-byte smart enough to deal properly with any
6463: constant value.
6464:
6465: @node Dependent Patterns, Jump Patterns, Pattern Ordering, Machine Desc
6466: @section Interdependence of Patterns
6467:
6468: Every machine description must have a named pattern for each of the
6469: conditional branch names @samp{b@var{cond}}. The recognition template
6470: must always have the form
6471:
6472: @example
6473: (set (pc)
6474: (if_then_else (@var{cond} (cc0) (const_int 0))
6475: (label_ref (match_operand 0 "" ""))
6476: (pc)))
6477: @end example
6478:
6479: @noindent
6480: In addition, every machine description must have an anonymous pattern
6481: for each of the possible reverse-conditional branches. These patterns
6482: look like
6483:
6484: @example
6485: (set (pc)
6486: (if_then_else (@var{cond} (cc0) (const_int 0))
6487: (pc)
6488: (label_ref (match_operand 0 "" ""))))
6489: @end example
6490:
6491: @noindent
6492: They are necessary because jump optimization can turn direct-conditional
6493: branches into reverse-conditional branches.
6494:
6495: The compiler does more with RTL than just create it from patterns
6496: and recognize the patterns: it can perform arithmetic expression codes
6497: when constant values for their operands can be determined. As a result,
6498: sometimes having one pattern can require other patterns. For example, the
6499: Vax has no `and' instruction, but it has `and not' instructions. Here
6500: is the definition of one of them:
6501:
6502: @example
6503: (define_insn "andcbsi2"
6504: [(set (match_operand:SI 0 "general_operand" "")
6505: (and:SI (match_dup 0)
6506: (not:SI (match_operand:SI
6507: 1 "general_operand" ""))))]
6508: ""
6509: "bicl2 %1,%0")
6510: @end example
6511:
6512: @noindent
6513: If operand 1 is an explicit integer constant, an instruction constructed
6514: using that pattern can be simplified into an `and' like this:
6515:
6516: @example
6517: (set (reg:SI 41)
6518: (and:SI (reg:SI 41)
6519: (const_int 0xffff7fff)))
6520: @end example
6521:
6522: @noindent
6523: (where the integer constant is the one's complement of what
6524: appeared in the original instruction).
6525:
6526: To avoid a fatal error, the compiler must have a pattern that recognizes
6527: such an instruction. Here is what is used:
6528:
6529: @example
6530: (define_insn ""
6531: [(set (match_operand:SI 0 "general_operand" "")
6532: (and:SI (match_dup 0)
6533: (match_operand:SI 1 "general_operand" "")))]
6534: "GET_CODE (operands[1]) == CONST_INT"
6535: "*
6536: @{ operands[1]
6537: = gen_rtx (CONST_INT, VOIDmode, ~INTVAL (operands[1]));
6538: return \"bicl2 %1,%0\";
6539: @}")
6540: @end example
6541:
6542: @noindent
6543: Whereas a pattern to match a general `and' instruction is impossible to
6544: support on the Vax, this pattern is possible because it matches only a
6545: constant second argument: a special case that can be output as an `and not'
6546: instruction.
6547:
6548: A ``compare'' instruction whose RTL looks like this:
6549:
6550: @example
1.1.1.6 root 6551: (set (cc0) (compare @var{operand} (const_int 0)))
1.1 root 6552: @end example
6553:
6554: @noindent
6555: may be simplified by optimization into a ``test'' like this:
6556:
6557: @example
6558: (set (cc0) @var{operand})
6559: @end example
6560:
6561: @noindent
6562: So in the machine description, each ``compare'' pattern for an integer
6563: mode must have a corresponding ``test'' pattern that will match the
6564: result of such simplification.
6565:
6566: In some cases machines support instructions identical except for the
6567: machine mode of one or more operands. For example, there may be
6568: ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
6569: patterns are
6570:
6571: @example
6572: (set (match_operand:SI 0 @dots{})
6573: (extend:SI (match_operand:HI 1 @dots{})))
6574:
6575: (set (match_operand:SI 0 @dots{})
6576: (extend:SI (match_operand:QI 1 @dots{})))
6577: @end example
6578:
6579: @noindent
6580: Constant integers do not specify a machine mode, so an instruction to
6581: extend a constant value could match either pattern. The pattern it
6582: actually will match is the one that appears first in the file. For correct
6583: results, this must be the one for the widest possible mode (@code{HImode},
6584: here). If the pattern matches the @code{QImode} instruction, the results
6585: will be incorrect if the constant value does not actually fit that mode.
6586:
6587: Such instructions to extend constants are rarely generated because they are
6588: optimized away, but they do occasionally happen in nonoptimized
6589: compilations.
6590:
6591: When an instruction has the constraint letter @samp{o}, the reload
6592: pass may generate instructions which copy a nonoffsetable address into
6593: an index register. The idea is that the register can be used as a
6594: replacement offsetable address. In order for these generated
6595: instructions to work, there must be patterns to copy any kind of valid
6596: address into a register.
6597:
6598: Most older machine designs have ``load address'' instructions which do
6599: just what is needed here. Some RISC machines do not advertise such
6600: instructions, but the possible addresses on these machines are very
6601: limited, so it is easy to fake them.
6602:
6603: Auto-increment and auto-decrement addresses are an exception; there
6604: need not be an instruction that can copy such an address into a
6605: register, because reload handles these cases in a different manner.
6606:
6607: @node Jump Patterns, Peephole Definitions, Dependent Patterns, Machine Desc
6608: @section Defining Jump Instruction Patterns
6609:
6610: GNU CC assumes that the machine has a condition code. A comparison insn
6611: sets the condition code, recording the results of both signed and unsigned
6612: comparison of the given operands. A separate branch insn tests the
6613: condition code and branches or not according its value. The branch insns
6614: come in distinct signed and unsigned flavors. Many common machines, such
6615: as the Vax, the 68000 and the 32000, work this way.
6616:
6617: Some machines have distinct signed and unsigned compare instructions, and
6618: only one set of conditional branch instructions. The easiest way to handle
6619: these machines is to treat them just like the others until the final stage
6620: where assembly code is written. At this time, when outputting code for the
6621: compare instruction, peek ahead at the following branch using
6622: @code{NEXT_INSN (insn)}. (The variable @code{insn} refers to the insn
6623: being output, in the output-writing code in an instruction pattern.) If
6624: the RTL says that is an unsigned branch, output an unsigned compare;
6625: otherwise output a signed compare. When the branch itself is output, you
6626: can treat signed and unsigned branches identically.
6627:
6628: The reason you can do this is that GNU CC always generates a pair of
6629: consecutive RTL insns, one to set the condition code and one to test it,
6630: and keeps the pair inviolate until the end.
6631:
6632: To go with this technique, you must define the machine-description macro
6633: @code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no
6634: compare instruction is superfluous.
6635:
6636: Some machines have compare-and-branch instructions and no condition code.
6637: A similar technique works for them. When it is time to ``output'' a
6638: compare instruction, record its operands in two static variables. When
6639: outputting the branch-on-condition-code instruction that follows, actually
6640: output a compare-and-branch instruction that uses the remembered operands.
6641:
6642: It also works to define patterns for compare-and-branch instructions.
6643: In optimizing compilation, the pair of compare and branch instructions
1.1.1.5 root 6644: will be combined according to these patterns. But this does not happen
1.1 root 6645: if optimization is not requested. So you must use one of the solutions
6646: above in addition to any special patterns you define.
6647:
6648: @node Peephole Definitions, Expander Definitions, Jump Patterns, Machine Desc
6649: @section Defining Machine-Specific Peephole Optimizers
6650:
6651: In addition to instruction patterns the @file{md} file may contain
6652: definitions of machine-specific peephole optimizations.
6653:
6654: The combiner does not notice certain peephole optimizations when the data
6655: flow in the program does not suggest that it should try them. For example,
6656: sometimes two consecutive insns related in purpose can be combined even
6657: though the second one does not appear to use a register computed in the
6658: first one. A machine-specific peephole optimizer can detect such
6659: opportunities.
6660:
6661: A definition looks like this:
6662:
6663: @example
6664: (define_peephole
6665: [@var{insn-pattern-1}
6666: @var{insn-pattern-2}
6667: @dots{}]
6668: "@var{condition}"
6669: "@var{template}"
6670: "@var{machine-specific info}")
6671: @end example
6672:
6673: @noindent
6674: The last string operand may be omitted if you are not using any
6675: machine-specific information in this machine description. If present,
6676: it must obey the same rules as in a @samp{define_insn}.
6677:
6678: In this skeleton, @var{insn-pattern-1} and so on are patterns to match
1.1.1.5 root 6679: consecutive insns. The optimization applies to a sequence of insns when
6680: @var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
6681: the next, and so on.@refill
1.1 root 6682:
6683: @var{insn-pattern-1} and so on look @emph{almost} like the second operand
6684: of @code{define_insn}. There is one important difference: this pattern is
6685: an RTX, not a vector. If the @code{define_insn} pattern would be a vector
6686: of one element, the @var{insn-pattern} should be just that element, no
6687: vector. If the @code{define_insn} pattern would have multiple elements
6688: then the @var{insn-pattern} must place the vector inside an explicit
6689: @code{parallel} RTX.@refill
6690:
1.1.1.5 root 6691: The operands of the insns are matched with @code{match_operands} and
6692: @code{match_dup}, as usual. What is not usual is that the operand numbers
6693: apply to all the insn patterns in the definition. So, you can check for
6694: identical operands in two insns by using @code{match_operand} in one insn
6695: and @code{match_dup} in the other.
1.1 root 6696:
6697: The operand constraints used in @code{match_operand} patterns do not have
6698: any direct effect on the applicability of the optimization, but they will
6699: be validated afterward, so write constraints that are sure to fit whenever
6700: the optimization is applied. It is safe to use @code{"g"} for each
6701: operand.
6702:
1.1.1.5 root 6703: Once a sequence of insns matches the patterns, the @var{condition} is
6704: checked. This is a C expression which makes the final decision whether to
6705: perform the optimization (we do so if the expression is nonzero). If
1.1 root 6706: @var{condition} is omitted (in other words, the string is empty) then the
1.1.1.5 root 6707: optimization is applied to every sequence of insns that matches the
1.1 root 6708: patterns.
6709:
1.1.1.5 root 6710: The defined peephole optimizations are applied after register allocation
6711: is complete. Therefore, the peephole definition can check which
6712: operands have ended up in which kinds of registers, just by looking at
6713: the operands.
1.1 root 6714:
6715: The way to refer to the operands in @var{condition} is to write
6716: @code{operands[@var{i}]} for operand number @var{i} (as matched by
6717: @code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} to
6718: refer to the last of the insns being matched; use @code{PREV_INSN} to find
6719: the preceding insns (but be careful to skip over any @samp{note} insns that
6720: intervene).@refill
6721:
6722: When optimizing computations with intermediate results, you can use
6723: @var{condition} to match only when the intermediate results are not used
6724: elsewhere. Use the C expression @code{dead_or_set_p (@var{insn},
6725: @var{op})}, where @var{insn} is the insn in which you expect the value to
6726: be used for the last time (from the value of @code{insn}, together with use
6727: of @code{PREV_INSN}), and @var{op} is the intermediate value (from
6728: @code{operands[@var{i}]}).@refill
6729:
1.1.1.5 root 6730: Applying the optimization means replacing the sequence of insns with one
6731: new insn. The @var{template} controls ultimate output of assembler code
6732: for this combined insn. It works exactly like the template of a
6733: @code{define_insn}. Operand numbers in this template are the same ones
6734: used in matching the original sequence of insns.
1.1 root 6735:
6736: The result of a defined peephole optimizer does not need to match any of
1.1.1.5 root 6737: the insn patterns in the machine description; it does not even have an
6738: opportunity to match them. The peephole optimizer definition itself serves
6739: as the insn pattern to control how the insn is output.
6740:
6741: Defined peephole optimizers are run as assembler code is being output,
6742: so the insns they produce are never combined or rearranged in any way.
1.1 root 6743:
6744: Here is an example, taken from the 68000 machine description:
6745:
6746: @example
6747: (define_peephole
6748: [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
6749: (set (match_operand:DF 0 "register_operand" "f")
6750: (match_operand:DF 1 "register_operand" "ad"))]
6751: "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
6752: "*
6753: @{
6754: rtx xoperands[2];
6755: xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1);
6756: #ifdef MOTOROLA
6757: output_asm_insn (\"move.l %1,(sp)\", xoperands);
6758: output_asm_insn (\"move.l %1,-(sp)\", operands);
6759: return \"fmove.d (sp)+,%0\";
6760: #else
6761: output_asm_insn (\"movel %1,sp@@\", xoperands);
6762: output_asm_insn (\"movel %1,sp@@-\", operands);
6763: return \"fmoved sp@@+,%0\";
6764: #endif
6765: @}
6766: ")
6767: @end example
6768:
6769: The effect of this optimization is to change
6770:
6771: @example
6772: jbsr _foobar
6773: addql #4,sp
6774: movel d1,sp@@-
6775: movel d0,sp@@-
6776: fmoved sp@@+,fp0
6777: @end example
6778:
6779: @noindent
6780: into
6781:
6782: @example
6783: jbsr _foobar
6784: movel d1,sp@@
6785: movel d0,sp@@-
6786: fmoved sp@@+,fp0
6787: @end example
6788:
1.1.1.5 root 6789: @ignore
6790: If a peephole matches a sequence including one or more jump insns, you must
6791: take account of the flags such as @code{CC_REVERSED} which specify that the
6792: condition codes are represented in an unusual manner. The compiler
6793: automatically alters any ordinary conditional jumps which occur in such
6794: situations, but the compiler cannot alter jumps which have been replaced by
6795: peephole optimizations. So it is up to you to alter the assembler code
6796: that the peephole produces. Supply C code to write the assembler output,
6797: and in this C code check the condition code status flags and change the
6798: assembler code as appropriate.
6799: @end ignore
6800:
1.1 root 6801: @node Expander Definitions,, Peephole Definitions, Machine Desc
6802: @section Defining RTL Sequences for Code Generation
6803:
6804: On some target machines, some standard pattern names for RTL generation
6805: cannot be handled with single insn, but a sequence of RTL insns can
6806: represent them. For these target machines, you can write a
6807: @samp{define_expand} to specify how to generate the sequence of RTL.
6808:
6809: A @samp{define_expand} is an RTL expression that looks almost like a
6810: @samp{define_insn}; but, unlike the latter, a @samp{define_expand} is used
6811: only for RTL generation and it can produce more than one RTL insn.
6812:
6813: A @samp{define_expand} RTX has four operands:
6814:
6815: @itemize @bullet
6816: @item
6817: The name. Each @samp{define_expand} must have a name, since the only
6818: use for it is to refer to it by name.
6819:
6820: @item
6821: The RTL template. This is just like the RTL template for a
6822: @samp{define_peephole} in that it is a vector of RTL expressions
6823: each being one insn.
6824:
6825: @item
6826: The condition, a string containing a C expression. This expression is
6827: used to express how the availability of this pattern depends on
6828: subclasses of target machine, selected by command-line options when
6829: GNU CC is run. This is just like the condition of a
6830: @samp{define_insn} that has a standard name.
6831:
6832: @item
6833: The preparation statements, a string containing zero or more C
6834: statements which are to be executed before RTL code is generated from
6835: the RTL template.
6836:
6837: Usually these statements prepare temporary registers for use as
6838: internal operands in the RTL template, but they can also generate RTL
6839: insns directly by calling routines such as @samp{emit_insn}, etc.
6840: Any such insns precede the ones that come from the RTL template.
6841: @end itemize
6842:
6843: The RTL template, in addition to controlling generation of RTL insns,
6844: also describes the operands that need to be specified when this pattern
6845: is used. In particular, it gives a predicate for each operand.
6846:
6847: A true operand, which need to be specified in order to generate RTL from
6848: the pattern, should be described with a @samp{match_operand} in its first
6849: occurrence in the RTL template. This enters information on the operand's
6850: predicate into the tables that record such things. GNU CC uses the
6851: information to preload the operand into a register if that is required for
6852: valid RTL code. If the operand is referred to more than once, subsequent
6853: references should use @samp{match_dup}.
6854:
6855: The RTL template may also refer to internal ``operands'' which are
6856: temporary registers or labels used only within the sequence made by the
6857: @samp{define_expand}. Internal operands are substituted into the RTL
6858: template with @samp{match_dup}, never with @samp{match_operand}. The
6859: values of the internal operands are not passed in as arguments by the
6860: compiler when it requests use of this pattern. Instead, they are computed
6861: within the pattern, in the preparation statements. These statements
6862: compute the values and store them into the appropriate elements of
6863: @code{operands} so that @samp{match_dup} can find them.
6864:
6865: There are two special macros defined for use in the preparation statements:
6866: @code{DONE} and @code{FAIL}. Use them with a following semicolon,
6867: as a statement.
6868:
6869: @table @code
6870: @item DONE
6871: Use the @code{DONE} macro to end RTL generation for the pattern. The
6872: only RTL insns resulting from the pattern on this occasion will be
6873: those already emitted by explicit calls to @code{emit_insn} within the
6874: preparation statements; the RTL template will not be generated.
6875:
6876: @item FAIL
6877: Make the pattern fail on this occasion. When a pattern fails, it means
6878: that the pattern was not truly available. The calling routines in the
6879: compiler will try other strategies for code generation using other patterns.
6880:
6881: Failure is currently supported only for binary operations (addition,
6882: multiplication, shifting, etc.).
6883:
6884: Do not emit any insns explicitly with @code{emit_insn} before failing.
6885: @end table
6886:
6887: Here is an example, the definition of left-shift for the SPUR chip:
6888:
6889: @example
6890: (define_expand "ashlsi3"
6891: [(set (match_operand:SI 0 "register_operand" "")
6892: (ashift:SI
6893: (match_operand:SI 1 "register_operand" "")
6894: (match_operand:SI 2 "nonmemory_operand" "")))]
6895: ""
6896: "
6897: @{
6898: if (GET_CODE (operands[2]) != CONST_INT
6899: || (unsigned) INTVAL (operands[2]) > 3)
6900: FAIL;
6901: @}")
6902: @end example
6903:
6904: @noindent
6905: This example uses @samp{define_expand} so that it can generate an RTL insn
6906: for shifting when the shift-count is in the supported range of 0 to 3 but
6907: fail in other cases where machine insns aren't available. When it fails,
6908: the compiler tries another strategy using different patterns (such as, a
6909: library call).
6910:
6911: If the compiler were able to handle nontrivial condition-strings in
6912: patterns with names, then there would be possible to use a
6913: @samp{define_insn} in that case. Here is another case (zero-extension on
6914: the 68000) which makes more use of the power of @samp{define_expand}:
6915:
6916: @example
6917: (define_expand "zero_extendhisi2"
6918: [(set (match_operand:SI 0 "general_operand" "")
6919: (const_int 0))
6920: (set (strict_low_part
6921: (subreg:HI
6922: (match_operand:SI 0 "general_operand" "")
6923: 0))
6924: (match_operand:HI 1 "general_operand" ""))]
6925: ""
6926: "operands[1] = make_safe_from (operands[1], operands[0]);")
6927: @end example
6928:
6929: @noindent
6930: Here two RTL insns are generated, one to clear the entire output operand
6931: and the other to copy the input operand into its low half. This sequence
6932: is incorrect if the input operand refers to [the old value of] the output
6933: operand, so the preparation statement makes sure this isn't so. The
6934: function @code{make_safe_from} copies the @code{operands[1]} into a
6935: temporary register if it refers to @code{operands[0]}. It does this
6936: by emitting another RTL insn.
6937:
6938: Finally, a third example shows the use of an internal operand.
6939: Zero-extension on the SPUR chip is done by @samp{and}-ing the result
6940: against a halfword mask. But this mask cannot be represented by a
6941: @samp{const_int} because the constant value is too large to be legitimate
6942: on this machine. So it must be copied into a register with
6943: @code{force_reg} and then the register used in the @samp{and}.
6944:
6945: @example
6946: (define_expand "zero_extendhisi2"
6947: [(set (match_operand:SI 0 "register_operand" "")
6948: (and:SI (subreg:SI
6949: (match_operand:HI 1 "register_operand" "")
6950: 0)
6951: (match_dup 2)))]
6952: ""
6953: "operands[2]
6954: = force_reg (SImode, gen_rtx (CONST_INT,
6955: VOIDmode, 65535)); ")
6956: @end example
6957:
6958: @node Machine Macros, Config, Machine Desc, Top
6959: @chapter Machine Description Macros
6960:
6961: The other half of the machine description is a C header file conventionally
6962: given the name @file{tm-@var{machine}.h}. The file @file{tm.h} should be a
6963: link to it. The header file @file{config.h} includes @file{tm.h} and most
6964: compiler source files include @file{config.h}.
6965:
6966: @menu
6967: * Run-time Target:: Defining -m options like -m68000 and -m68020.
6968: * Storage Layout:: Defining sizes and alignments of data types.
6969: * Registers:: Naming and describing the hardware registers.
6970: * Register Classes:: Defining the classes of hardware registers.
6971: * Stack Layout:: Defining which way the stack grows and by how much.
6972: * Library Names:: Specifying names of subroutines to call automatically.
6973: * Addressing Modes:: Defining addressing modes valid for memory operands.
6974: * Condition Code:: Defining how insns update the condition code.
6975: * Assembler Format:: Defining how to write insns and pseudo-ops to output.
1.1.1.5 root 6976: * Cross-compilation:: Handling floating point for cross-compilers.
1.1 root 6977: * Misc:: Everything else.
6978: @end menu
6979:
6980: @node Run-time Target, Storage Layout, Machine Macros, Machine Macros
6981: @section Run-time Target Specification
6982:
6983: @table @code
6984: @item CPP_PREDEFINES
6985: Define this to be a string constant containing @samp{-D} options to
6986: define the predefined macros that identify this machine and system.
6987: These macros will be predefined unless the @samp{-ansi} option is
6988: specified.
6989:
1.1.1.4 root 6990: In addition, a parallel set of macros are predefined, whose names are
6991: made by appending @samp{__} at the beginning and at the end. These
6992: @samp{__} macros are permitted by the ANSI standard, so they are
6993: predefined regardless of whether @samp{-ansi} is specified.
6994:
6995: For example, on the Sun, one can use the following value:
1.1 root 6996:
6997: @example
6998: "-Dmc68000 -Dsun -Dunix"
6999: @end example
7000:
1.1.1.5 root 7001: The result is to define the macros @samp{__mc68000__}, @samp{__sun__}
1.1.1.4 root 7002: and @samp{__unix__} unconditionally, and the macros @samp{mc68000},
7003: @samp{sun} and @samp{unix} provided @samp{-ansi} is not specified.
7004:
1.1 root 7005: @item CPP_SPEC
7006: A C string constant that tells the GNU CC driver program options to
7007: pass to CPP. It can also specify how to translate options you
7008: give to GNU CC into options for GNU CC to pass to the CPP.
7009:
7010: Do not define this macro if it does not need to do anything.
7011:
7012: @item CC1_SPEC
7013: A C string constant that tells the GNU CC driver program options to
7014: pass to CC1. It can also specify how to translate options you
7015: give to GNU CC into options for GNU CC to pass to the CC1.
7016:
7017: Do not define this macro if it does not need to do anything.
7018:
7019: @item extern int target_flags;
7020: This declaration should be present.
7021:
7022: @item TARGET_@dots{}
7023: This series of macros is to allow compiler command arguments to
7024: enable or disable the use of optional features of the target machine.
7025: For example, one machine description serves both the 68000 and
7026: the 68020; a command argument tells the compiler whether it should
7027: use 68020-only instructions or not. This command argument works
7028: by means of a macro @code{TARGET_68020} that tests a bit in
7029: @code{target_flags}.
7030:
7031: Define a macro @code{TARGET_@var{featurename}} for each such option.
7032: Its definition should test a bit in @code{target_flags}; for example:
7033:
7034: @example
7035: #define TARGET_68020 (target_flags & 1)
7036: @end example
7037:
7038: One place where these macros are used is in the condition-expressions
7039: of instruction patterns. Note how @code{TARGET_68020} appears
7040: frequently in the 68000 machine description file, @file{m68k.md}.
7041: Another place they are used is in the definitions of the other
7042: macros in the @file{tm-@var{machine}.h} file.
7043:
7044: @item TARGET_SWITCHES
7045: This macro defines names of command options to set and clear
7046: bits in @code{target_flags}. Its definition is an initializer
7047: with a subgrouping for each command option.
7048:
7049: Each subgrouping contains a string constant, that defines the option
7050: name, and a number, which contains the bits to set in
7051: @code{target_flags}. A negative number says to clear bits instead;
7052: the negative of the number is which bits to clear. The actual option
7053: name is made by appending @samp{-m} to the specified name.
7054:
7055: One of the subgroupings should have a null string. The number in
7056: this grouping is the default value for @code{target_flags}. Any
7057: target options act starting with that value.
7058:
7059: Here is an example which defines @samp{-m68000} and @samp{-m68020}
7060: with opposite meanings, and picks the latter as the default:
7061:
7062: @example
7063: #define TARGET_SWITCHES \
7064: @{ @{ "68020", 1@}, \
7065: @{ "68000", -1@}, \
7066: @{ "", 1@}@}
7067: @end example
7068:
7069: @item OVERRIDE_OPTIONS
7070: Sometimes certain combinations of command options do not make sense on
7071: a particular target machine. You can define a macro
7072: @code{OVERRIDE_OPTIONS} to take account of this. This macro, if
7073: defined, is executed once just after all the command options have been
7074: parsed.
7075: @end table
7076:
7077: @node Storage Layout, Registers, Run-time Target, Machine Macros
7078: @section Storage Layout
7079:
7080: Note that the definitions of the macros in this table which are sizes or
7081: alignments measured in bits do not need to be constant. They can be C
7082: expressions that refer to static variables, such as the @code{target_flags}.
7083: @xref{Run-time Target}.
7084:
7085: @table @code
7086: @item BITS_BIG_ENDIAN
7087: Define this macro if the most significant bit in a byte has the lowest
7088: number. This means that bit-field instructions count from the most
7089: significant bit. If the machine has no bit-field instructions, this
7090: macro is irrelevant.
7091:
7092: @item BYTES_BIG_ENDIAN
7093: Define this macro if the most significant byte in a word has the
7094: lowest number.
7095:
7096: @item WORDS_BIG_ENDIAN
7097: Define this macro if, in a multiword object, the most significant
7098: word has the lowest number.
7099:
7100: @item BITS_PER_UNIT
7101: Number of bits in an addressable storage unit (byte); normally 8.
7102:
7103: @item BITS_PER_WORD
7104: Number of bits in a word; normally 32.
7105:
7106: @item UNITS_PER_WORD
7107: Number of storage units in a word; normally 4.
7108:
7109: @item POINTER_SIZE
7110: Width of a pointer, in bits.
7111:
7112: @item POINTER_BOUNDARY
7113: Alignment required for pointers stored in memory, in bits.
7114:
7115: @item PARM_BOUNDARY
1.1.1.7 ! root 7116: Normal alignment required for function parameters on the stack, in
! 7117: bits. All stack parameters receive least this much alignment
! 7118: regardless of data type. On most machines, this is the same as the
! 7119: size of an integer.
! 7120:
! 7121: @item MAX_PARM_BOUNDARY
! 7122: Largest alignment required for any stack parameters, in bits. If the
! 7123: data type of the parameter calls for more alignment than
! 7124: @code{PARM_BOUNDARY}, then it is given extra padding up to this limit.
! 7125:
! 7126: Don't define this macro if it would be equal to @code{PARM_BOUNDARY};
! 7127: in other words, if the alignment of a stack parameter should not
! 7128: depend on its data type (as is the case on most machines).
1.1 root 7129:
7130: @item STACK_BOUNDARY
7131: Define this macro if you wish to preserve a certain alignment for
7132: the stack pointer at all times. The definition is a C expression
7133: for the desired alignment (measured in bits).
7134:
7135: @item FUNCTION_BOUNDARY
7136: Alignment required for a function entry point, in bits.
7137:
7138: @item BIGGEST_ALIGNMENT
7139: Biggest alignment that any data type can require on this machine, in bits.
7140:
7141: @item EMPTY_FIELD_BOUNDARY
7142: Alignment in bits to be given to a structure bit field that follows an
7143: empty field such as @code{int : 0;}.
7144:
7145: @item STRUCTURE_SIZE_BOUNDARY
7146: Number of bits which any structure or union's size must be a multiple of.
7147: Each structure or union's size is rounded up to a multiple of this.
7148:
7149: If you do not define this macro, the default is the same as
7150: @code{BITS_PER_UNIT}.
7151:
7152: @item STRICT_ALIGNMENT
7153: Define this if instructions will fail to work if given data not
7154: on the nominal alignment. If instructions will merely go slower
7155: in that case, do not define this macro.
7156:
7157: @item PCC_BITFIELD_TYPE_MATTERS
7158: Define this if you wish to imitate a certain bizarre behavior pattern
7159: of some instances of PCC: a bit field whose declared type is
7160: @code{int} has the same effect on the size and alignment of a
7161: structure as an actual @code{int} would have.
7162:
7163: Just what effect that is in GNU CC depends on other parameters, but on
7164: most machines it would force the structure's alignment and size to a
7165: multiple of 32 or @code{BIGGEST_ALIGNMENT} bits.
7166:
1.1.1.7 ! root 7167: @item MAX_FIXED_MODE_SIZE
! 7168: An integer expression for the largest integer machine mode that should
! 7169: actually be used. All integer machine modes of this size or smaller
! 7170: can be used for structures and unions with the appropriate sizes.
! 7171:
1.1 root 7172: @item CHECK_FLOAT_VALUE (@var{mode}, @var{value})
7173: A C statement to validate the value @var{value} (or type
7174: @code{double}) for mode @var{mode}. This means that you check whether
7175: @var{value} fits within the possible range of values for mode
7176: @var{mode} on this target machine. The mode @var{mode} is always
7177: @code{SFmode} or @code{DFmode}.
7178:
7179: If @var{value} is not valid, you should call @code{error} to print an
7180: error message and then assign some valid value to @var{value}.
7181: Allowing an invalid value to go through the compiler can produce
7182: incorrect assembler code which may even cause Unix assemblers to
7183: crash.
7184:
7185: This macro need not be defined if there is no work for it to do.
7186: @end table
7187:
7188: @node Registers, Register Classes, Storage Layout, Machine Macros
7189: @section Register Usage
7190:
7191: @table @code
7192: @item FIRST_PSEUDO_REGISTER
7193: Number of hardware registers known to the compiler. They receive
7194: numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
7195: pseudo register's number really is assigned the number
7196: @code{FIRST_PSEUDO_REGISTER}.
7197:
7198: @item FIXED_REGISTERS
7199: An initializer that says which registers are used for fixed purposes
7200: all throughout the compiled code and are therefore not available for
7201: general allocation. These would include the stack pointer, the frame
7202: pointer (except on machines where that can be used as a general
7203: register when no frame pointer is needed), the program counter on
7204: machines where that is considered one of the addressable registers,
7205: and any other numbered register with a standard use.
7206:
7207: This information is expressed as a sequence of numbers, separated by
7208: commas and surrounded by braces. The @var{n}th number is 1 if
7209: register @var{n} is fixed, 0 otherwise.
7210:
7211: The table initialized from this macro, and the table initialized by
7212: the following one, may be overridden at run time either automatically,
7213: by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
7214: the user with the command options @samp{-ffixed-@var{reg}},
7215: @samp{-fcall-used-@var{reg}} and @samp{-fcall-saved-@var{reg}}.
7216:
7217: @item CALL_USED_REGISTERS
7218: Like @code{FIXED_REGISTERS} but has 1 for each register that is
7219: clobbered (in general) by function calls as well as for fixed
7220: registers. This macro therefore identifies the registers that are not
7221: available for general allocation of values that must live across
7222: function calls.
7223:
7224: If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
7225: automatically saves it on function entry and restores it on function
7226: exit, if the register is used within the function.
7227:
1.1.1.6 root 7228: @item DEFAULT_CALLER_SAVES
7229: Define this macro if the target machine if function calls do not preserve
7230: any registers; in other words, if @code{CALL_USED_REGISTERS} has 1
7231: for all registers. This macro enables @samp{-fcaller-saves} by default.
7232: Eventually that option will be enabled by default on all machines and both
7233: the option and this macro will be eliminated.
7234:
1.1 root 7235: @item CONDITIONAL_REGISTER_USAGE
7236: Zero or more C statements that may conditionally modify two variables
7237: @code{fixed_regs} and @code{call_used_regs} (both of type @code{char
7238: []}) after they have been initialized from the two preceding macros.
7239:
7240: This is necessary in case the fixed or call-clobbered registers depend
7241: on target flags.
7242:
7243: You need not define this macro if it has no work to do.
7244:
7245: If the usage of an entire class of registers depends on the target
1.1.1.5 root 7246: flags, you may indicate this to GCC by using this macro to modify
1.1 root 7247: @code{fixed_regs} and @code{call_used_regs} to 1 for each of the
1.1.1.5 root 7248: registers in the classes which should not be used by GCC. Also define
1.1 root 7249: the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it
7250: is called with a letter for a class that shouldn't be used.
7251:
7252: (However, if this class is not included in @code{GENERAL_REGS} and all
7253: of the insn patterns whose constraints permit this class are
7254: controlled by target switches, then GCC will automatically avoid using
7255: these registers when the target switches are opposed to them.)
7256:
7257: @item OVERLAPPING_REGNO_P (@var{regno})
1.1.1.5 root 7258: If defined, this is a C expression whose value is nonzero if hard
7259: register number @var{regno} is an overlapping register. This means a
7260: hard register which overlaps a hard register with a different number.
7261: (Such overlap is undesirable, but occasionally it allows a machine to
7262: be supported which otherwise could not be.) This macro must return
7263: nonzero for @emph{all} the registers which overlap each other. GNU CC
7264: can use an overlapping register only in certain limited ways. It can
7265: be used for allocation within a basic block, and may be spilled for
7266: reloading; that is all.
1.1 root 7267:
7268: If this macro is not defined, it means that none of the hard registers
7269: overlap each other. This is the usual situation.
7270:
7271: @item INSN_CLOBBERS_REGNO_P (@var{insn}, @var{regno})
7272: If defined, this is a C expression whose value should be nonzero if
7273: the insn @var{insn} has the effect of mysteriously clobbering the
7274: contents of hard register number @var{regno}. By ``mysterious'' we
7275: mean that the insn's RTL expression doesn't describe such an effect.
7276:
7277: If this macro is not defined, it means that no insn clobbers registers
7278: mysteriously. This is the usual situation; all else being equal,
7279: it is best for the RTL expression to show all the activity.
7280:
7281: @item PRESERVE_DEATH_INFO_REGNO_P (@var{regno})
7282: If defined, this is a C expression whose value is nonzero if accurate
7283: @code{REG_DEAD} notes are needed for hard register number @var{regno}
7284: at the time of outputting the assembler code. When this is so, a few
7285: optimizations that take place after register allocation and could
7286: invalidate the death notes are not done when this register is
7287: involved.
7288:
7289: You would arrange to preserve death info for a register when some
7290: of the code in the machine description which is executed to write
7291: the assembler code looks at the the death notes. This is
7292: necessary only when the actual hardware feature which GNU CC
7293: thinks of as a register is not actually a register of the usual sort.
7294: (It might, for example, be a hardware stack.)
7295:
7296: If this macro is not defined, it means that no death notes need to be
7297: preserved. This is the usual situation.
7298:
7299: @item HARD_REGNO_REGS (@var{regno}, @var{mode})
7300: A C expression for the number of consecutive hard registers, starting
7301: at register number @var{regno}, required to hold a value of mode
7302: @var{mode}.
7303:
7304: On a machine where all registers are exactly one word, a suitable
7305: definition of this macro is
7306:
7307: @example
7308: #define HARD_REGNO_NREGS(REGNO, MODE) \
7309: ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \
7310: / UNITS_PER_WORD))
7311: @end example
7312:
7313: @item HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
7314: A C expression that is nonzero if it is permissible to store a value
7315: of mode @var{mode} in hard register number @var{regno} (or in several
7316: registers starting with that one). For a machine where all registers
7317: are equivalent, a suitable definition is
7318:
7319: @example
7320: #define HARD_REGNO_MODE_OK(REGNO, MODE) 1
7321: @end example
7322:
7323: It is not necessary for this macro to check for fixed register numbers
7324: because the allocation mechanism considers them to be always occupied.
7325:
7326: Many machines have special registers for floating point arithmetic.
7327: Often people assume that floating point machine modes are allowed only
7328: in floating point registers. This is not true. Any registers that
7329: can hold integers can safely @emph{hold} a floating point machine
7330: mode, whether or not floating arithmetic can be done on it in those
7331: registers.
7332:
7333: The true significance of special floating registers is rather than
7334: non-floating-point machine modes @emph{may not} go in those registers.
7335: This is true if the floating registers normalize any value stored in
7336: them, because storing a non-floating value there would garble it. If
7337: the floating registers do not automatically normalize, if you can
7338: store any bit pattern in one and retrieve it unchanged without a trap,
7339: then any machine mode may go in a floating register and this macro
7340: should say so.
7341:
7342: Sometimes there are floating registers that are especially slow to
7343: access, so that it is better to store a value in a stack frame than in
7344: such a register if floating point arithmetic is not being done. As long
7345: as the floating registers are not in class @code{GENERAL_REGS}, they
7346: will not be used unless some insn's constraint asks for one.
7347:
7348: It is obligatory to support floating point `move' instructions into
7349: and out of any registers that can hold fixed point values, because
7350: unions and structures (which have modes @samp{SImode} or
7351: @samp{DImode}) can be in those registers and they may have floating
7352: point members.
7353:
7354: There may also be a need to support fixed point `move' instructions in
7355: and out of floating point registers. Unfortunately, I have forgotten
7356: why this was so, and I don't know whether it is still true. If
7357: @code{HARD_REGNO_MODE_OK} rejects fixed point values in floating point
7358: registers, then the constraints of the fixed point `move' instructions
7359: must be designed to avoid ever trying to reload into a floating point
7360: register.
7361:
7362: @item MODES_TIEABLE_P (@var{mode1}, @var{mode2})
7363: A C expression that is nonzero if it is desirable to choose register
7364: allocation so as to avoid move instructions between a value of mode
7365: @var{mode1} and a value of mode @var{mode2}.
7366:
7367: If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
7368: @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different
7369: for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1},
7370: @var{mode2})} must be zero.
7371:
7372: @item PC_REGNUM
7373: If the program counter has a register number, define this as that
7374: register number. Otherwise, do not define it.
7375:
7376: @item STACK_POINTER_REGNUM
7377: The register number of the stack pointer register, which must also be
7378: a fixed register according to @code{FIXED_REGISTERS}. On many
7379: machines, the hardware determines which register this is.
7380:
7381: @item FRAME_POINTER_REGNUM
7382: The register number of the frame pointer register, which is used to
7383: access automatic variables in the stack frame. On some machines, the
7384: hardware determines which register this is. On other machines, you
7385: can choose any register you wish for this purpose.
7386:
7387: @item FRAME_POINTER_REQUIRED
7388: A C expression which is nonzero if a function must have and use a
7389: frame pointer. This expression is evaluated in the reload pass, in
7390: the function @code{reload}, and it can in principle examine the
7391: current function and decide according to the facts, but on most
7392: machines the constant 0 or the constant 1 suffices. Use 0 when the
7393: machine allows code to be generated with no frame pointer, and doing
7394: so saves some time or space. Use 1 when there is no possible
7395: advantage to avoiding a frame pointer.
7396:
1.1.1.5 root 7397: In certain cases, the compiler does not know how to produce valid code
7398: without a frame pointer. The compiler recognizes those cases and
7399: automatically gives the function a frame pointer regardless of what
1.1 root 7400: @code{FRAME_POINTER_REQUIRED} says. You don't need to worry about
7401: them.@refill
7402:
7403: In a function that does not require a frame pointer, the frame pointer
7404: register can be allocated for ordinary usage, unless you mark it as a
7405: fixed register. See @code{FIXED_REGISTERS} for more information.
7406:
7407: @item ARG_POINTER_REGNUM
7408: The register number of the arg pointer register, which is used to
7409: access the function's argument list. On some machines, this is the
7410: same as the frame pointer register. On some machines, the hardware
7411: determines which register this is. On other machines, you can choose
7412: any register you wish for this purpose. If this is not the same
7413: register as the frame pointer register, then you must mark it as a
7414: fixed register according to @code{FIXED_REGISTERS}.
7415:
7416: @item STATIC_CHAIN_REGNUM
7417: The register number used for passing a function's static chain
7418: pointer. This is needed for languages such as Pascal and Algol where
7419: functions defined within other functions can access the local
7420: variables of the outer functions; it is not currently used because C
7421: does not provide this feature, but you must define the macro.
7422:
7423: The static chain register need not be a fixed register.
7424:
7425: @item STRUCT_VALUE_REGNUM
7426: When a function's value's mode is @code{BLKmode}, the value is not
7427: returned according to @code{FUNCTION_VALUE}. Instead, the caller
7428: passes the address of a block of memory in which the value should be
7429: stored.
7430:
7431: If this value is passed in a register, then @code{STRUCT_VALUE_REGNUM}
7432: should be the number of that register.
7433:
7434: @item STRUCT_VALUE
7435: If the structure value address is not passed in a register, define
7436: @code{STRUCT_VALUE} as an expression returning an RTX for the place
7437: where the address is passed. If it returns a @samp{mem} RTX, the
7438: address is passed as an ``invisible'' first argument.
7439:
7440: @item STRUCT_VALUE_INCOMING_REGNUM
7441: On some architectures the place where the structure value address
7442: is found by the called function is not the same place that the
7443: caller put it. This can be due to register windows, or it could
7444: be because the function prologue moves it to a different place.
7445:
7446: If the incoming location of the structure value address is in a
7447: register, define this macro as the register number.
7448:
7449: @item STRUCT_VALUE_INCOMING
7450: If the incoming location is not a register, define
7451: @code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the
7452: called function should find the value. If it should find the value on
7453: the stack, define this to create a @samp{mem} which refers to the
7454: frame pointer. If the value is a @samp{mem}, the compiler assumes it
7455: is for an invisible first argument, and leaves space for it when
7456: finding the first real argument.
7457:
7458: @item REG_ALLOC_ORDER
7459: If defined, an initializer for a vector of integers, containing the
7460: numbers of hard registers in the order in which the GNU CC should
7461: prefer to use them (from most preferred to least).
7462:
7463: If this macro is not defined, registers are used lowest numbered first
7464: (all else being equal).
7465:
7466: One use of this macro is on the 360, where the highest numbered
7467: registers must always be saved and the save-multiple-registers
7468: instruction supports only sequences of consecutive registers. This
7469: macro is defined to cause the highest numbered allocatable registers
7470: to be used first.
7471: @end table
7472:
7473: @node Register Classes, Stack Layout, Registers, Machine Macros
7474: @section Register Classes
7475:
7476: On many machines, the numbered registers are not all equivalent.
7477: For example, certain registers may not be allowed for indexed addressing;
7478: certain registers may not be allowed in some instructions. These machine
7479: restrictions are described to the compiler using @dfn{register classes}.
7480:
7481: You define a number of register classes, giving each one a name and saying
7482: which of the registers belong to it. Then you can specify register classes
7483: that are allowed as operands to particular instruction patterns.
7484:
7485: In general, each register will belong to several classes. In fact, one
7486: class must be named @code{ALL_REGS} and contain all the registers. Another
7487: class must be named @code{NO_REGS} and contain no registers. Often the
7488: union of two classes will be another class; however, this is not required.
7489:
7490: One of the classes must be named @code{GENERAL_REGS}. There is nothing
7491: terribly special about the name, but the operand constraint letters
7492: @samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is
7493: the same as @code{ALL_REGS}, just define it as a macro which expands
7494: to @code{ALL_REGS}.
7495:
7496: The way classes other than @code{GENERAL_REGS} are specified in operand
7497: constraints is through machine-dependent operand constraint letters.
7498: You can define such letters to correspond to various classes, then use
7499: them in operand constraints.
7500:
7501: You should define a class for the union of two classes whenever some
7502: instruction allows both classes. For example, if an instruction allows
7503: either a floating-point (coprocessor) register or a general register for a
7504: certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
7505: which includes both of them. Otherwise you will get suboptimal code.
7506:
7507: You must also specify certain redundant information about the register
7508: classes: for each class, which classes contain it and which ones are
7509: contained in it; for each pair of classes, the largest class contained
7510: in their union.
7511:
7512: Register classes used for input-operands of bitwise-and or shift
7513: instructions have a special requirement: each such class must have, for
7514: each fixed-point machine mode, a subclass whose registers can transfer that
7515: mode to or from memory. For example, on some machines, the operations for
7516: single-byte values (@code{QImode}) are limited to certain registers. When
7517: this is so, each register class that is used in a bitwise-and or shift
7518: instruction must have a subclass consisting of registers from which
7519: single-byte values can be loaded or stored. This is so that
7520: @code{PREFERRED_RELOAD_CLASS} can always have a possible value to return.
7521:
7522: @table @code
7523: @item enum reg_class
7524: An enumeral type that must be defined with all the register class names
7525: as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS}
7526: must be the last register class, followed by one more enumeral value,
7527: @code{LIM_REG_CLASSES}, which is not a register class but rather
7528: tells how many classes there are.
7529:
7530: Each register class has a number, which is the value of casting
7531: the class name to type @code{int}. The number serves as an index
7532: in many of the tables described below.
7533:
7534: @item N_REG_CLASSES
7535: The number of distinct register classes, defined as follows:
7536:
7537: @example
7538: #define N_REG_CLASSES (int) LIM_REG_CLASSES
7539: @end example
7540:
7541: @item REG_CLASS_NAMES
7542: An initializer containing the names of the register classes as C string
7543: constants. These names are used in writing some of the debugging dumps.
7544:
7545: @item REG_CLASS_CONTENTS
7546: An initializer containing the contents of the register classes, as integers
7547: which are bit masks. The @var{n}th integer specifies the contents of class
7548: @var{n}. The way the integer @var{mask} is interpreted is that
7549: register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
7550:
7551: When the machine has more than 32 registers, an integer does not suffice.
7552: Then the integers are replaced by sub-initializers, braced groupings containing
7553: several integers. Each sub-initializer must be suitable as an initializer
7554: for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
7555:
7556: @item REGNO_REG_CLASS (@var{regno})
7557: A C expression whose value is a register class containing hard register
7558: @var{regno}. In general there is more that one such class; choose a class
7559: which is @dfn{minimal}, meaning that no smaller class also contains the
7560: register.
7561:
7562: @item BASE_REG_CLASS
7563: A macro whose definition is the name of the class to which a valid
7564: base register must belong. A base register is one used in an address
7565: which is the register value plus a displacement.
7566:
7567: @item INDEX_REG_CLASS
7568: A macro whose definition is the name of the class to which a valid
7569: index register must belong. An index register is one used in an
7570: address where its value is either multiplied by a scale factor or
7571: added to another register (as well as added to a displacement).
7572:
7573: @item REG_CLASS_FROM_LETTER (@var{char})
7574: A C expression which defines the machine-dependent operand constraint
7575: letters for register classes. If @var{char} is such a letter, the
7576: value should be the register class corresponding to it. Otherwise,
7577: the value should be @code{NO_REGS}.
7578:
7579: @item REGNO_OK_FOR_BASE_P (@var{num})
7580: A C expression which is nonzero if register number @var{num} is
7581: suitable for use as a base register in operand addresses. It may be
7582: either a suitable hard register or a pseudo register that has been
7583: allocated such a hard register.
7584:
7585: @item REGNO_OK_FOR_INDEX_P (@var{num})
7586: A C expression which is nonzero if register number @var{num} is
7587: suitable for use as an index register in operand addresses. It may be
7588: either a suitable hard register or a pseudo register that has been
7589: allocated such a hard register.
7590:
7591: The difference between an index register and a base register is that
7592: the index register may be scaled. If an address involves the sum of
7593: two registers, neither one of them scaled, then either one may be
7594: labeled the ``base'' and the other the ``index''; but whichever
7595: labeling is used must fit the machine's constraints of which registers
7596: may serve in each capacity. The compiler will try both labelings,
7597: looking for one that is valid, and will reload one or both registers
7598: only if neither labeling works.
7599:
7600: @item PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
7601: A C expression that places additional restrictions on the register class
7602: to use when it is necessary to copy value @var{x} into a register in class
7603: @var{class}. The value is a register class; perhaps @var{class}, or perhaps
7604: another, smaller class. On many machines, the definition
7605:
7606: @example
7607: #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
7608: @end example
7609:
7610: @noindent
7611: is safe.
7612:
7613: Sometimes returning a more restrictive class makes better code. For
7614: example, on the 68000, when @var{x} is an integer constant that is in range
7615: for a @samp{moveq} instruction, the value of this macro is always
7616: @code{DATA_REGS} as long as @var{class} includes the data registers.
7617: Requiring a data register guarantees that a @samp{moveq} will be used.
7618:
7619: If @var{x} is a @samp{const_double}, by returning @code{NO_REGS}
7620: you can force @var{x} into a memory constant. This is useful on
7621: certain machines where immediate floating values cannot be loaded into
7622: certain kinds of registers.
7623:
7624: In a shift instruction or a bitwise-and instruction, the mode of @var{x},
7625: the value being reloaded, may not be the same as the mode of the
7626: instruction's operand. (They will both be fixed-point modes, however.) In
7627: such a case, @var{class} may not be a safe value to return. @var{class} is
7628: certainly valid for the instruction, but it may not be valid for reloading
7629: @var{x}. This problem can occur on machines such as the 68000 and 80386
7630: where some registers can handle full-word values but cannot handle
7631: single-byte values.
7632:
7633: On such machines, this macro must examine the mode of @var{x} and return a
7634: subclass of @var{class} which can handle loads and stores of that mode. On
7635: the 68000, where address registers cannot handle @code{QImode}, if @var{x}
7636: has @code{QImode} then you must return @code{DATA_REGS}. If @var{class} is
7637: @code{ADDR_REGS}, then there is no correct value to return; but the shift
7638: and bitwise-and instructions don't use @code{ADDR_REGS}, so this fatal case
7639: never arises.
7640:
7641: @item CLASS_MAX_NREGS (@var{class}, @var{mode})
7642: A C expression for the maximum number of consecutive registers
7643: of class @var{class} needed to hold a value of mode @var{mode}.
7644:
7645: This is closely related to the macro @code{HARD_REGNO_NREGS}.
7646: In fact, the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
7647: should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, @var{mode})}
7648: for all @var{regno} values in the class @var{class}.
7649:
7650: This macro helps control the handling of multiple-word values
7651: in the reload pass.
7652: @end table
7653:
7654: Two other special macros describe which constants fit which constraint
7655: letters.
7656:
7657: @table @code
7658: @item CONST_OK_FOR_LETTER_P (@var{value}, @var{c})
7659: A C expression that defines the machine-dependent operand constraint letters
7660: that specify particular ranges of integer values. If @var{c} is one
7661: of those letters, the expression should check that @var{value}, an integer,
7662: is in the appropriate range and return 1 if so, 0 otherwise. If @var{c} is
7663: not one of those letters, the value should be 0 regardless of @var{value}.
7664:
7665: @item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c})
7666: A C expression that defines the machine-dependent operand constraint
7667: letters that specify particular ranges of floating values. If @var{c} is
7668: one of those letters, the expression should check that @var{value}, an RTX
7669: of code @samp{const_double}, is in the appropriate range and return 1 if
7670: so, 0 otherwise. If @var{c} is not one of those letters, the value should
7671: be 0 regardless of @var{value}.
7672: @end table
7673:
7674: @node Stack Layout, Library Names, Register Classes, Machine Macros
7675: @section Describing Stack Layout
7676:
7677: @table @code
7678: @item STACK_GROWS_DOWNWARD
7679: Define this macro if pushing a word onto the stack moves the stack
7680: pointer to a smaller address.
7681:
7682: When we say, ``define this macro if @dots{},'' it means that the
7683: compiler checks this macro only with @code{#ifdef} so the precise
7684: definition used does not matter.
7685:
7686: @item FRAME_GROWS_DOWNWARD
7687: Define this macro if the addresses of local variable slots are at negative
7688: offsets from the frame pointer.
7689:
7690: @item STARTING_FRAME_OFFSET
7691: Offset from the frame pointer to the first local variable slot to be allocated.
7692:
7693: If @code{FRAME_GROWS_DOWNWARD}, the next slot's offset is found by
7694: subtracting the length of the first slot from @code{STARTING_FRAME_OFFSET}.
7695: Otherwise, it is found by adding the length of the first slot to
7696: the value @code{STARTING_FRAME_OFFSET}.
7697:
7698: @item PUSH_ROUNDING (@var{npushed})
7699: A C expression that is the number of bytes actually pushed onto the
7700: stack when an instruction attempts to push @var{npushed} bytes.
7701:
7702: If the target machine does not have a push instruction, do not define
7703: this macro. That directs GNU CC to use an alternate strategy: to
7704: allocate the entire argument block and then store the arguments into
7705: it.
7706:
7707: On some machines, the definition
7708:
7709: @example
7710: #define PUSH_ROUNDING(BYTES) (BYTES)
7711: @end example
7712:
7713: @noindent
7714: will suffice. But on other machines, instructions that appear
7715: to push one byte actually push two bytes in an attempt to maintain
7716: alignment. Then the definition should be
7717:
7718: @example
7719: #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
7720: @end example
7721:
7722: @item FIRST_PARM_OFFSET (@var{fundecl})
7723: Offset from the argument pointer register to the first argument's
7724: address. On some machines it may depend on the data type of the
7725: function. (In the next version of GNU CC, the argument will be
7726: changed to the function data type rather than its declaration.)
7727:
7728: @item FIRST_PARM_CALLER_OFFSET (@var{fundecl})
7729: Define this macro on machines where register parameters have shadow
7730: locations on the stack, at addresses below the nominal parameter.
7731: This matters because certain arguments cannot be passed on the stack.
7732: On these machines, such arguments must be stored into the shadow
7733: locations.
7734:
7735: This macro should expand into a C expression whose value is the offset
7736: of the first parameter's shadow location from the nominal stack
7737: pointer value. (That value is itself computed by adding the value of
7738: @code{STACK_POINTER_OFFSET} to the stack pointer register.)
7739:
1.1.1.6 root 7740: @item STACK_ARGS_ADJUST (@var{size})
7741: Define this macro if the machine requires padding on the stack for
7742: certain function calls. This is padding on a per-function-call basis,
7743: not padding for individual arguments.
7744:
1.1.1.7 ! root 7745: The argument @var{size} will be a C variable of type @code{struct
! 7746: arg_data} which contains two fields, an integer named @code{constant}
! 7747: and an RTX named @code{var}. These together represent a size measured
! 7748: in bytes which is the sum of the integer and the RTX. Most of the
! 7749: time @code{var} is 0, which means that the size is simply the integer.
! 7750:
! 7751: The definition should be a C statement or compound statement
! 7752: which alters the variable supplied in whatever way you wish.
! 7753:
! 7754: Note that the value you leave in the variable @code{size} will
! 7755: ultimately be rounded up to a multiple of @code{STACK_BOUNDARY} bits.
! 7756:
! 7757: This macro is not fully implemented for machines which have push
! 7758: instructions (i.e., on which @code{PUSH_ROUNDING} is defined).
1.1.1.6 root 7759:
1.1 root 7760: @item RETURN_POPS_ARGS (@var{funtype})
7761: A C expression that should be 1 if a function pops its own arguments
7762: on returning, or 0 if the function pops no arguments and the caller
7763: must therefore pop them all after the function returns.
7764:
7765: @var{funtype} is a C variable whose value is a tree node that
7766: describes the function in question. Normally it is a node of type
7767: @code{FUNCTION_TYPE} that describes the data type of the function.
7768: From this it is possible to obtain the data types of the value and
7769: arguments (if known).
7770:
7771: When a call to a library function is being considered, @var{funtype}
7772: will contain an identifier node for the library function. Thus, if
7773: you need to distinguish among various library functions, you can do so
7774: by their names. Note that ``library function'' in this context means
7775: a function used to perform arithmetic, whose name is known specially
7776: in the compiler and was not mentioned in the C code being compiled.
7777:
7778: On the Vax, all functions always pop their arguments, so the
7779: definition of this macro is 1. On the 68000, using the standard
7780: calling convention, no functions pop their arguments, so the value of
7781: the macro is always 0 in this case. But an alternative calling
7782: convention is available in which functions that take a fixed number of
7783: arguments pop them but other functions (such as @code{printf}) pop
7784: nothing (the caller pops all). When this convention is in use,
7785: @var{funtype} is examined to determine whether a function takes a
7786: fixed number of arguments.
7787:
7788: @item FUNCTION_VALUE (@var{valtype}, @var{func})
7789: A C expression to create an RTX representing the place where a
7790: function returns a value of data type @var{valtype}. @var{valtype} is
7791: a tree node representing a data type. Write @code{TYPE_MODE
7792: (@var{valtype})} to get the machine mode used to represent that type.
7793: On many machines, only the mode is relevant. (Actually, on most
7794: machines, scalar values are returned in the same place regardless of
7795: mode).@refill
7796:
7797: If the precise function being called is known, @var{func} is a tree
7798: node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
7799: pointer. This makes it possible to use a different value-returning
7800: convention for specific functions when all their calls are
7801: known.@refill
7802:
7803: @item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func})
7804: Define this macro if the target machine has ``register windows''
7805: so that the register in which a function returns its value is not
7806: the same as the one in which the caller sees the value.
7807:
7808: For such machines, @code{FUNCTION_VALUE} computes the register in
7809: which the caller will see the value, and
7810: @code{FUNCTION_OUTGOING_VALUE} should be defined in a similar fashion
7811: to tell the function where to put the value.@refill
7812:
7813: If @code{FUNCTION_OUTGOING_VALUE} is not defined,
7814: @code{FUNCTION_VALUE} serves both purposes.@refill
7815:
1.1.1.7 ! root 7816: @item RETURN_IN_MEMORY (@var{type})
! 7817: A C expression which can inhibit the returning of certain function
! 7818: values in registers, based on the type of value. A nonzero value says
! 7819: to return the function value in memory, just as large structures are
! 7820: always returned. Here @var{type} will be a C expression of type
! 7821: @code{tree}, representing the data type of the value.
! 7822:
! 7823: Note that values of mode @code{BLKmode} are returned in memory
! 7824: regardless of this macro. Also, the option @samp{-fpcc-struct-return}
! 7825: takes effect regardless of this macro. On most systems, it is
! 7826: possible to leave the macro undefined; this causes a default
! 7827: definition to be used, whose value is the constant 0.
! 7828:
1.1 root 7829: @item LIBCALL_VALUE (@var{mode})
7830: A C expression to create an RTX representing the place where a library
7831: function returns a value of mode @var{mode}. If the precise function
7832: being called is known, @var{func} is a tree node
7833: (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
7834: pointer. This makes it possible to use a different value-returning
7835: convention for specific functions when all their calls are
7836: known.@refill
7837:
7838: Note that ``library function'' in this context means a compiler
7839: support routine, used to perform arithmetic, whose name is known
7840: specially by the compiler and was not mentioned in the C code being
7841: compiled.
7842:
7843: @item FUNCTION_VALUE_REGNO_P (@var{regno})
7844: A C expression that is nonzero if @var{regno} is the number of a hard
7845: register in which the values of called function may come back.
7846:
7847: A register whose use for returning values is limited to serving as the
7848: second of a pair (for a value of type @code{double}, say) need not be
7849: recognized by this macro. So for most machines, this definition
7850: suffices:
7851:
7852: @example
7853: #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
7854: @end example
7855:
7856: If the machine has register windows, so that the caller and the called
7857: function use different registers for the return value, this macro
7858: should recognize only the caller's register numbers.
7859:
7860: @item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
7861: A C expression that controls whether a function argument is passed
7862: in a register, and which register.
7863:
7864: The arguments are @var{cum}, which summarizes all the previous
7865: arguments; @var{mode}, the machine mode of the argument; @var{type},
7866: the data type of the argument as a tree node or 0 if that is not known
7867: (which happens for C support library functions); and @var{named},
7868: which is 1 for an ordinary argument and 0 for nameless arguments that
7869: correspond to @samp{...} in the called function's prototype.
7870:
7871: The value of the expression should either be a @samp{reg} RTX for the
7872: hard register in which to pass the argument, or zero to pass the
7873: argument on the stack.
7874:
7875: For the Vax and 68000, where normally all arguments are pushed, zero
7876: suffices as a definition.
7877:
7878: @item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
7879: Define this macro if the target machine has ``register windows'', so
7880: that the register in which a function sees an arguments is not
7881: necessarily the same as the one in which the caller passed the
7882: argument.
7883:
7884: For such machines, @code{FUNCTION_ARG} computes the register in which
7885: the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should
7886: be defined in a similar fashion to tell the function being called
7887: where the arguments will arrive.
7888:
7889: If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG}
7890: serves both purposes.@refill
7891:
7892: @item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named})
7893: A C expression for the number of words, at the beginning of an
7894: argument, must be put in registers. The value must be zero for
7895: arguments that are passed entirely in registers or that are entirely
7896: pushed on the stack.
7897:
7898: On some machines, certain arguments must be passed partially in
7899: registers and partially in memory. On these machines, typically the
7900: first @var{n} words of arguments are passed in registers, and the rest
7901: on the stack. If a multi-word argument (a @code{double} or a
7902: structure) crosses that boundary, its first few words must be passed
7903: in registers and the rest must be pushed. This macro tells the
7904: compiler when this occurs, and how many of the words should go in
7905: registers.
7906:
7907: @code{FUNCTION_ARG} for these arguments should return the first
7908: register to be used by the caller for this argument; likewise
7909: @code{FUNCTION_INCOMING_ARG}, for the called function.
7910:
7911: @item CUMULATIVE_ARGS
7912: A C type for declaring a variable that is used as the first argument
7913: of @code{FUNCTION_ARG} and other related values. For some target
7914: machines, the type @code{int} suffices and can hold the number of
7915: bytes of argument so far.
7916:
7917: @item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype})
7918: A C statement (sans semicolon) for initializing the variable @var{cum}
7919: for the state at the beginning of the argument list. The variable has
7920: type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node
7921: for the data type of the function which will receive the args, or 0
7922: if the args are to a compiler support library function.
7923:
7924: @item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named})
1.1.1.7 ! root 7925: A C statement (sans semicolon) to update the summarizer variable
! 7926: @var{cum} to advance past an argument in the argument list. The
! 7927: values @var{mode}, @var{type} and @var{named} describe that argument.
! 7928: Once this is done, the variable @var{cum} is suitable for analyzing
! 7929: the @emph{following} argument with @code{FUNCTION_ARG}, etc.@refill
1.1 root 7930:
7931: @item FUNCTION_ARG_REGNO_P (@var{regno})
7932: A C expression that is nonzero if @var{regno} is the number of a hard
7933: register in which function arguments are sometimes passed. This does
7934: @emph{not} include implicit arguments such as the static chain and
7935: the structure-value address. On many machines, no registers can be
7936: used for this purpose since all function arguments are pushed on the
7937: stack.
7938:
7939: @item FUNCTION_ARG_PADDING (@var{mode}, @var{size})
7940: If defined, a C expression which determines whether, and in which direction,
7941: to pad out an argument with extra space. The value should be of type
7942: @code{enum direction}: either @code{upward} to pad above the argument,
7943: @code{downward} to pad below, or @code{none} to inhibit padding.
7944:
7945: The argument @var{size} is an RTX which describes the size of the
7946: argument, in bytes. It should be used only if @var{mode} is
7947: @code{BLKmode}. Otherwise, @var{size} is 0.
7948:
7949: This macro does not control the @emph{amount} of padding; that is
7950: always just enough to reach the next multiple of @code{PARM_BOUNDARY}.
7951:
7952: This macro has a default definition which is right for most systems.
7953: For little-endian machines, the default is to pad upward. For
7954: big-endian machines, the default is to pad downward for an argument of
7955: constant size shorter than an @code{int}, and upward otherwise.
7956:
7957: @item FUNCTION_PROLOGUE (@var{file}, @var{size})
7958: A C compound statement that outputs the assembler code for entry to a
7959: function. The prologue is responsible for setting up the stack frame,
7960: initializing the frame pointer register, saving registers that must be
7961: saved, and allocating @var{size} additional bytes of storage for the
7962: local variables. @var{size} is an integer. @var{file} is a stdio
7963: stream to which the assembler code should be output.
7964:
7965: The label for the beginning of the function need not be output by this
7966: macro. That has already been done when the macro is run.
7967:
7968: To determine which registers to save, the macro can refer to the array
7969: @code{regs_ever_live}: element @var{r} is nonzero if hard register
7970: @var{r} is used anywhere within the function. This implies the
7971: function prologue should save register @var{r}, but not if it is one
7972: of the call-used registers.
7973:
7974: On machines where functions may or may not have frame-pointers, the
7975: function entry code must vary accordingly; it must set up the frame
7976: pointer if one is wanted, and not otherwise. To determine whether a
7977: frame pointer is in wanted, the macro can refer to the variable
7978: @code{frame_pointer_needed}. The variable's value will be 1 at run
7979: time in a function that needs a frame pointer.
7980:
7981: @item FUNCTION_PROFILER (@var{file}, @var{labelno})
7982: A C statement or compound statement to output to @var{file} some
7983: assembler code to call the profiling subroutine @code{mcount}.
7984: Before calling, the assembler code must load the address of a
7985: counter variable into a register where @code{mcount} expects to
7986: find the address. The name of this variable is @samp{LP} followed
7987: by the number @var{labelno}, so you would generate the name using
7988: @samp{LP%d} in a @code{fprintf}.
7989:
7990: The details of how the address should be passed to @code{mcount} are
7991: determined by your operating system environment, not by GNU CC. To
7992: figure them out, compile a small program for profiling using the
7993: system's installed C compiler and look at the assembler code that
7994: results.
7995:
1.1.1.6 root 7996: @item FUNCTION_BLOCK_PROFILER (@var{file}, @var{labelno})
7997: A C statement or compound statement to output to @var{file} some
7998: assembler code to initialize basic-block profiling for the current
7999: object module. This code should call the subroutine
8000: @code{__bb_init_func} once per object module, passing it as its sole
8001: argument the address of a block allocated in the object module.
8002:
8003: The name of the block is a local symbol made with this statement:
8004:
8005: @example
8006: ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 0);
8007: @end example
8008:
8009: Of course, since you are writing the definition of
8010: @code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you
8011: can take a short cut in the definition of this macro and use the name
8012: that you know will result.
8013:
8014: The first word of this block is a flag which will be nonzero if the
8015: object module has already been initialized. So test this word first,
8016: and do not call @code{__bb_init_func} if the flag is nonzero.
8017:
8018: @item BLOCK_PROFILER (@var{file}, @var{blockno})
8019: A C statement or compound statement to increment the count associated
8020: with the basic block number @var{blockno}. Basic blocks are numbered
8021: separately from zero within each compilation. The count associated
8022: with block number @var{blockno} is at index @var{blockno} in a vector
8023: of words; the name of this array is a local symbol made with this
8024: statement:
8025:
8026: @example
8027: ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 2);
8028: @end example
8029:
8030: Of course, since you are writing the definition of
8031: @code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you
8032: can take a short cut in the definition of this macro and use the name
8033: that you know will result.
8034:
1.1 root 8035: @item EXIT_IGNORES_STACK
8036: Define this macro as a C expression that is nonzero if the return
8037: instruction or the function epilogue ignores the value of the stack
8038: pointer; in other words, if it is safe to delete an instruction to
8039: adjust the stack pointer before a return from the function.
8040:
8041: Note that this macro's value is relevant only for for which frame
8042: pointers are maintained. It is never possible to delete a final stack
8043: adjustment in a function that has no frame pointer, and the compiler
8044: knows this regardless of @code{EXIT_IGNORES_STACK}.
8045:
8046: @item FUNCTION_EPILOGUE (@var{file}, @var{size})
8047: A C compound statement that outputs the assembler code for exit from a
8048: function. The epilogue is responsible for restoring the saved
8049: registers and stack pointer to their values when the function was
8050: called, and returning control to the caller. This macro takes the
8051: same arguments as the macro @code{FUNCTION_PROLOGUE}, and the
8052: registers to restore are determined from @code{regs_ever_live} and
8053: @code{CALL_USED_REGISTERS} in the same way.
8054:
8055: On some machines, there is a single instruction that does all the work
8056: of returning from the function. On these machines, give that
8057: instruction the name @samp{return} and do not define the macro
8058: @code{FUNCTION_EPILOGUE} at all.
8059:
8060: Do not define a pattern named @samp{return} if you want the
8061: @code{FUNCTION_EPILOGUE} to be used. If you want the target switches
8062: to control whether return instructions or epilogues are used, define a
8063: @samp{return} pattern with a validity condition that tests the target
8064: switches appropriately. If the @samp{return} pattern's validity
8065: condition is false, epilogues will be used.
8066:
8067: On machines where functions may or may not have frame-pointers, the
8068: function exit code must vary accordingly. Sometimes the code for
8069: these two cases is completely different. To determine whether a frame
8070: pointer is in wanted, the macro can refer to the variable
8071: @code{frame_pointer_needed}. The variable's value will be 1 at run
8072: time in a function that needs a frame pointer.
8073:
8074: On some machines, some functions pop their arguments on exit while
8075: others leave that for the caller to do. For example, the 68020 when
8076: given @samp{-mrtd} pops arguments in functions that take a fixed
8077: number of arguments.
8078:
8079: Your definition of the macro @code{RETURN_POPS_ARGS} decides which
8080: functions pop their own arguments. @code{FUNCTION_EPILOGUE} needs to
8081: know what was decided. The variable @code{current_function_pops_args}
8082: is nonzero if the function should pop its own arguments. If so, use
8083: the variable @code{current_function_args_size} as the number of bytes
8084: to pop.
8085:
8086: @item FIX_FRAME_POINTER_ADDRESS (@var{addr}, @var{depth})
8087: A C compound statement to alter a memory address that uses the frame
8088: pointer register so that it uses the stack pointer register instead.
8089: This must be done in the instructions that load parameter values into
8090: registers, when the reload pass determines that a frame pointer is not
8091: necessary for the function. @var{addr} will be a C variable name, and
8092: the updated address should be stored in that variable. @var{depth}
8093: will be the current depth of stack temporaries (number of bytes of
8094: arguments currently pushed). The change in offset between a
8095: frame-pointer-relative address and a stack-pointer-relative address
8096: must include @var{depth}.
8097:
8098: Even if your machine description specifies there will always be a
8099: frame pointer in the frame pointer register, you must still define
8100: @code{FIX_FRAME_POINTER_ADDRESS}, but the definition will never be
8101: executed at run time, so it may be empty.
8102: @end table
8103:
8104: @node Library Names, Addressing Modes, Stack Layout, Machine Macros
8105: @section Library Subroutine Names
8106:
8107: @table @code
1.1.1.5 root 8108: @item MULSI3_LIBCALL
8109: A C string constant giving the name of the function to call for
8110: multiplication of one signed full-word by another. If you do not
8111: define this macro, the default name is used, which is @code{__mulsi3},
8112: a function defined in @file{gnulib}.
8113:
8114: @item UMULSI3_LIBCALL
8115: A C string constant giving the name of the function to call for
8116: multiplication of one unsigned full-word by another. If you do not
8117: define this macro, the default name is used, which is
8118: @code{__umulsi3}, a function defined in @file{gnulib}.
8119:
8120: @item DIVSI3_LIBCALL
8121: A C string constant giving the name of the function to call for
8122: division of one signed full-word by another. If you do not define
8123: this macro, the default name is used, which is @code{__divsi3}, a
8124: function defined in @file{gnulib}.
8125:
1.1 root 8126: @item UDIVSI3_LIBCALL
8127: A C string constant giving the name of the function to call for
1.1.1.5 root 8128: division of one unsigned full-word by another. If you do not define
8129: this macro, the default name is used, which is @code{__udivsi3}, a
8130: function defined in @file{gnulib}.
8131:
8132: @item MODSI3_LIBCALL
8133: A C string constant giving the name of the function to call for the
8134: remainder in division of one signed full-word by another. If you do
8135: not define this macro, the default name is used, which is
8136: @code{__modsi3}, a function defined in @file{gnulib}.
1.1 root 8137:
8138: @item UMODSI3_LIBCALL
8139: A C string constant giving the name of the function to call for the
1.1.1.5 root 8140: remainder in division of one unsigned full-word by another. If you do
8141: not define this macro, the default name is used, which is
8142: @code{__umodsi3}, a function defined in @file{gnulib}.
1.1 root 8143:
8144: @item TARGET_MEM_FUNCTIONS
8145: Define this macro if GNU CC should generate calls to the System V
8146: (and ANSI C) library functions @code{memcpy} and @code{memset}
8147: rather than the BSD functions @code{bcopy} and @code{bzero}.
8148: @end table
8149:
1.1.1.5 root 8150: @node Addressing Modes, Cross-compilation, Library Names, Machine Macros
1.1 root 8151: @section Addressing Modes
8152:
8153: @table @code
8154: @item HAVE_POST_INCREMENT
8155: Define this macro if the machine supports post-increment addressing.
8156:
8157: @item HAVE_PRE_INCREMENT
8158: @itemx HAVE_POST_DECREMENT
8159: @itemx HAVE_PRE_DECREMENT
8160: Similar for other kinds of addressing.
8161:
8162: @item CONSTANT_ADDRESS_P (@var{x})
8163: A C expression that is 1 if the RTX @var{x} is a constant whose value
8164: is an integer. This includes integers whose values are not explicitly
8165: known, such as @samp{symbol_ref} and @samp{label_ref} expressions and
8166: @samp{const} arithmetic expressions.
8167:
8168: On most machines, this can be defined as @code{CONSTANT_P (@var{x})},
8169: but a few machines are more restrictive in which constant addresses
8170: are supported.
8171:
8172: @item MAX_REGS_PER_ADDRESS
8173: A number, the maximum number of registers that can appear in a valid
8174: memory address.
8175:
8176: @item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label})
8177: A C compound statement with a conditional @code{goto @var{label};}
8178: executed if @var{x} (an RTX) is a legitimate memory address on the
8179: target machine for a memory operand of mode @var{mode}.
8180:
8181: It usually pays to define several simpler macros to serve as
8182: subroutines for this one. Otherwise it may be too complicated to
8183: understand.
8184:
8185: This macro must exist in two variants: a strict variant and a
8186: non-strict one. The strict variant is used in the reload pass. It
8187: must be defined so that any pseudo-register that has not been
8188: allocated a hard register is considered a memory reference. In
8189: contexts where some kind of register is required, a pseudo-register
8190: with no hard register must be rejected.
8191:
8192: The non-strict variant is used in other passes. It must be defined to
8193: accept all pseudo-registers in every context where some kind of
8194: register is required.
8195:
8196: Compiler source files that want to use the strict variant of this
8197: macro define the macro @code{REG_OK_STRICT}. You should use an
8198: @code{#ifdef REG_OK_STRICT} conditional to define the strict variant
8199: in that case and the non-strict variant otherwise.
8200:
8201: Typically among the subroutines used to define
8202: @code{GO_IF_LEGITIMATE_ADDRESS} are subroutines to check for
8203: acceptable registers for various purposes (one for base registers, one
8204: for index registers, and so on). Then only these subroutine macros
8205: need have two variants; the higher levels of macros may be the same
8206: whether strict or not.@refill
8207:
8208: @item REG_OK_FOR_BASE_P (@var{x})
1.1.1.5 root 8209: A C expression that is nonzero if @var{x} (assumed to be a @code{reg}
1.1 root 8210: RTX) is valid for use as a base register. For hard registers, it
8211: should always accept those which the hardware permits and reject the
8212: others. Whether the macro accepts or rejects pseudo registers must be
8213: controlled by @code{REG_OK_STRICT} as described above. This usually
8214: requires two variant definitions, of which @code{REG_OK_STRICT}
8215: controls the one actually used.
8216:
8217: @item REG_OK_FOR_INDEX_P (@var{x})
1.1.1.5 root 8218: A C expression that is nonzero if @var{x} (assumed to be a @code{reg}
1.1 root 8219: RTX) is valid for use as an index register.
8220:
8221: The difference between an index register and a base register is that
8222: the index register may be scaled. If an address involves the sum of
8223: two registers, neither one of them scaled, then either one may be
8224: labeled the ``base'' and the other the ``index''; but whichever
8225: labeling is used must fit the machine's constraints of which registers
8226: may serve in each capacity. The compiler will try both labelings,
8227: looking for one that is valid, and will reload one or both registers
8228: only if neither labeling works.
8229:
8230: @item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win})
8231: A C compound statement that attempts to replace @var{x} with a valid
8232: memory address for an operand of mode @var{mode}. @var{win} will be a
8233: C statement label elsewhere in the code; the macro definition may use
8234:
8235: @example
8236: GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win});
8237: @end example
8238:
8239: @noindent
8240: to avoid further processing if the address has become legitimate.
8241:
8242: @var{x} will always be the result of a call to @code{break_out_memory_refs},
8243: and @var{oldx} will be the operand that was given to that function to produce
8244: @var{x}.
8245:
8246: The code generated by this macro should not alter the substructure of
8247: @var{x}. If it transforms @var{x} into a more legitimate form, it
8248: should assign @var{x} (which will always be a C variable) a new value.
8249:
8250: It is not necessary for this macro to come up with a legitimate
8251: address. The compiler has standard ways of doing so in all cases. In
8252: fact, it is safe for this macro to do nothing. But often a
8253: machine-dependent strategy can generate better code.
8254:
8255: @item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label})
8256: A C statement or compound statement with a conditional @code{goto
8257: @var{label};} executed if memory address @var{x} (an RTX) can have
8258: different meanings depending on the machine mode of the memory
8259: reference it is used for.
8260:
8261: Autoincrement and autodecrement addresses typically have mode-dependent
8262: effects because the amount of the increment or decrement is the size
8263: of the operand being addressed. Some machines have other mode-dependent
8264: addresses. Many RISC machines have no mode-dependent addresses.
8265:
8266: You may assume that @var{addr} is a valid address for the machine.
8267:
8268: @item LEGITIMATE_CONSTANT_P (@var{x})
8269: A C expression that is nonzero if @var{x} is a legitimate constant for
8270: an immediate operand on the target machine. You can assume that
8271: either @var{x} is a @samp{const_double} or it satisfies
8272: @code{CONSTANT_P}, so you need not check these things. In fact,
8273: @samp{1} is a suitable definition for this macro on machines where any
8274: @samp{const_double} is valid and anything @code{CONSTANT_P} is valid.@refill
8275: @end table
8276:
1.1.1.5 root 8277: @node Cross-compilation, Misc, Addressing Modes, Machine Macros
8278: @section Cross Compilation and Floating-Point Format
8279:
8280: While all modern machines use 2's compliment representation for integers,
8281: there are a variety of representations for floating point numbers. This
8282: means that in a cross-compiler the representation of floating point numbers
8283: in the compiled program may be different from that used in the machine
8284: doing the compilation.
8285:
8286: Because different representation systems may offer different amounts of
8287: range and precision, the cross compiler cannot safely use the host
8288: machine's floating point arithmetic. Therefore, floating point constants
8289: must be represented in the target machine's format. This means that the
8290: cross compiler cannot use @code{atof} to parse a floating point constant;
8291: it must have its own special routine to use instead. Also, constant
8292: folding must emulate the target machine's arithmetic (or must not be done
8293: at all).
8294:
8295: The macros in the following table should be defined only if you are cross
8296: compiling between different floating point formats.
8297:
8298: Otherwise, don't define them. Then default definitions will be set up which
8299: use @code{double} as the data type, @code{==} to test for equality, etc.
8300:
8301: You don't need to worry about how many times you use an operand of any
8302: of these macros. The compiler never uses operands which have side effects.
8303:
8304: @table @code
8305: @item REAL_VALUE_TYPE
8306: A macro for the C data type to be used to hold a floating point value
8307: in the target machine's format. Typically this would be a
8308: @code{struct} containing an array of @code{int}.
8309:
8310: @item REAL_VALUES_EQUAL (@var{x}, @var{y})
8311: A macro for a C expression which compares for equality the two values,
8312: @var{x} and @var{y}, both of type @code{REAL_VALUE_TYPE}.
8313:
8314: @item REAL_VALUES_LESS (@var{x}, @var{y})
8315: A macro for a C expression which tests whether @var{x} is less than
8316: @var{y}, both values being of type @code{REAL_VALUE_TYPE} and
8317: interpreted as floating point numbers in the target machine's
8318: representation.
8319:
8320: @item REAL_VALUE_LDEXP (@var{x}, @var{scale})
8321: A macro for a C expression which performs the standard library
8322: function @code{ldexp}, but using the target machine's floating point
8323: representation. Both @var{x} and the value of the expression have
8324: type @code{REAL_VALUE_TYPE}. The second argument, @var{scale}, is an
8325: integer.
8326:
8327: @item REAL_VALUE_ATOF (@var{string})
8328: A macro for a C expression which converts @var{string}, an expression
8329: of type @code{char *}, into a floating point number in the target
8330: machine's representation. The value has type @code{REAL_VALUE_TYPE}.
8331: @end table
8332:
8333: Define the following additional macros if you want to make floating
8334: point constant folding work while cross compiling. If you don't
8335: define them, cross compilation is still possible, but constant folding
8336: will not happen for floating point values.
8337:
8338: @table @code
8339: @item REAL_ARITHMETIC (@var{output}, @var{code}, @var{x}, @var{y})
8340: A macro for a C statement which calculates an arithmetic operation of
8341: the two floating point values @var{x} and @var{y}, both of type
8342: @code{REAL_VALUE_TYPE} in the target machine's representation, to
8343: produce a result of the same type and representation which is stored
8344: in @var{output} (which will be a variable).
8345:
8346: The operation to be performed is specified by @var{code}, a tree code
8347: which will always be one of the following: @code{PLUS_EXPR},
8348: @code{MINUS_EXPR}, @code{MULT_EXPR}, @code{RDIV_EXPR},
8349: @code{MAX_EXPR}, @code{MIN_EXPR}.@refill
8350:
8351: The expansion of this macro is responsible for checking for overflow.
8352: If overflow happens, the macro expansion should execute the statement
8353: @code{return 0;}, which indicates the inability to perform the
8354: arithmetic operation requested.
8355:
8356: @item REAL_VALUE_NEGATE (@var{x})
8357: A macro for a C expression which returns the negative of the floating
8358: point value @var{x}. Both @var{x} and the value of the expression
8359: have type @code{REAL_VALUE_TYPE} and are in the target machine's
8360: floating point representation.
8361:
8362: There is no way for this macro to report overflow, since overflow
8363: can't happen in the negation operation.
8364:
8365: @item REAL_VALUE_TO_INT (@var{low}, @var{high}, @var{x})
8366: A macro for a C expression which converts a floating point value
8367: @var{x} into a double-precision integer which is then stored into
8368: @var{low} and @var{high}, two variables of type @var{int}.
8369:
8370: @item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high})
8371: A macro for a C expression which converts a double-precision integer
8372: found in @var{low} and @var{high}, two variables of type @var{int},
8373: into a floating point value which is then stored into @var{x}.
8374: @end table
8375:
8376: @node Misc, Condition Code, Cross-compilation, Machine Macros
1.1 root 8377: @section Miscellaneous Parameters
8378:
8379: @table @code
8380: @item CASE_VECTOR_MODE
8381: An alias for a machine mode name. This is the machine mode that
8382: elements of a jump-table should have.
8383:
8384: @item CASE_VECTOR_PC_RELATIVE
8385: Define this macro if jump-tables should contain relative addresses.
8386:
8387: @item CASE_DROPS_THROUGH
8388: Define this if control falls through a @code{case} insn when the index
8389: value is out of range. This means the specified default-label is
8390: actually ignored by the @code{case} insn proper.
8391:
8392: @item IMPLICIT_FIX_EXPR
8393: An alias for a tree code that should be used by default for conversion
8394: of floating point values to fixed point. Normally,
8395: @code{FIX_ROUND_EXPR} is used.@refill
8396:
8397: @item FIXUNS_TRUNC_LIKE_FIX_TRUNC
8398: Define this macro if the same instructions that convert a floating
8399: point number to a signed fixed point number also convert validly to an
8400: unsigned one.
8401:
8402: @item EASY_DIV_EXPR
8403: An alias for a tree code that is the easiest kind of division to
8404: compile code for in the general case. It may be
8405: @code{TRUNC_DIV_EXPR}, @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or
8406: @code{ROUND_DIV_EXPR}. These four division operators differ in how
8407: they round the result to an integer. @code{EASY_DIV_EXPR} is used
8408: when it is permissible to use any of those kinds of division and the
8409: choice should be made on the basis of efficiency.@refill
8410:
8411: @item DEFAULT_SIGNED_CHAR
8412: An expression whose value is 1 or 0, according to whether the type
8413: @code{char} should be signed or unsigned by default. The user can
8414: always override this default with the options @samp{-fsigned-char}
8415: and @samp{-funsigned-char}.
8416:
8417: @item SCCS_DIRECTIVE
8418: Define this if the preprocessor should ignore @code{#sccs} directives
8419: and print no error message.
8420:
1.1.1.7 ! root 8421: @item HAVE_VPRINTF
! 8422: Define this if the library function @code{vprintf} is available on your
! 8423: system.
1.1 root 8424:
8425: @item MOVE_MAX
8426: The maximum number of bytes that a single instruction can move quickly
8427: from memory to memory.
8428:
8429: @item INT_TYPE_SIZE
8430: A C expression for the size in bits of the type @code{int} on the
8431: target machine.
8432:
8433: @item SLOW_BYTE_ACCESS
8434: Define this macro as a C expression which is nonzero if accessing less
8435: than a word of memory (i.e. a @code{char} or a @code{short}) is slow
8436: (requires more than one instruction).
8437:
8438: @item SLOW_ZERO_EXTEND
8439: Define this macro if zero-extension (of a @code{char} or @code{short}
8440: to an @code{int}) can be done faster if the destination is a register
8441: that is known to be zero.
8442:
8443: If you define this macro, you must have instruction patterns that
8444: recognize RTL structures like this:
8445:
8446: @example
8447: (set (strict-low-part (subreg:QI (reg:SI @dots{}) 0)) @dots{})
8448: @end example
8449:
8450: @noindent
8451: and likewise for @code{HImode}.
8452:
8453: @item SHIFT_COUNT_TRUNCATED
8454: Define this macro if shift instructions ignore all but the lowest few
8455: bits of the shift count. It implies that a sign-extend or zero-extend
8456: instruction for the shift count can be omitted.
8457:
8458: @item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec})
8459: A C expression which is nonzero if on this machine it is safe to
8460: ``convert'' an integer of @var{inprec} bits to one of @var{outprec}
8461: bits (where @var{outprec} is smaller than @var{inprec}) by merely
8462: operating on it as if it had only @var{outprec} bits.
8463:
8464: On many machines, this expression can be 1.
8465:
8466: @item NO_FUNCTION_CSE
8467: Define this macro if it is as good or better to call a constant
8468: function address than to call an address kept in a register.
8469:
8470: @item PROMOTE_PROTOTYPES
8471: Define this macro if an argument declared as @code{char} or
8472: @code{short} in a prototype should actually be passed as an
8473: @code{int}. In addition to avoiding errors in certain cases of
8474: mismatch, it also makes for better code on certain machines.
8475:
8476: @item STORE_FLAG_VALUE
8477: A C expression for the value stored by a store-flag instruction
8478: (@code{s@var{cond}}) when the condition is true. This is usually 1 or
8479: -1; it is required to be an odd number.
8480:
8481: Do not define @code{STORE_FLAG_VALUE} if the machine has no store-flag
8482: instructions.
8483:
8484: @item Pmode
8485: An alias for the machine mode for pointers. Normally the definition
8486: can be
8487:
8488: @example
8489: #define Pmode SImode
8490: @end example
8491:
8492: @item FUNCTION_MODE
8493: An alias for the machine mode used for memory references to functions
8494: being called, in @samp{call} RTL expressions. On most machines this
8495: should be @code{QImode}.
8496:
8497: @item INSN_MACHINE_INFO
8498: This macro should expand into a C structure type to use for the
8499: machine-dependent info field specified with the optional last argument
8500: in @samp{define_insn} and @samp{define_peephole} patterns. For example,
8501: it might expand into @samp{struct machine_info}; then it would be up
8502: to you to define this structure in the @file{tm.h} file.
8503:
8504: You do not need to define this macro if you do not write the optional
8505: last argument in any of the patterns in the machine description.
8506:
8507: @item CONST_COSTS (@var{x}, @var{code})
8508: A part of a C @code{switch} statement that describes the relative
8509: costs of constant RTL expressions. It must contain @code{case} labels
8510: for expression codes @samp{const_int}, @samp{const}, @samp{symbol_ref}, @samp{label_ref}
8511: and @samp{const_double}. Each case must ultimately reach a
8512: @code{return} statement to return the relative cost of the use of that
8513: kind of constant value in an expression. The cost may depend on the
8514: precise value of the constant, which is available for examination in
8515: @var{x}.
8516:
8517: @var{code} is the expression code---redundant, since it can be
8518: obtained with @code{GET_CODE (@var{x})}.
8519:
8520: @item DOLLARS_IN_IDENTIFIERS
8521: Define this to be nonzero if the character @samp{$} should be allowed
8522: by default in identifier names.
1.1.1.7 ! root 8523:
! 8524: @item USE_C_ALLOCA
! 8525: Define this macro to indicate that the compiler is running with the
! 8526: @code{alloca} implemented in C. This version of @code{alloca} can be
! 8527: found in the file @file{alloca.c}; to use it, you must also edit the
! 8528: @file{Makefile}.
! 8529:
! 8530: This macro, unlike most, describes the machine that the compiler is
! 8531: running on, rather than the one the compiler is compiling for.
! 8532: Therefore, it should be set in the @file{xm-@var{machine}.h} file
! 8533: rather than in the @file{xm-@var{machine}.h} file.
! 8534:
! 8535: If you do define this macro, you should probably do it as follows:
! 8536:
! 8537: @example
! 8538: #ifndef __GNUC__
! 8539: #define USE_C_ALLOCA
! 8540: #else
! 8541: #deifne alloca __builtin_alloca
! 8542: #endif
! 8543: @end example
! 8544:
! 8545: @noindent
! 8546: so that when the compiler is compiled with GNU CC it uses the more
! 8547: efficient built-in @code{alloca} function.
1.1 root 8548: @end table
8549:
8550: @node Condition Code, Assembler Format, Misc, Machine Macros
8551: @section Condition Code Information
8552:
8553: The file @file{conditions.h} defines a variable @code{cc_status} to
8554: describe how the condition code was computed (in case the interpretation of
8555: the condition code depends on the instruction that it was set by). This
8556: variable contains the RTL expressions on which the condition code is
8557: currently based, and several standard flags.
8558:
8559: Sometimes additional machine-specific flags must be defined in the machine
8560: description header file. It can also add additional machine-specific
8561: information by defining @code{CC_STATUS_MDEP}.
8562:
8563: @table @code
8564: @item CC_STATUS_MDEP
8565: C code for a data type which is used for declaring the @code{mdep}
8566: component of @code{cc_status}. It defaults to @code{int}.
8567:
8568: @item CC_STATUS_MDEP_INIT
8569: A C expression for the initial value of the @code{mdep} field. It
8570: defaults to 0.
8571:
8572: @item NOTICE_UPDATE_CC (@var{exp}, @var{insn})
8573: A C compound statement to set the components of @code{cc_status}
8574: appropriately for an insn @var{insn} whose body is @var{exp}. It is
8575: this macro's responsibility to recognize insns that set the condition
8576: code as a byproduct of other activity as well as those that explicitly
8577: set @code{(cc0)}.
8578:
8579: If there are insn that do not set the condition code but do alter
8580: other machine registers, this macro must check to see whether they
8581: invalidate the expressions that the condition code is recorded as
8582: reflecting. For example, on the 68000, insns that store in address
8583: registers do not set the condition code, which means that usually
8584: @code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such
8585: insns. But suppose that the previous insn set the condition code
8586: based on location @samp{a4@@(102)} and the current insn stores a new
8587: value in @samp{a4}. Although the condition code is not changed by
8588: this, it will no longer be true that it reflects the contents of
8589: @samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter
8590: @code{cc_status} in this case to say that nothing is known about the
8591: condition code value.
8592:
8593: The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal
8594: with the results of peephole optimization: insns whose patterns are
8595: @samp{parallel} RTXs containing various @samp{reg}, @samp{mem} or
8596: constants which are just the operands. The RTL structure of these
8597: insns is not sufficient to indicate what the insns actually do. What
8598: @code{NOTICE_UPDATE_CC} should do when it sees one is just to run
8599: @code{CC_STATUS_INIT}.
8600: @end table
8601:
8602: @node Assembler Format,, Condition Code, Machine Macros
8603: @section Output of Assembler Code
8604:
8605: @table @code
8606: @item ASM_SPEC
8607: A C string constant that tells the GNU CC driver program options to
8608: pass to the assembler. It can also specify how to translate options
8609: you give to GNU CC into options for GNU CC to pass to the assembler.
8610: See the file @file{tm-sun3.h} for an example of this.
8611:
8612: Do not define this macro if it does not need to do anything.
8613:
8614: @item LINK_SPEC
8615: A C string constant that tells the GNU CC driver program options to
8616: pass to the linker. It can also specify how to translate options you
8617: give to GNU CC into options for GNU CC to pass to the linker.
8618:
8619: Do not define this macro if it does not need to do anything.
8620:
8621: @item LIB_SPEC
8622: Another C string constant used much like @code{LINK_SPEC}. The difference
8623: between the two is that @code{LIBS_SPEC} is used at the end of the
8624: command given to the linker.
8625:
8626: If this macro is not defined, a default is provided that
8627: loads the standard C library from the usual place. See @file{gcc.c}.
8628:
8629: @item STARTFILE_SPEC
8630: Another C string constant used much like @code{LINK_SPEC}. The
8631: difference between the two is that @code{STARTFILE_SPEC} is used at
8632: the very beginning of the command given to the linker.
8633:
8634: If this macro is not defined, a default is provided that loads the
8635: standard C startup file from the usual place. See @file{gcc.c}.
8636:
1.1.1.7 ! root 8637: @item STANDARD_EXEC_PREFIX
! 8638: Define this macro as a C string constant if you wish to override the
! 8639: standard choice of @file{/usr/local/lib/gcc-} as the default prefix to
! 8640: try when searching for the executable files of the compiler.
! 8641:
! 8642: The prefix specified by the @samp{-B} option, if any, is tried before
! 8643: the default prefix. After the default prefix, if the executable is
! 8644: not found that way, @file{/usr/lib/gcc-} is tried next; then the
! 8645: directories in your search path for shell commands are searched.
! 8646:
1.1.1.4 root 8647: @item STANDARD_STARTFILE_PREFIX
8648: Define this macro as a C string constant if you wish to override the
1.1.1.7 ! root 8649: standard choice of @file{/usr/local/lib/} as the default prefix to try
! 8650: when searching for startup files such as @file{crt0.o}.
! 8651:
! 8652: In this search, all the prefixes tried for executable files are tried
! 8653: first. Then comes the default startfile prefix specified by this
! 8654: macro, followed by the prefixes @file{/lib/} and @file{/usr/lib/} as
! 8655: last resorts.
1.1.1.4 root 8656:
1.1 root 8657: @item ASM_FILE_START (@var{stream})
8658: A C expression which outputs to the stdio stream @var{stream}
8659: some appropriate text to go at the start of an assembler file.
8660:
8661: Normally this macro is defined to output a line containing
8662: @samp{#NO_APP}, which is a comment that has no effect on most
8663: assemblers but tells the GNU assembler that it can save time by not
8664: checking for certain assembler constructs.
8665:
8666: On systems that use SDB, it is necessary to output certain commands;
8667: see @file{tm-attasm.h}.
8668:
8669: @item ASM_APP_ON
8670: A C string constant for text to be output before each @code{asm}
8671: statement or group of consecutive ones. Normally this is
8672: @code{"#APP"}, which is a comment that has no effect on most
8673: assemblers but tells the GNU assembler that it must check the lines
8674: that follow for all valid assembler constructs.
8675:
8676: @item ASM_APP_OFF
8677: A C string constant for text to be output after each @code{asm}
8678: statement or group of consecutive ones. Normally this is
8679: @code{"#NO_APP"}, which tells the GNU assembler to resume making the
8680: time-saving assumptions that are valid for ordinary compiler output.
8681:
8682: @item TEXT_SECTION_ASM_OP
8683: A C string constant for the assembler operation that should precede
8684: instructions and read-only data. Normally @code{".text"} is right.
8685:
8686: @item DATA_SECTION_ASM_OP
8687: A C string constant for the assembler operation to identify the
8688: following data as writable initialized data. Normally @code{".data"}
8689: is right.
8690:
8691: @item REGISTER_NAMES
8692: A C initializer containing the assembler's names for the machine
8693: registers, each one as a C string constant. This is what translates
8694: register numbers in the compiler into assembler language.
8695:
8696: @item DBX_REGISTER_NUMBER (@var{regno})
8697: A C expression that returns the DBX register number for the compiler
8698: register number @var{regno}. In simple cases, the value of this
8699: expression may be @var{regno} itself. But sometimes there are some
8700: registers that the compiler knows about and DBX does not, or vice
8701: versa. In such cases, some register may need to have one number in
8702: the compiler and another for DBX.
8703:
8704: @item DBX_DEBUGGING_INFO
8705: Define this macro if GNU CC should produce debugging output for DBX
8706: in response to the @samp{-g} option.
8707:
8708: @item SDB_DEBUGGING_INFO
8709: Define this macro if GNU CC should produce debugging output for SDB
8710: in response to the @samp{-g} option.
8711:
8712: @item PUT_SDB_@var{op}
8713: Define these macros to override the assembler syntax for the special
8714: SDB assembler directives. See @file{sdbout.c} for a list of these
8715: macros and their arguments. If the standard syntax is used, you need
8716: not define them yourself.
8717:
8718: @item SDB_GENERATE_FAKE
8719: Define this macro to override the usual method of constructing a dummy
8720: name for anonymous structure and union types. See @file{sdbout.c} for
8721: more infomation.
8722:
8723: @item DBX_NO_XREFS
8724: Define this macro if DBX on your system does not support the construct
8725: @samp{xs@var{tagname}}. On some systems, this construct is used to
8726: describe a forward reference to a structure named @var{tagname}.
8727: On other systems, this construct is not supported at all.
8728:
8729: @item DBX_CONTIN_LENGTH
8730: A symbol name in DBX-format debugging information is normally
8731: continued (split into two separate @code{.stabs} directives) when it
8732: exceeds a certain length (by default, 80 characters). On some
8733: operating systems, DBX requires this splitting; on others, splitting
8734: must not be done. You can inhibit splitting by defining this macro
8735: with the value zero. You can override the default splitting-length by
8736: defining this macro as an expression for the length you desire.
8737:
8738: @item DBX_CONTIN_CHAR
8739: Normally continuation is indicated by adding a @samp{\} character to
8740: the end of a @code{.stabs} string when a continuation follows. To use
8741: a different character instead, define this macro as a character
8742: constant for the character you want to use. Do not define this macro
8743: if backslash is correct for your system.
8744:
8745: @item ASM_OUTPUT_LABEL (@var{stream}, @var{name})
8746: A C statement (sans semicolon) to output to the stdio stream
8747: @var{stream} the assembler definition of a label named @var{name}. Use
8748: the expression @code{assemble_name (@var{stream}, @var{name})} to output
8749: the name itself; before and after that, output the additional
8750: assembler syntax for defining the name, and a newline.
8751:
8752: @item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl})
8753: A C statement (sans semicolon) to output to the stdio stream
8754: @var{stream} any text necessary for declaring the name @var{name} of a
8755: function which is being defined. This macro is responsible for
8756: outputting the label definition (perhaps using
8757: @code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the
8758: @code{FUNCTION_DECL} tree node representing the function.
8759:
8760: If this macro is not defined, then the function name is defined in the
8761: usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
8762:
8763: @item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name})
8764: A C statement (sans semicolon) to output to the stdio stream
8765: @var{stream} some commands that will make the label @var{name} global;
8766: that is, available for reference from other files. Use the expression
8767: @code{assemble_name (@var{stream}, @var{name})} to output the name
8768: itself; before and after that, output the additional assembler syntax
8769: for making that name global, and a newline.
8770:
8771: @item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{name}, @var{decl})
8772: A C statement (sans semicolon) to output to the stdio stream
8773: @var{stream} any text necessary for declaring the name of an external
8774: symbol named @var{name} which is referenced in this compilation but
8775: not defined. The value of @var{decl} is the tree node for the
8776: declaration.
8777:
8778: This macro need not be defined if it does not need to output anything.
8779: The GNU assembler and most Unix assemblers don't require anything.
8780:
8781: @item ASM_OUTPUT_LABELREF (@var{stream}, @var{name})
8782: A C statement to output to the stdio stream @var{stream} a reference in
8783: assembler syntax to a label named @var{name}. The character @samp{_}
8784: should be added to the front of the name, if that is customary on your
8785: operating system, as it is in most Berkeley Unix systems. This macro
8786: is used in @code{assemble_name}.
8787:
8788: @item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num})
8789: A C statement to store into the string @var{string} a label whose
8790: name is made from the string @var{prefix} and the number @var{num}.
8791:
8792: This string, when output subsequently by @code{ASM_OUTPUT_LABELREF},
8793: should produce the same output that @code{ASM_OUTPUT_INTERNAL_LABEL}
8794: would produce with the same @var{prefix} and @var{num}.
8795:
8796: @item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num})
8797: A C statement to output to the stdio stream @var{stream} a label whose
8798: name is made from the string @var{prefix} and the number @var{num}.
8799: These labels are used for internal purposes, and there is no reason
8800: for them to appear in the symbol table of the object file. On many
8801: systems, the letter @samp{L} at the beginning of a label has this
8802: effect. The usual definition of this macro is as follows:
8803:
8804: @example
8805: fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num})
8806: @end example
8807:
8808: @item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table})
8809: Define this if the label before a jump-table needs to be output
8810: specially. The first three arguments are the same as for
8811: @code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the
8812: jump-table which follows (a @samp{jump_insn} containing an
8813: @samp{addr_vec} or @samp{addr_diff_vec}).
8814:
8815: This feature is used on system V to output a @code{swbeg} statement
8816: for the table.
8817:
8818: If this macro is not defined, these labels are output with
8819: @code{ASM_OUTPUT_INTERNAL_LABEL}.
8820:
8821: @item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table})
8822: Define this if something special must be output at the end of a jump-table.
8823: The definition should be a C statement to be executed after the assembler
8824: code for the table is written. It should write the appropriate code to
8825: stdio stream @var{stream}. The argument @var{table} is the jump-table
8826: insn, and @var{num} is the label-number of the preceding label.
8827:
8828: If this macro is not defined, nothing special is output at the end of
8829: the jump-table.
8830:
1.1.1.4 root 8831: @item ASM_OUTPUT_ALIGN_CODE (@var{file})
8832: A C expression to output text to align the location counter in the way
8833: that is desirable at a point in the code that is reached only by
8834: jumping.
8835:
8836: This macro need not be defined if you don't want any special alignment
8837: to be done at such a time. Most machine descriptions do not currently
8838: define the macro.
8839:
1.1 root 8840: @item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number})
8841: A C expression to assign to @var{outvar} (which is a variable of type
8842: @code{char *}) a newly allocated string made from the string
8843: @var{name} and the number @var{number}, with some suitable punctuation
8844: added. Use @code{alloca} to get space for the string.
8845:
8846: This string will be used as the argument to @code{ASM_OUTPUT_LABELREF}
8847: to produce an assembler label for an internal static variable whose
8848: name is @var{name}. Therefore, the string must be such as to result
8849: in valid assembler code. The argument @var{number} is different each
8850: time this macro is executed; it prevents conflicts between
8851: similarly-named internal static variables in different scopes.
8852:
8853: Ideally this string should not be a valid C identifier, to prevent any
8854: conflict with the user's own symbols. Most assemblers allow periods
8855: or percent signs in assembler symbols; putting at least one of these
8856: between the name and the number will suffice.
8857:
8858: @item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno})
8859: A C expression to output to @var{stream} some assembler code
8860: which will push hard register number @var{regno} onto the stack.
8861: The code need not be optimal, since this macro is used only when
8862: profiling.
8863:
8864: @item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno})
8865: A C expression to output to @var{stream} some assembler code
8866: which will pop hard register number @var{regno} off of the stack.
8867: The code need not be optimal, since this macro is used only when
8868: profiling.
8869:
8870: @item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{value}, @var{rel})
8871: This macro should be provided on machines where the addresses
8872: in a dispatch table are relative to the table's own address.
8873:
8874: The definition should be a C statement to output to the stdio stream
8875: @var{stream} an assembler pseudo-instruction to generate a difference
8876: between two labels. @var{value} and @var{rel} are the numbers of two
8877: internal labels. The definitions of these labels are output using
8878: @code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same
8879: way here. For example,
8880:
8881: @example
8882: fprintf (@var{stream}, "\t.word L%d-L%d\n",
8883: @var{value}, @var{rel})
8884: @end example
8885:
8886: @item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value})
8887: This macro should be provided on machines where the addresses
8888: in a dispatch table are absolute.
8889:
8890: The definition should be a C statement to output to the stdio stream
8891: @var{stream} an assembler pseudo-instruction to generate a reference to
8892: a label. @var{value} is the number of an internal label whose
8893: definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}.
8894: For example,
8895:
8896: @example
8897: fprintf (@var{stream}, "\t.word L%d\n", @var{value})
8898: @end example
8899:
8900: @item ASM_OUTPUT_DOUBLE (@var{stream}, @var{value})
8901: A C statement to output to the stdio stream @var{stream} an assembler
8902: instruction to assemble a @code{double} constant whose value is
8903: @var{value}. @var{value} will be a C expression of type
8904: @code{double}.
8905:
8906: @item ASM_OUTPUT_FLOAT (@var{stream}, @var{value})
8907: A C statement to output to the stdio stream @var{stream} an assembler
8908: instruction to assemble a @code{float} constant whose value is
8909: @var{value}. @var{value} will be a C expression of type @code{float}.
8910:
8911: @item ASM_OUTPUT_INT (@var{stream}, @var{exp})
8912: @itemx ASM_OUTPUT_SHORT (@var{stream}, @var{exp})
8913: @itemx ASM_OUTPUT_CHAR (@var{stream}, @var{exp})
8914: A C statement to output to the stdio stream @var{stream} an assembler
8915: instruction to assemble a @code{int}, @code{short} or @code{char}
8916: constant whose value is @var{value}. The argument @var{exp} will be
8917: an RTL expression which represents a constant value. Use
8918: @samp{output_addr_const (@var{exp})} to output this value as an
8919: assembler expression.@refill
8920:
8921: @item ASM_OUTPUT_BYTE (@var{stream}, @var{value})
8922: A C statement to output to the stdio stream @var{stream} an assembler
8923: instruction to assemble a single byte containing the number @var{value}.
8924:
8925: @item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len})
8926: A C statement to output to the stdio stream @var{stream} an assembler
8927: instruction to assemble a string constant containing the @var{len}
8928: bytes at @var{ptr}. @var{ptr} will be a C expression of type
8929: @code{char *} and @var{len} a C expression of type @code{int}.
8930:
8931: If the assembler has a @code{.ascii} pseudo-op as found in the
8932: Berkeley Unix assembler, do not define the macro
8933: @code{ASM_OUTPUT_ASCII}.
8934:
8935: @item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes})
8936: A C statement to output to the stdio stream @var{stream} an assembler
8937: instruction to advance the location counter by @var{nbytes} bytes.
8938: @var{nbytes} will be a C expression of type @code{int}.
8939:
8940: @item ASM_OUTPUT_ALIGN (@var{stream}, @var{power})
8941: A C statement to output to the stdio stream @var{stream} an assembler
8942: instruction to advance the location counter to a multiple of 2 to the
8943: @var{power} bytes. @var{power} will be a C expression of type @code{int}.
8944:
1.1.1.7 ! root 8945: @item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded})
1.1 root 8946: A C statement (sans semicolon) to output to the stdio stream
1.1.1.7 ! root 8947: @var{stream} the assembler definition of a common-label named
! 8948: @var{name} whose size is @var{size} bytes. The variable @var{rounded}
! 8949: is the size rounded up to whatever alignment the caller wants.
! 8950:
! 8951: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
! 8952: output the name itself; before and after that, output the additional
! 8953: assembler syntax for defining the name, and a newline.
1.1 root 8954:
8955: This macro controls how the assembler definitions of uninitialized
8956: global variables are output.
8957:
1.1.1.7 ! root 8958: @item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded})
1.1 root 8959: A C statement (sans semicolon) to output to the stdio stream
8960: @var{stream} the assembler definition of a local-common-label named
1.1.1.7 ! root 8961: @var{name} whose size is @var{size} bytes. The variable @var{rounded}
! 8962: is the size rounded up to whatever alignment the caller wants.
! 8963:
! 8964: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
! 8965: output the name itself; before and after that, output the additional
! 8966: assembler syntax for defining the name, and a newline.
1.1 root 8967:
8968: This macro controls how the assembler definitions of uninitialized
8969: static variables are output.
8970:
8971: @item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line})
8972: A C statment to output DBX or SDB debugging information before code
8973: for line number @var{line} of the current source file to the
8974: stdio stream @var{stream}.
8975:
8976: This macro need not be defined if the standard form of debugging
8977: information for the debugger in use is appropriate.
8978:
8979: @item ASM_OUTPUT_IDENT (@var{stream}, @var{string})
8980: A C statement to output something to the assembler file to handle a
8981: @samp{#ident} directive containing the text @var{string}. If this
1.1.1.7 ! root 8982: macro is not defined, nothing is output for a @samp{#ident} directive.
1.1 root 8983:
8984: @item TARGET_BELL
8985: A C constant expression for the integer value for escape sequence
8986: @samp{\a}.
8987:
8988: @item TARGET_BS
8989: @itemx TARGET_TAB
8990: @itemx TARGET_NEWLINE
8991: C constant expressions for the integer values for escape sequences
8992: @samp{\b}, @samp{\t} and @samp{\n}.
8993:
8994: @item TARGET_VT
8995: @itemx TARGET_FF
8996: @itemx TARGET_CR
8997: C constant expressions for the integer values for escape sequences
8998: @samp{\v}, @samp{\f} and @samp{\r}.
8999:
9000: @item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr})
9001: Define this macro if you are using an unusual assembler that
9002: requires different names for the machine instructions.
9003:
9004: The definition is a C statement or statements which output an
9005: assembler instruction opcode to the stdio stream @var{stream}. The
9006: macro-operand @var{ptr} is a variable of type @code{char *} which
9007: points to the opcode name in its ``internal'' form---the form that is
9008: written in the machine description. The definition should output the
9009: opcode name to @var{stream}, performing any translation you desire, and
9010: increment the variable @var{ptr} to point at the end of the opcode
9011: so that it will not be output twice.
9012:
9013: In fact, your macro definition may process less than the entire opcode
9014: name, or more than the opcode name; but if you want to process text
9015: that includes @samp{%}-sequences to substitute operands, you must take
9016: care of the substitution yourself. Just be sure to increment
9017: @var{ptr} over whatever text should not be output normally.
9018:
9019: If the macro definition does nothing, the instruction is output
9020: in the usual way.
9021:
9022: @item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands})
9023: If defined, a C statement to be executed just prior to the output of
9024: assembler code for @var{insn}, to modify the extracted operands so
9025: they will be output differently.
9026:
9027: Here the argument @var{opvec} is the vector containing the operands
9028: extracted from @var{insn}, and @var{noperands} is the number of
9029: elements of the vector which contain meaningful data for this insn.
9030: The contents of this vector are what will be used to convert the insn
9031: template into assembler code, so you can change the assembler output
9032: by changing the contents of the vector.
9033:
9034: This macro is useful when various assembler syntaxes share a single
9035: file of instruction patterns; by defining this macro differently, you
9036: can cause a large class of instructions to be output differently (such
9037: as with rearranged operands). Naturally, variations in assembler
9038: syntax affecting individual insn patterns ought to be handled by
9039: writing conditional output routines in those patterns.
9040:
9041: If this macro is not defined, it is equivalent to a null statement.
9042:
9043: @item PRINT_OPERAND (@var{stream}, @var{x}, @var{code})
9044: A C compound statement to output to stdio stream @var{stream} the
9045: assembler syntax for an instruction operand @var{x}. @var{x} is an
9046: RTL expression.
9047:
9048: @var{code} is a value that can be used to specify one of several ways
9049: of printing the operand. It is used when identical operands must be
9050: printed differently depending on the context. @var{code} comes from
9051: the @samp{%} specification that was used to request printing of the
9052: operand. If the specification was just @samp{%@var{digit}} then
9053: @var{code} is 0; if the specification was @samp{%@var{ltr}
9054: @var{digit}} then @var{code} is the ASCII code for @var{ltr}.
9055:
9056: If @var{x} is a register, this macro should print the register's name.
9057: The names can be found in an array @code{reg_names} whose type is
9058: @code{char *[]}. @code{reg_names} is initialized from
9059: @code{REGISTER_NAMES}.
9060:
9061: When the machine description has a specification @samp{%@var{punct}}
9062: (a @samp{%} followed by a punctuation character), this macro is called
9063: with a null pointer for @var{x} and the punctuation character for
9064: @var{code}.
9065:
9066: @item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x})
9067: A C compound statement to output to stdio stream @var{stream} the
9068: assembler syntax for an instruction operand that is a memory reference
9069: whose address is @var{x}. @var{x} is an RTL expression.
9070:
9071: @item ASM_OPEN_PAREN
9072: @itemx ASM_CLOSE_PAREN
9073: These macros are defined as C string constant, describing the syntax
9074: in the assembler for grouping arithmetic expressions. The following
9075: definitions are correct for most assemblers:
9076:
9077: @example
9078: #define ASM_OPEN_PAREN "("
9079: #define ASM_CLOSE_PAREN ")"
9080: @end example
9081: @end table
9082:
9083: @node Config,, Machine Macros, Top
9084: @chapter The Configuration File
9085:
1.1.1.3 root 9086: The configuration file @file{xm-@var{machine}.h} contains macro definitions
9087: that describe the machine and system on which the compiler is running.
9088: Most of the values in it are actually the same on all machines that GNU CC
9089: runs on, so large parts of all configuration files are identical. But
1.1 root 9090: there are some macros that vary:
9091:
9092: @table @code
9093: @item FAILURE_EXIT_CODE
9094: A C expression for the status code to be returned when the compiler
9095: exits after serious errors.
9096:
9097: @item SUCCESS_EXIT_CODE
9098: A C expression for the status code to be returned when the compiler
9099: exits without serious errors.
9100: @end table
9101:
1.1.1.3 root 9102: In addition, configuration files for system V define @code{bcopy},
9103: @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
9104: as a macro when compiled with GNU CC, in order to take advantage of the
9105: benefit of GNU CC's built-in @code{alloca}.
9106:
1.1 root 9107: @contents
9108: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.