![[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.8 ! root 42: @center last updated 12 September 1989
1.1 root 43: @sp 1
1.1.1.8 ! root 44: @center for version 1.36
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.
1.1.1.8 ! root 91: * Config:: Writing the @file{xm-@var{machine}.h} file.
1.1 root 92: @end menu
93:
94: @node Copying, Contributors, Top, Top
1.1.1.6 root 95: @unnumbered GNU GENERAL PUBLIC LICENSE
96: @center Version 1, February 1989
1.1 root 97:
1.1.1.6 root 98: @display
99: Copyright @copyright{} 1989 Free Software Foundation, Inc.
100: 675 Mass Ave, Cambridge, MA 02139, USA
101:
102: Everyone is permitted to copy and distribute verbatim copies
103: of this license document, but changing it is not allowed.
104: @end display
105:
106: @unnumberedsec Preamble
107:
108: The license agreements of most software companies try to keep users
109: at the mercy of those companies. By contrast, our General Public
110: License is intended to guarantee your freedom to share and change free
111: software---to make sure the software is free for all its users. The
112: General Public License applies to the Free Software Foundation's
113: software and to any other program whose authors commit to using it.
114: You can use it for your programs, too.
115:
116: When we speak of free software, we are referring to freedom, not
117: price. Specifically, the General Public License is designed to make
118: sure that you have the freedom to give away or sell copies of free
119: software, that you receive source code or can get it if you want it,
120: that you can change the software or use pieces of it in new free
121: programs; and that you know you can do these things.
122:
123: To protect your rights, we need to make restrictions that forbid
124: anyone to deny you these rights or to ask you to surrender the rights.
125: These restrictions translate to certain responsibilities for you if you
126: distribute copies of the software, or if you modify it.
127:
128: For example, if you distribute copies of a such a program, whether
129: gratis or for a fee, you must give the recipients all the rights that
130: you have. You must make sure that they, too, receive or can get the
1.1 root 131: source code. And you must tell them their rights.
132:
1.1.1.6 root 133: We protect your rights with two steps: (1) copyright the software, and
134: (2) offer you this license which gives you legal permission to copy,
135: distribute and/or modify the software.
136:
137: Also, for each author's protection and ours, we want to make certain
138: that everyone understands that there is no warranty for this free
139: software. If the software is modified by someone else and passed on, we
140: want its recipients to know that what they have is not the original, so
141: that any problems introduced by others will not reflect on the original
142: authors' reputations.
1.1 root 143:
1.1.1.6 root 144: The precise terms and conditions for copying, distribution and
145: modification follow.
1.1 root 146:
1.1.1.6 root 147: @iftex
148: @unnumberedsec TERMS AND CONDITIONS
149: @end iftex
150: @ifinfo
151: @center TERMS AND CONDITIONS
152: @end ifinfo
1.1 root 153:
1.1.1.6 root 154: @enumerate
1.1 root 155: @item
1.1.1.6 root 156: This License Agreement applies to any program or other work which
157: contains a notice placed by the copyright holder saying it may be
158: distributed under the terms of this General Public License. The
159: ``Program'', below, refers to any such program or work, and a ``work based
160: on the Program'' means either the Program or any work containing the
161: Program or a portion of it, either verbatim or with modifications. Each
162: licensee is addressed as ``you''.
163:
164: @item
165: You may copy and distribute verbatim copies of the Program's source
166: code as you receive it, in any medium, provided that you conspicuously and
167: appropriately publish on each copy an appropriate copyright notice and
168: disclaimer of warranty; keep intact all the notices that refer to this
169: General Public License and to the absence of any warranty; and give any
170: other recipients of the Program a copy of this General Public License
171: along with the Program. You may charge a fee for the physical act of
172: transferring a copy.
173:
174: @item
175: You may modify your copy or copies of the Program or any portion of
176: it, and copy and distribute such modifications under the terms of Paragraph
177: 1 above, provided that you also do the following:
1.1 root 178:
179: @itemize @bullet
180: @item
1.1.1.6 root 181: cause the modified files to carry prominent notices stating that
182: you changed the files and the date of any change; and
1.1 root 183:
184: @item
185: cause the whole of any work that you distribute or publish, that
1.1.1.6 root 186: in whole or in part contains the Program or any part thereof, either
187: with or without modifications, to be licensed at no charge to all
188: third parties under the terms of this General Public License (except
189: that you may choose to grant warranty protection to some or all
190: third parties, at your option).
191:
192: @item
193: If the modified program normally reads commands interactively when
194: run, you must cause it, when started running for such interactive use
195: in the simplest and most usual way, to print or display an
196: announcement including an appropriate copyright notice and a notice
197: that there is no warranty (or else, saying that you provide a
198: warranty) and that users may redistribute the program under these
199: conditions, and telling the user how to view a copy of this General
200: Public License.
201:
202: @item
203: You may charge a fee for the physical act of transferring a
204: copy, and you may at your option offer warranty protection in
205: exchange for a fee.
1.1 root 206: @end itemize
207:
1.1.1.6 root 208: Mere aggregation of another independent work with the Program (or its
1.1 root 209: derivative) on a volume of a storage or distribution medium does not bring
1.1.1.6 root 210: the other work under the scope of these terms.
1.1 root 211:
212: @item
1.1.1.6 root 213: You may copy and distribute the Program (or a portion or derivative of
214: it, under Paragraph 2) in object code or executable form under the terms of
215: Paragraphs 1 and 2 above provided that you also do one of the following:
1.1 root 216:
217: @itemize @bullet
218: @item
219: accompany it with the complete corresponding machine-readable
220: source code, which must be distributed under the terms of
221: Paragraphs 1 and 2 above; or,
222:
223: @item
224: accompany it with a written offer, valid for at least three
1.1.1.6 root 225: years, to give any third party free (except for a nominal charge
226: for the cost of distribution) a complete machine-readable copy of the
1.1 root 227: corresponding source code, to be distributed under the terms of
228: Paragraphs 1 and 2 above; or,
229:
230: @item
231: accompany it with the information you received as to where the
232: corresponding source code may be obtained. (This alternative is
233: allowed only for noncommercial distribution and only if you
234: received the program in object code or executable form alone.)
235: @end itemize
236:
1.1.1.6 root 237: Source code for a work means the preferred form of the work for making
238: modifications to it. For an executable file, complete source code means
239: all the source code for all modules it contains; but, as a special
240: exception, it need not include source code for modules which are standard
241: libraries that accompany the operating system on which the executable
242: file runs, or for standard header files or definitions files that
243: accompany that operating system.
244:
245: @item
246: You may not copy, modify, sublicense, distribute or transfer the
247: Program except as expressly provided under this General Public License.
248: Any attempt otherwise to copy, modify, sublicense, distribute or transfer
249: the Program is void, and will automatically terminate your rights to use
250: the Program under this License. However, parties who have received
251: copies, or rights to use copies, from you under this General Public
252: License will not have their licenses terminated so long as such parties
253: remain in full compliance.
254:
255: @item
256: By copying, distributing or modifying the Program (or any work based
257: on the Program) you indicate your acceptance of this license to do so,
258: and all its terms and conditions.
259:
260: @item
261: Each time you redistribute the Program (or any work based on the
262: Program), the recipient automatically receives a license from the original
263: licensor to copy, distribute or modify the Program subject to these
264: terms and conditions. You may not impose any further restrictions on the
265: recipients' exercise of the rights granted herein.
266:
267: @item
268: The Free Software Foundation may publish revised and/or new versions
269: of the General Public License from time to time. Such new versions will
270: be similar in spirit to the present version, but may differ in detail to
271: address new problems or concerns.
272:
273: Each version is given a distinguishing version number. If the Program
274: specifies a version number of the license which applies to it and ``any
275: later version'', you have the option of following the terms and conditions
276: either of that version or of any later version published by the Free
277: Software Foundation. If the Program does not specify a version number of
278: the license, you may choose any version ever published by the Free Software
279: Foundation.
280:
281: @item
282: If you wish to incorporate parts of the Program into other free
283: programs whose distribution conditions are different, write to the author
284: to ask for permission. For software which is copyrighted by the Free
285: Software Foundation, write to the Free Software Foundation; we sometimes
286: make exceptions for this. Our decision will be guided by the two goals
287: of preserving the free status of all derivatives of our free software and
288: of promoting the sharing and reuse of software generally.
289:
290: @iftex
291: @heading NO WARRANTY
292: @end iftex
293: @ifinfo
294: @center NO WARRANTY
295: @end ifinfo
296:
297: @item
298: BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
299: FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
300: OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
301: PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
302: OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
303: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
304: TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
305: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
306: REPAIR OR CORRECTION.
307:
308: @item
309: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
310: ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
311: REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
312: INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
313: ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
314: LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
315: SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
316: WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
317: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
1.1 root 318: @end enumerate
319:
1.1.1.6 root 320: @iftex
321: @heading END OF TERMS AND CONDITIONS
322: @end iftex
323: @ifinfo
324: @center END OF TERMS AND CONDITIONS
325: @end ifinfo
326:
327: @page
328: @unnumberedsec Appendix: How to Apply These Terms to Your New Programs
329:
330: If you develop a new program, and you want it to be of the greatest
331: possible use to humanity, the best way to achieve this is to make it
332: free software which everyone can redistribute and change under these
333: terms.
334:
335: To do so, attach the following notices to the program. It is safest to
336: attach them to the start of each source file to most effectively convey
337: the exclusion of warranty; and each file should have at least the
338: ``copyright'' line and a pointer to where the full notice is found.
339:
340: @smallexample
341: @var{one line to give the program's name and a brief idea of what it does.}
342: Copyright (C) 19@var{yy} @var{name of author}
343:
344: This program is free software; you can redistribute it and/or modify
345: it under the terms of the GNU General Public License as published by
346: the Free Software Foundation; either version 1, or (at your option)
347: any later version.
348:
349: This program is distributed in the hope that it will be useful,
350: but WITHOUT ANY WARRANTY; without even the implied warranty of
351: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
352: GNU General Public License for more details.
353:
354: You should have received a copy of the GNU General Public License
355: along with this program; if not, write to the Free Software
356: Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
357: @end smallexample
358:
359: Also add information on how to contact you by electronic and paper mail.
360:
361: If the program is interactive, make it output a short notice like this
362: when it starts in an interactive mode:
363:
364: @smallexample
365: Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
366: Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
367: This is free software, and you are welcome to redistribute it
368: under certain conditions; type `show c' for details.
369: @end smallexample
370:
371: The hypothetical commands `show w' and `show c' should show the
372: appropriate parts of the General Public License. Of course, the
373: commands you use may be called something other than `show w' and `show
374: c'; they could even be mouse-clicks or menu items---whatever suits your
375: program.
376:
377: You should also get your employer (if you work as a programmer) or your
378: school, if any, to sign a ``copyright disclaimer'' for the program, if
379: necessary. Here a sample; alter the names:
380:
381: @example
382: Yoyodyne, Inc., hereby disclaims all copyright interest in the
383: program `Gnomovision' (a program to direct compilers to make passes
384: at assemblers) written by James Hacker.
385:
386: @var{signature of Ty Coon}, 1 April 1989
387: Ty Coon, President of Vice
388: @end example
389:
390: That's all there is to it!
1.1 root 391:
392: @node Contributors, Options, Copying, Top
393: @unnumbered Contributors to GNU CC
394:
395: In addition to Richard Stallman, several people have written parts
396: of GNU CC.
397:
398: @itemize @bullet
399: @item
400: The idea of using RTL and some of the optimization ideas came from the
401: U. of Arizona Portable Optimizer, written by Jack Davidson and
402: Christopher Fraser. See ``Register Allocation and Exhaustive Peephole
403: Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
404: 857-866.
405:
406: @item
407: Paul Rubin wrote most of the preprocessor.
408:
409: @item
1.1.1.6 root 410: Leonard Tower wrote parts of the parser, RTL generator, and RTL
1.1 root 411: definitions, and of the Vax machine description.
412:
413: @item
414: Ted Lemon wrote parts of the RTL reader and printer.
415:
416: @item
417: Jim Wilson implemented loop strength reduction and some other
418: loop optimizations.
419:
420: @item
421: Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
1.1.1.8 ! root 422: the support for the Sony NEWS machine.
1.1 root 423:
424: @item
425: Charles LaBrec contributed the support for the Integrated Solutions
426: 68020 system.
427:
428: @item
429: Michael Tiemann of MCC wrote most of the description of the National
430: Semiconductor 32000 series cpu. He also wrote the code for inline
431: function integration and for the SPARC cpu and Motorola 88000 cpu
432: and part of the Sun FPA support.
433:
434: @item
435: Jan Stein of the Chalmers Computer Society provided support for
436: Genix, as well as part of the 32000 machine description.
437:
438: @item
439: Randy Smith finished the Sun FPA support.
440:
441: @item
442: Robert Brown implemented the support for Encore 32000 systems.
443:
444: @item
445: David Kashtan of SRI adapted GNU CC to the Vomit-Making System.
446:
447: @item
448: Alex Crain provided changes for the 3b1.
449:
450: @item
451: Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for
452: the 9000 series 300.
453:
454: @item
455: William Schelter did most of the work on the Intel 80386 support.
1.1.1.5 root 456:
457: @item
458: Christopher Smith did the port for Convex machines.
459:
460: @item
461: Paul Petersen wrote the machine description for the Alliant FX/8.
1.1.1.7 root 462:
463: @item
1.1.1.8 ! root 464: Alain Lichnewsky ported GNU CC to the Mips cpu.
! 465:
! 466: @item
! 467: Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the Tahoe.
! 468:
! 469: @item
! 470: Jonathan Stone wrote the machine description for the Pyramid computer.
! 471: Note that this machine description does not fully work.
1.1 root 472: @end itemize
473:
474: @node Options, Installation, Contributors, Top
475: @chapter GNU CC Command Options
476:
477: The GNU C compiler uses a command syntax much like the Unix C compiler.
478: The @code{gcc} program accepts options and file names as operands.
479: Multiple single-letter options may @emph{not} be grouped: @samp{-dr} is
1.1.1.8 ! root 480: very different from @w{@samp{-d -r}}.
1.1 root 481:
482: When you invoke GNU CC, it normally does preprocessing, compilation,
483: assembly and linking. File names which end in @samp{.c} are taken as C
1.1.1.5 root 484: source to be preprocessed and compiled; file names ending in @samp{.i}
485: are taken as preprocessor output to be compiled; compiler output files
486: plus any input files with names ending in @samp{.s} are assembled; then
487: the resulting object files, plus any other input files, are linked
488: together to produce an executable.
1.1 root 489:
490: Command options allow you to stop this process at an intermediate stage.
491: For example, the @samp{-c} option says not to run the linker. Then the
492: output consists of object files output by the assembler.
493:
1.1.1.5 root 494: Other command options are passed on to one stage of processing. Some
495: options control the preprocessor and others the compiler itself. Yet
496: other options control the assembler and linker; these are not documented
497: here, but you rarely need to use any of them.
1.1 root 498:
499: Here are the options to control the overall compilation process, including
500: those that say whether to link, whether to assemble, and so on.
501:
502: @table @samp
503: @item -o @var{file}
504: Place output in file @var{file}. This applies regardless to whatever
505: sort of output is being produced, whether it be an executable file,
506: an object file, an assembler file or preprocessed C code.
507:
508: If @samp{-o} is not specified, the default is to put an executable file
509: in @file{a.out}, the object file @file{@var{source}.c} in
510: @file{@var{source}.o}, an assembler file in @file{@var{source}.s}, and
511: preprocessed C on standard output.@refill
512:
513: @item -c
514: Compile or assemble the source files, but do not link. Produce object
515: files with names made by replacing @samp{.c} or @samp{.s} with
516: @samp{.o} at the end of the input file names. Do nothing at all for
517: object files specified as input.
518:
519: @item -S
520: Compile into assembler code but do not assemble. The assembler output
521: file name is made by replacing @samp{.c} with @samp{.s} at the end of
522: the input file name. Do nothing at all for assembler source files or
523: object files specified as input.
524:
525: @item -E
526: Run only the C preprocessor. Preprocess all the C source files
527: specified and output the results to standard output.
528:
529: @item -v
530: Compiler driver program prints the commands it executes as it runs
531: the preprocessor, compiler proper, assembler and linker. Some of
532: these are directed to print their own version numbers.
533:
1.1.1.5 root 534: @item -pipe
535: Use pipes rather than temporary files for communication between the
536: various stages of compilation. This fails to work on some systems
537: where the assembler is unable to read from a pipe; but the GNU
538: assembler has no trouble.
539:
1.1 root 540: @item -B@var{prefix}
541: Compiler driver program tries @var{prefix} as a prefix for each
542: program it tries to run. These programs are @file{cpp}, @file{cc1},
543: @file{as} and @file{ld}.
544:
545: For each subprogram to be run, the compiler driver first tries the
546: @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
547: was not specified, the driver tries two standard prefixes, which are
548: @file{/usr/lib/gcc-} and @file{/usr/local/lib/gcc-}. If neither of
549: those results in a file name that is found, the unmodified program
550: name is searched for using the directories specified in your
551: @samp{PATH} environment variable.
552:
553: The run-time support file @file{gnulib} is also searched for using
554: the @samp{-B} prefix, if needed. If it is not found there, the two
555: standard prefixes above are tried, and that is all. The file is left
556: out of the link if it is not found by those means. Most of the time,
557: on most machines, you can do without it.
1.1.1.5 root 558:
559: You can get a similar result from the environment variable;
560: @code{GCC_EXEC_PREFIX} if it is defined, its value is used as a prefix
561: in the same way. If both the @samp{-B} option and the
562: @code{GCC_EXEC_PREFIX} variable are present, the @samp{-B} option is
563: used first and the environment variable value second.
1.1.1.8 ! root 564:
! 565: @item -b@var{prefix}
! 566: The argument @var{prefix} is used as a second prefix for the compiler
! 567: executables and libraries. This prefix is optional: the compiler tries
! 568: each file first with it, then without it. This prefix follows the
! 569: prefix specified with @samp{-B} or the default prefixes.
! 570:
! 571: Thus, @samp{-bvax- -Bcc/} in the presence of environment variable
! 572: @code{GCC_EXEC_PREFIX} with definition @file{/u/foo/} causes GNU CC to
! 573: try the following file names for the preprocessor executable:
! 574:
! 575: @example
! 576: cc/vax-cpp
! 577: cc/cpp
! 578: /u/foo/vax-cpp
! 579: /u/foo/cpp
! 580: /usr/local/lib/gcc-vax-cpp
! 581: /usr/local/lib/gcc-cpp
! 582: /usr/lib/gcc-vax-cpp
! 583: /usr/lib/gcc-cpp
! 584: @end example
1.1 root 585: @end table
586:
587: These options control the details of C compilation itself.
588:
589: @table @samp
590: @item -ansi
591: Support all ANSI standard C programs.
592:
593: This turns off certain features of GNU C that are incompatible with
594: ANSI C, such as the @code{asm}, @code{inline} and @code{typeof}
595: keywords, and predefined macros such as @code{unix} and @code{vax}
596: that identify the type of system you are using. It also enables the
597: undesirable and rarely used ANSI trigraph feature.
598:
1.1.1.8 ! root 599: The alternate keywords @code{__asm__}, @code{__inline__} and
! 600: @code{__typeof__} continue to work despite @samp{-ansi}. You would not
1.1.1.7 root 601: want to use them in an ANSI C program, of course, but it useful to put
602: them in header files that might be included in compilations done with
1.1.1.8 ! root 603: @samp{-ansi}. Alternate predefined macros such as @code{__unix__} and
! 604: @code{__vax__} are also available, with or without @samp{-ansi}.
1.1.1.7 root 605:
1.1 root 606: The @samp{-ansi} option does not cause non-ANSI programs to be
607: rejected gratuitously. For that, @samp{-pedantic} is required in
608: addition to @samp{-ansi}.
609:
610: The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
611: option is used. Some header files may notice this macro and refrain
612: from declaring certain functions or defining certain macros that the
1.1.1.7 root 613: ANSI standard doesn't call for; this is to avoid interfering with any
614: programs that might use these names for other things.
1.1 root 615:
616: @item -traditional
617: Attempt to support some aspects of traditional C compilers.
618: Specifically:
619:
620: @itemize @bullet
621: @item
622: All @code{extern} declarations take effect globally even if they
623: are written inside of a function definition. This includes implicit
624: declarations of functions.
625:
626: @item
627: The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
628: and @code{volatile} are not recognized.@refill
629:
630: @item
631: Comparisons between pointers and integers are always allowed.
632:
633: @item
634: Integer types @code{unsigned short} and @code{unsigned char} promote
635: to @code{unsigned int}.
636:
637: @item
638: Out-of-range floating point literals are not an error.
639:
640: @item
1.1.1.8 ! root 641: String ``constants'' are not necessarily constant; they are stored in
! 642: writable space, and identical looking constants are allocated
! 643: separately.
! 644:
! 645: @item
1.1.1.2 root 646: All automatic variables not declared @code{register} are preserved by
647: @code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
648: not declared @code{volatile} may be clobbered.
649:
650: @item
1.1 root 651: In the preprocessor, comments convert to nothing at all, rather than
652: to a space. This allows traditional token concatenation.
653:
654: @item
655: In the preprocessor, macro arguments are recognized within string
656: constants in a macro definition (and their values are stringified,
657: though without additional quote marks, when they appear in such a
658: context). The preprocessor always considers a string constant to end
659: at a newline.
660:
661: @item
662: The predefined macro @code{__STDC__} is not defined when you use
663: @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
664: which @code{__GNUC__} indicates are not affected by
665: @samp{-traditional}). If you need to write header files that work
666: differently depending on whether @samp{-traditional} is in use, by
667: testing both of these predefined macros you can distinguish four
668: situations: GNU C, traditional GNU C, other ANSI C compilers, and
669: other old C compilers.
670: @end itemize
671:
672: @item -O
673: Optimize. Optimizing compilation takes somewhat more time, and a lot
674: more memory for a large function.
675:
676: Without @samp{-O}, the compiler's goal is to reduce the cost of
677: compilation and to make debugging produce the expected results.
678: Statements are independent: if you stop the program with a breakpoint
679: between statements, you can then assign a new value to any variable or
680: change the program counter to any other statement in the function and
681: get exactly the results you would expect from the source code.
682:
683: Without @samp{-O}, only variables declared @code{register} are
684: allocated in registers. The resulting compiled code is a little worse
685: than produced by PCC without @samp{-O}.
686:
687: With @samp{-O}, the compiler tries to reduce code size and execution
688: time.
689:
690: Some of the @samp{-f} options described below turn specific kinds of
691: optimization on or off.
692:
693: @item -g
694: Produce debugging information in the operating system's native format
695: (for DBX or SDB). GDB also can work with this debugging information.
696:
697: Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
698: @samp{-O}. The shortcuts taken by optimized code may occasionally
699: produce surprising results: some variables you declared may not exist
700: at all; flow of control may briefly move where you did not expect it;
701: some statements may not be executed because they compute constant
702: results or their values were already at hand; some statements may
703: execute in different places because they were moved out of loops.
704: Nevertheless it proves possible to debug optimized output. This makes
705: it reasonable to use the optimizer for programs that might have bugs.
706:
707: @item -gg
1.1.1.8 ! root 708: Produce debugging information in the old GDB format. This is obsolete.
1.1 root 709:
710: @item -w
711: Inhibit all warning messages.
712:
713: @item -W
714: Print extra warning messages for these events:
715:
716: @itemize @bullet
717: @item
718: An automatic variable is used without first being initialized.
719:
720: These warnings are possible only in optimizing compilation,
721: because they require data flow information that is computed only
1.1.1.6 root 722: when optimizing. If you don't specify @samp{-O}, you simply won't
723: get these warnings.
724:
725: These warnings occur only for variables that are candidates for
726: register allocation. Therefore, they do not occur for a variable that
727: is declared @code{volatile}, or whose address is taken, or whose size
728: is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
729: structures, unions or arrays, even when they are in registers.
730:
731: Note that there may be no warning about a variable that is used only
732: to compute a value that itself is never used, because such
733: computations may be deleted by data flow analysis before the warnings
734: are printed.
1.1 root 735:
736: These warnings are made optional because GNU CC is not smart
737: enough to see all the reasons why the code might be correct
738: despite appearing to have an error. Here is one example of how
739: this can happen:
740:
741: @example
742: @{
743: int x;
744: switch (y)
745: @{
746: case 1: x = 1;
747: break;
748: case 2: x = 4;
749: break;
750: case 3: x = 5;
751: @}
752: foo (x);
753: @}
754: @end example
755:
756: @noindent
757: If the value of @code{y} is always 1, 2 or 3, then @code{x} is
758: always initialized, but GNU CC doesn't know this. Here is
759: another common case:
760:
761: @example
762: @{
763: int save_y;
764: if (change_y) save_y = y, y = new_y;
765: @dots{}
766: if (change_y) y = save_y;
767: @}
768: @end example
769:
770: @noindent
771: This has no bug because @code{save_y} is used only if it is set.
772:
1.1.1.5 root 773: Some spurious warnings can be avoided if you declare as
774: @code{volatile} all the functions you use that never return.
775: @xref{Function Attributes}.
776:
1.1 root 777: @item
778: A nonvolatile automatic variable might be changed by a call to
779: @code{longjmp}. These warnings as well are possible only in
780: optimizing compilation.
781:
782: The compiler sees only the calls to @code{setjmp}. It cannot know
783: where @code{longjmp} will be called; in fact, a signal handler could
784: call it at any point in the code. As a result, you may get a warning
785: even when there is in fact no problem because @code{longjmp} cannot
786: in fact be called at the place which would cause a problem.
787:
788: @item
789: A function can return either with or without a value. (Falling
790: off the end of the function body is considered returning without
1.1.1.6 root 791: a value.) For example, this function would evoke such a
1.1 root 792: warning:
793:
794: @example
795: foo (a)
796: @{
797: if (a > 0)
798: return a;
799: @}
800: @end example
801:
802: Spurious warnings can occur because GNU CC does not realize that
803: certain functions (including @code{abort} and @code{longjmp})
804: will never return.
1.1.1.4 root 805:
806: @item
807: An expression-statement contains no side effects.
1.1 root 808: @end itemize
809:
810: In the future, other useful warnings may also be enabled by this
811: option.
812:
813: @item -Wimplicit
814: Warn whenever a function is implicitly declared.
815:
816: @item -Wreturn-type
817: Warn whenever a function is defined with a return-type that defaults
818: to @code{int}. Also warn about any @code{return} statement with no
819: return-value in a function whose return-type is not @code{void}.
820:
821: @item -Wunused
1.1.1.5 root 822: Warn whenever a local variable is unused aside from its declaration,
1.1.1.8 ! root 823: whenever a function is declared static but never defined, and whenever
! 824: a statement computes a result that is explicitly not used.
1.1.1.7 root 825:
826: @item -Wswitch
827: Warn whenever a @code{switch} statement has an index of enumeral type
828: and lacks a @code{case} for one or more of the named codes of that
829: enumeration. (The presence of a @code{default} label prevents this
830: warning.) @code{case} labels outside the enumeration range also
831: provoke warnings when this option is used.
832:
1.1 root 833: @item -Wcomment
834: Warn whenever a comment-start sequence @samp{/*} appears in a comment.
835:
1.1.1.7 root 836: @item -Wtrigraphs
837: Warn if any trigraphs are encountered (assuming they are enabled).
838:
1.1 root 839: @item -Wall
1.1.1.8 ! root 840: All of the above @samp{-W} options combined. These are all the
! 841: options which pertain to usage that we recommend avoiding and that we
! 842: believe is easy to avoid, even in conjunction with macros.
! 843:
! 844: The other @samp{-W@dots{}} options below are not implied by @samp{-Wall}
! 845: because certain kinds of useful macros are almost impossible to write
! 846: without causing those warnings.
! 847:
! 848: @item -Wshadow
! 849: Warn whenever a local variable shadows another local variable.
! 850:
! 851: @item -Wid-clash-@var{len}
! 852: Warn whenever two distinct identifiers match in the first @var{len}
! 853: characters. This may help you prepare a program that will compile
! 854: with certain obsolete, brain-damaged compilers.
! 855:
! 856: @item -Wpointer-arith
! 857: Warn about anything that depends on the ``size of'' a function type or
! 858: of @code{void}. GNU C assigns these types a size of 1, for
! 859: convenience in calculations with @code{void *} pointers and pointers
! 860: to functions.
1.1 root 861:
1.1.1.6 root 862: @item -Wcast-qual
863: Warn whenever a pointer is cast so as to remove a type qualifier from
864: the target type. For example, warn if a @code{const char *} is cast
865: to an ordinary @code{char *}.
866:
1.1 root 867: @item -Wwrite-strings
868: Give string constants the type @code{const char[@var{length}]} so that
869: copying the address of one into a non-@code{const} @code{char *}
870: pointer will get a warning. These warnings will help you find at
871: compile time code that can try to write into a string constant, but
872: only if you have been very careful about using @code{const} in
873: declarations and prototypes. Otherwise, it will just be a nuisance;
874: this is why we did not make @samp{-Wall} request these warnings.
875:
876: @item -p
877: Generate extra code to write profile information suitable for the
878: analysis program @code{prof}.
879:
880: @item -pg
881: Generate extra code to write profile information suitable for the
882: analysis program @code{gprof}.
883:
1.1.1.6 root 884: @item -a
1.1.1.8 ! root 885: Generate extra code to write profile information for basic blocks, which
! 886: will record the number of times each basic block is executed. This data
! 887: could be analyzed by a program like @code{tcov}. Note, however, that
! 888: the format of the data is not what @code{tcov} expects. Eventually GNU
1.1.1.6 root 889: @code{gprof} should be extended to process this data.
890:
1.1 root 891: @item -l@var{library}
892: Search a standard list of directories for a library named
893: @var{library}, which is actually a file named
894: @file{lib@var{library}.a}. The linker uses this file as if it
895: had been specified precisely by name.
896:
897: The directories searched include several standard system directories
898: plus any that you specify with @samp{-L}.
899:
900: Normally the files found this way are library files---archive files
901: whose members are object files. The linker handles an archive file by
902: scanning through it for members which define symbols that have so far
903: been referenced but not defined. But if the file that is found is an
904: ordinary object file, it is linked in the usual fashion. The only
905: difference between using an @samp{-l} option and specifying a file name
906: is that @samp{-l} searches several directories.
907:
908: @item -L@var{dir}
909: Add directory @var{dir} to the list of directories to be searched
910: for @samp{-l}.
911:
912: @item -nostdlib
913: Don't use the standard system libraries and startup files when
914: linking. Only the files you specify (plus @file{gnulib}) will be
915: passed to the linker.
916:
917: @item -m@var{machinespec}
918: Machine-dependent option specifying something about the type of target
919: machine. These options are defined by the macro
920: @code{TARGET_SWITCHES} in the machine description. The default for
921: the options is also defined by that macro, which enables you to change
922: the defaults.@refill
923:
924: These are the @samp{-m} options defined in the 68000 machine
925: description:
926:
927: @table @samp
928: @item -m68020
929: @itemx -mc68020
930: Generate output for a 68020 (rather than a 68000). This is the
931: default if you use the unmodified sources.
932:
933: @item -m68000
934: @item -mc68000
935: Generate output for a 68000 (rather than a 68020).
936:
937: @item -m68881
938: Generate output containing 68881 instructions for floating point.
939: This is the default if you use the unmodified sources.
940:
941: @item -mfpa
942: Generate output containing Sun FPA instructions for floating point.
943:
944: @item -msoft-float
945: Generate output containing library calls for floating point.
946:
947: @item -mshort
948: Consider type @code{int} to be 16 bits wide, like @code{short int}.
949:
950: @item -mnobitfield
951: Do not use the bit-field instructions. @samp{-m68000} implies
952: @samp{-mnobitfield}.
953:
954: @item -mbitfield
955: Do use the bit-field instructions. @samp{-m68020} implies
956: @samp{-mbitfield}. This is the default if you use the unmodified
957: sources.
958:
959: @item -mrtd
960: Use a different function-calling convention, in which functions
961: that take a fixed number of arguments return with the @code{rtd}
962: instruction, which pops their arguments while returning. This
963: saves one instruction in the caller since there is no need to pop
964: the arguments there.
965:
966: This calling convention is incompatible with the one normally
967: used on Unix, so you cannot use it if you need to call libraries
968: compiled with the Unix compiler.
969:
970: Also, you must provide function prototypes for all functions that
971: take variable numbers of arguments (including @code{printf});
972: otherwise incorrect code will be generated for calls to those
973: functions.
974:
975: In addition, seriously incorrect code will result if you call a
976: function with too many arguments. (Normally, extra arguments are
977: harmlessly ignored.)
978:
979: The @code{rtd} instruction is supported by the 68010 and 68020
980: processors, but not by the 68000.
981: @end table
982:
983: These @samp{-m} options are defined in the Vax machine description:
984:
985: @table @samp
986: @item -munix
987: Do not output certain jump instructions (@code{aobleq} and so on)
988: that the Unix assembler for the Vax cannot handle across long
989: ranges.
990:
991: @item -mgnu
992: Do output those jump instructions, on the assumption that you
993: will assemble with the GNU assembler.
994:
995: @item -mg
996: Output code for g-format floating point numbers instead of d-format.
997: @end table
998:
1.1.1.5 root 999: These @samp{-m} switches are supported on the Sparc:
1000:
1001: @table @samp
1002: @item -mfpu
1003: Generate output containing floating point instructions. This is the
1004: default if you use the unmodified sources.
1005:
1006: @item -msoft-float
1007: Generate output containing library calls for floating point.
1008:
1009: @item -mno-epilogue
1.1.1.6 root 1010: Generate separate return instructions for @code{return} statements.
1011: This has both advantages and disadvantages; I don't recall what they
1012: are.
1.1.1.5 root 1013: @end table
1014:
1015: These @samp{-m} options are defined in the Convex machine description:
1016:
1017: @table @samp
1018: @item -mc1
1019: Generate output for a C1. This is the default when the compiler is
1020: configured for a C1.
1021:
1022: @item -mc2
1023: Generate output for a C2. This is the default when the compiler is
1024: configured for a C2.
1025:
1026: @item -margcount
1027: Generate code which puts an argument count in the word preceding each
1028: argument list. Some nonportable Convex and Vax programs need this
1029: word. (Debuggers don't; this info is in the symbol table.)
1030:
1031: @item -mnoargcount
1032: Omit the argument count word. This is the default if you use the
1033: unmodified sources.
1034: @end table
1035:
1.1 root 1036: @item -f@var{flag}
1.1.1.4 root 1037: Specify machine-independent flags. Most flags have both positive and
1038: negative forms; the negative form of @samp{-ffoo} would be
1039: @samp{-fno-foo}. In the table below, only one of the forms is
1040: listed---the one which is not the default. You can figure out the
1041: other form by either removing @samp{no-} or adding it.
1.1 root 1042:
1043: @table @samp
1.1.1.6 root 1044: @item -fpcc-struct-return
1045: Use the same convention for returning @code{struct} and @code{union}
1046: values that is used by the usual C compiler on your system. This
1047: convention is less efficient for small structures, and on many
1048: machines it fails to be reentrant; but it has the advantage of
1049: allowing intercallability between GCC-compiled code and PCC-compiled
1050: code.
1051:
1.1 root 1052: @item -ffloat-store
1053: Do not store floating-point variables in registers. This
1054: prevents undesirable excess precision on machines such as the
1055: 68000 where the floating registers (of the 68881) keep more
1056: precision than a @code{double} is supposed to have.
1057:
1058: For most programs, the excess precision does only good, but a few
1059: programs rely on the precise definition of IEEE floating point.
1060: Use @samp{-ffloat-store} for such programs.
1061:
1062: @item -fno-asm
1063: Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1.1.1.7 root 1064: keyword. These words may then be used as identifiers. You can
1.1.1.8 ! root 1065: use @code{__asm__}, @code{__inline__} and @code{__typeof__} instead.
1.1 root 1066:
1067: @item -fno-defer-pop
1068: Always pop the arguments to each function call as soon as that
1069: function returns. Normally the compiler (when optimizing) lets
1070: arguments accumulate on the stack for several function calls and
1071: pops them all at once.
1072:
1073: @item -fstrength-reduce
1074: Perform the optimizations of loop strength reduction and
1075: elimination of iteration variables.
1076:
1077: @item -fcombine-regs
1078: Allow the combine pass to combine an instruction that copies one
1079: register into another. This might or might not produce better
1080: code when used in addition to @samp{-O}. I am interested in
1081: hearing about the difference this makes.
1082:
1083: @item -fforce-mem
1084: Force memory operands to be copied into registers before doing
1085: arithmetic on them. This may produce better code by making all
1086: memory references potential common subexpressions. When they are
1087: not common subexpressions, instruction combination should
1088: eliminate the separate register-load. I am interested in hearing
1089: about the difference this makes.
1090:
1091: @item -fforce-addr
1092: Force memory address constants to be copied into registers before
1093: doing arithmetic on them. This may produce better code just as
1094: @samp{-fforce-mem} may. I am interested in hearing about the
1095: difference this makes.
1096:
1097: @item -fomit-frame-pointer
1098: Don't keep the frame pointer in a register for functions that
1099: don't need one. This avoids the instructions to save, set up and
1100: restore frame pointers; it also makes an extra register available
1101: in many functions. @strong{It also makes debugging impossible.}
1102:
1103: On some machines, such as the Vax, this flag has no effect,
1104: because the standard calling sequence automatically handles the
1105: frame pointer and nothing is saved by pretending it doesn't
1106: exist. The machine-description macro
1107: @code{FRAME_POINTER_REQUIRED} controls whether a target machine
1108: supports this flag. @xref{Registers}.@refill
1109:
1110: @item -finline-functions
1111: Integrate all simple functions into their callers. The compiler
1112: heuristically decides which functions are simple enough to be
1113: worth integrating in this way.
1114:
1115: If all calls to a given function are integrated, and the function
1116: is declared @code{static}, then the function is normally not
1117: output as assembler code in its own right.
1118:
1.1.1.6 root 1119: @item -fcaller-saves
1120: Enable values to be allocated in registers that will be clobbered by
1121: function calls, by emitting extra instructions to save and restore the
1122: registers around such calls. Such allocation is done only when it
1123: seems to result in better code than would otherwise be produced.
1124:
1125: This option is enabled by default on certain machines, usually those
1126: which have no call-preserved registers to use instead.
1127:
1.1 root 1128: @item -fkeep-inline-functions
1129: Even if all calls to a given function are integrated, and the
1130: function is declared @code{static}, nevertheless output a
1131: separate run-time callable version of the function.
1132:
1133: @item -fwritable-strings
1.1.1.8 ! root 1134: Store string constants in the writable data segment and don't uniquize
! 1135: them. This is for compatibility with old programs which assume they can
! 1136: write into string constants. @samp{-traditional} also has this effect.
! 1137:
! 1138: Writing into string constants is a very bad idea; ``constants'' should
! 1139: be constant.
1.1 root 1140:
1.1.1.4 root 1141: @item -fcond-mismatch
1142: Allow conditional expressions with mismatched types in the second and
1143: third arguments. The value of such an expression is void.
1144:
1.1 root 1145: @item -fno-function-cse
1146: Do not put function addresses in registers; make each instruction
1147: that calls a constant function contain the function's address
1148: explicitly.
1149:
1150: This option results in less efficient code, but some strange
1151: hacks that alter the assembler output may be confused by the
1152: optimizations performed when this option is not used.
1153:
1154: @item -fvolatile
1155: Consider all memory references through pointers to be volatile.
1156:
1.1.1.4 root 1157: @item -fshared-data
1158: Requests that the data and non-@code{const} variables of this
1159: compilation be shared data rather than private data. The distinction
1160: makes sense only on certain operating systems, where shared data is
1161: shared between processes running the same program, while private data
1162: exists in one copy per process.
1163:
1.1 root 1164: @item -funsigned-char
1.1.1.4 root 1165: Let the type @code{char} be the unsigned, like @code{unsigned char}.
1.1 root 1166:
1167: Each kind of machine has a default for what @code{char} should
1168: be. It is either like @code{unsigned char} by default or like
1169: @code{signed char} by default. (Actually, at present, the
1170: default is always signed.)
1171:
1172: The type @code{char} is always a distinct type from either
1173: @code{signed char} or @code{unsigned char}, even though its
1174: behavior is always just like one of those two.
1175:
1.1.1.4 root 1176: Note that this is equivalent to @samp{-fno-signed-char}, which is the
1177: negative form of @samp{-fsigned-char}.
1178:
1.1 root 1179: @item -fsigned-char
1180: Let the type @code{char} be signed, like @code{signed char}.
1181:
1.1.1.4 root 1182: Note that this is equivalent to @samp{-fno-unsigned-char}, which is
1183: the negative form of @samp{-funsigned-char}.
1184:
1.1.1.8 ! root 1185: @item -fdelayed-branch
! 1186: If supported for the target machine, attempt to reorder instructions
! 1187: to exploit instruction slots available after delayed branch
! 1188: instructions.
! 1189:
1.1 root 1190: @item -ffixed-@var{reg}
1191: Treat the register named @var{reg} as a fixed register; generated
1192: code should never refer to it (except perhaps as a stack pointer,
1193: frame pointer or in some other fixed role).
1194:
1195: @var{reg} must be the name of a register. The register names
1196: accepted are machine-specific and are defined in the
1197: @code{REGISTER_NAMES} macro in the machine description macro
1198: file.
1199:
1.1.1.4 root 1200: This flag does not have a negative form, because it specifies a
1201: three-way choice.
1202:
1.1 root 1203: @item -fcall-used-@var{reg}
1204: Treat the register named @var{reg} as an allocatable register
1205: that is clobbered by function calls. It may be allocated for
1206: temporaries or variables that do not live across a call.
1207: Functions compiled this way will not save and restore the
1208: register @var{reg}.
1209:
1210: Use of this flag for a register that has a fixed pervasive role
1211: in the machine's execution model, such as the stack pointer or
1212: frame pointer, will produce disastrous results.
1213:
1.1.1.4 root 1214: This flag does not have a negative form, because it specifies a
1215: three-way choice.
1216:
1.1 root 1217: @item -fcall-saved-@var{reg}
1218: Treat the register named @var{reg} as an allocatable register
1219: saved by functions. It may be allocated even for temporaries or
1220: variables that live across a call. Functions compiled this way
1221: will save and restore the register @var{reg} if they use it.
1222:
1223: Use of this flag for a register that has a fixed pervasive role
1224: in the machine's execution model, such as the stack pointer or
1225: frame pointer, will produce disastrous results.
1226:
1227: A different sort of disaster will result from the use of this
1228: flag for a register in which function values may be returned.
1.1.1.4 root 1229:
1230: This flag does not have a negative form, because it specifies a
1231: three-way choice.
1.1 root 1232: @end table
1233:
1234: @item -d@var{letters}
1235: Says to make debugging dumps at times specified by @var{letters}.
1236: Here are the possible letters:
1237:
1238: @table @samp
1239: @item r
1240: Dump after RTL generation.
1241: @item j
1242: Dump after first jump optimization.
1243: @item s
1244: Dump after CSE (including the jump optimization that sometimes
1245: follows CSE).
1246: @item L
1247: Dump after loop optimization.
1248: @item f
1249: Dump after flow analysis.
1250: @item c
1251: Dump after instruction combination.
1252: @item l
1253: Dump after local register allocation.
1254: @item g
1255: Dump after global register allocation.
1.1.1.8 ! root 1256: @item d
! 1257: Dump after delayed branch scheduling.
! 1258: @item J
! 1259: Dump after last jump optimization.
1.1 root 1260: @item m
1261: Print statistics on memory usage, at the end of the run.
1262: @end table
1263:
1264: @item -pedantic
1265: Issue all the warnings demanded by strict ANSI standard C; reject
1266: all programs that use forbidden extensions.
1267:
1268: Valid ANSI standard C programs should compile properly with or without
1269: this option (though a rare few will require @samp{-ansi}). However,
1270: without this option, certain GNU extensions and traditional C features
1271: are supported as well. With this option, they are rejected. There is
1272: no reason to @i{use} this option; it exists only to satisfy pedants.
1.1.1.5 root 1273:
1.1.1.8 ! root 1274: @samp{-pedantic} does not cause warning messages for use of the
! 1275: alternate keywords whose names begin and end with @samp{__}.
! 1276: @xref{Alternate Keywords}.
! 1277:
1.1.1.5 root 1278: @item -static
1279: On Suns running version 4, this prevents linking with the shared
1280: libraries. (@samp{-g} has the same effect.)
1.1 root 1281: @end table
1282:
1283: These options control the C preprocessor, which is run on each C source
1284: file before actual compilation. If you use the @samp{-E} option, nothing
1285: is done except C preprocessing. Some of these options make sense only
1286: together with @samp{-E} because they request preprocessor output that is
1287: not suitable for actual compilation.
1288:
1289: @table @samp
1290: @item -C
1291: Tell the preprocessor not to discard comments. Used with the
1292: @samp{-E} option.
1293:
1294: @item -I@var{dir}
1295: Search directory @var{dir} for include files.
1296:
1297: @item -I-
1298: Any directories specified with @samp{-I} options before the @samp{-I-}
1299: option are searched only for the case of @samp{#include "@var{file}"};
1300: they are not searched for @samp{#include <@var{file}>}.
1301:
1302: If additional directories are specified with @samp{-I} options after
1303: the @samp{-I-}, these directories are searched for all @samp{#include}
1304: directives. (Ordinarily @emph{all} @samp{-I} directories are used
1305: this way.)
1306:
1307: In addition, the @samp{-I-} option inhibits the use of the current
1.1.1.8 ! root 1308: directory (where the current input file came from) as the first search
! 1309: directory for @samp{#include "@var{file}"}. There is no way to override
! 1310: this effect of @samp{-I-}. With @samp{-I.} you can specify searching
! 1311: the directory which was current when the compiler was invoked. That is
! 1312: not exactly the same as what the preprocessor does by default, but it is
! 1313: often satisfactory.
! 1314:
! 1315: @samp{-I-} does not inhibit the use of the standard system directories
! 1316: for header files. Thus, @samp{-I-} and @samp{-nostdinc} are
! 1317: independent.
! 1318:
! 1319: @item -i @var{file}
! 1320: Process @var{file} as input, discarding the resulting output, before
! 1321: processing the regular input file. Because the output generated from
! 1322: @var{file} is discarded, the only effect of @samp{-i @var{file}} is to
! 1323: make the macros defined in @var{file} available for use in the main
! 1324: input.
1.1 root 1325:
1326: @item -nostdinc
1327: Do not search the standard system directories for header files. Only
1328: the directories you have specified with @samp{-I} options (and the
1329: current directory, if appropriate) are searched.
1330:
1331: Between @samp{-nostdinc} and @samp{-I-}, you can eliminate all
1332: directories from the search path except those you specify.
1333:
1334: @item -M
1335: Tell the preprocessor to output a rule suitable for @code{make}
1336: describing the dependencies of each source file. For each source
1337: file, the preprocessor outputs one @code{make}-rule whose target is
1338: the object file name for that source file and whose dependencies are
1339: all the files @samp{#include}d in it. This rule may be a single line
1340: or may be continued with @samp{\}-newline if it is long.
1341:
1342: @samp{-M} implies @samp{-E}.
1343:
1344: @item -MM
1345: Like @samp{-M} but the output mentions only the user-header files
1346: included with @samp{#include "@var{file}"}. System header files
1347: included with @samp{#include <@var{file}>} are omitted.
1348:
1349: @samp{-MM} implies @samp{-E}.
1350:
1351: @item -D@var{macro}
1.1.1.8 ! root 1352: Define macro @var{macro} with the string @samp{1} as its definition.
1.1 root 1353:
1354: @item -D@var{macro}=@var{defn}
1355: Define macro @var{macro} as @var{defn}.
1356:
1357: @item -U@var{macro}
1358: Undefine macro @var{macro}.
1359:
1.1.1.7 root 1360: @item -trigraphs
1.1 root 1361: Support ANSI C trigraphs. You don't want to know about this
1362: brain-damage. The @samp{-ansi} option also has this effect.
1363: @end table
1364:
1365: @node Installation, Trouble, Options, Top
1366: @chapter Installing GNU CC
1367:
1368: Here is the procedure for installing GNU CC on a Unix system.
1.1.1.8 ! root 1369:
1.1 root 1370: @menu
1.1.1.8 ! root 1371: * Other Dir:: Compiling in a separate directory (not where the source is).
! 1372: * Sun Install:: See below for installation on the Sun.
! 1373: * 3B1 Install:: See below for installation on the 3B1.
1.1 root 1374: * VMS Install:: See below for installation on VMS.
1375: @end menu
1376: @iftex
1.1.1.8 ! root 1377: See below for VMS systems, and modified procedures needed on Sun systems
! 1378: and 3b1 machines. The following section says how to compile in a
! 1379: separate directory on Unix; here we assume you compile in the same
! 1380: directory that contains the source files.
1.1 root 1381: @end iftex
1382:
1383: @enumerate
1384: @item
1385: Edit @file{Makefile}. If you are using HPUX, or any form of system V,
1386: you must make a few changes described in comments at the beginning of
1.1.1.4 root 1387: the file. Genix requires changes also.
1.1 root 1388:
1389: @item
1390: On a Sequent system, go to the Berkeley universe.
1391:
1392: @item
1.1.1.2 root 1393: Choose configuration files. The easy way to do this is to run the
1.1.1.8 ! root 1394: command file @file{config.gcc} with a single argument, which specifies
! 1395: the type of machine (and in some cases which operating system).
1.1.1.4 root 1396:
1397: Here is a list of the possible arguments:
1398:
1399: @table @samp
1400: @item vax
1401: Vaxes running BSD.
1402: @item vms
1403: Vaxes running VMS.
1404: @item vax-sysv
1405: Vaxes running system V.
1406: @item i386-sysv
1407: Intel 386 PCs running system V.
1.1.1.5 root 1408: @item i386-sysv-gas
1409: Intel 386 PCs running system V, using the GNU assembler and GNU
1410: linker.
1.1.1.6 root 1411: @item sequent-i386
1.1.1.4 root 1412: Sequent with Intel 386 processors.
1.1.1.8 ! root 1413: @item i386-aix
! 1414: Intel 386 PCs or PS/2s running AIX.
1.1.1.4 root 1415: @item sun2
1416: Sun 2 running system version 2 or 3.
1417: @item sun3
1.1.1.5 root 1418: Sun 3 running system version 2 or 3, with 68881.
1.1.1.7 root 1419: Note there we do not provide a configuration file to use an FPA
1.1.1.8 ! root 1420: by default, because programs that establish signal handlers for
1.1.1.7 root 1421: floating point traps inherently cannot work with the FPA.
1.1.1.5 root 1422: @item sun3-nfp
1423: Sun 3 running system version 2 or 3, without 68881.
1.1.1.4 root 1424: @item sun4
1.1.1.8 ! root 1425: Sun 4 running system version 2 or 3. @xref{Incompatibilities},
! 1426: for calling convention incompatibilities on the Sun 4 (sparc).
1.1.1.4 root 1427: @item sun2-os4
1428: Sun 2 running system version 4.
1429: @item sun3-os4
1.1.1.5 root 1430: Sun 3 running system version 4, with 68881.
1431: @item sun3-nfp-os4
1432: Sun 3 running system version 4, without 68881.
1.1.1.4 root 1433: @item sun4-os4
1.1.1.8 ! root 1434: Sun 4 running system version 4. @xref{Incompatibilities},
! 1435: for calling convention incompatibilities on the Sun 4 (sparc).
1.1.1.4 root 1436: @item sun386
1437: Sun 386 (``roadrunner'').
1.1.1.5 root 1438: @item alliant
1.1.1.8 ! root 1439: Alliant FX/8 computer. Note that the standard installed C compiler in
! 1440: Concentrix 5.0 has a bug which prevent it from compiling GNU CC
! 1441: correctly. You can patch the compiler bug as follows:
! 1442:
! 1443: @example
! 1444: cp /bin/pcc ./pcc
! 1445: adb -w ./pcc - << 'EOF'
! 1446: 15f6?w 6610
! 1447: EOF
! 1448: @end example
! 1449:
! 1450: Then you must use the @samp{-ip12} option when compiling GNU CC
! 1451: with the patched compiler, as shown here:
! 1452:
! 1453: @example
! 1454: make CC="./pcc -ip12" CFLAGS=-w
! 1455: @end example
! 1456:
! 1457: Note also that Alliant's version of DBX does not manage to work with the
! 1458: output from GNU CC.
! 1459: @item tahoe
! 1460: The tahoe computer (running BSD, and using DBX).
! 1461: @item decstation
! 1462: The DEC 3100 Mips machine (``pmax''). Note that GNU CC cannot generate
! 1463: debugging information in the unusual format used on the Mips.
! 1464: @item mips-sysv
! 1465: The Mips computer, RS series, with the System V environment as default.
! 1466: Note that GNU CC cannot generate debugging information in the unusual
! 1467: format used on the Mips.
! 1468: @item mips-bsd43
! 1469: The Mips computer, RS series, with the BSD 4.3 environment as default.
! 1470: Note that GNU CC cannot generate debugging information in the unusual
! 1471: format used on the Mips.
1.1.1.7 root 1472: @item mips
1.1.1.8 ! root 1473: The Mips computer, M series. Note that GNU CC cannot generate debugging
! 1474: information in the unusual format used on the Mips.
! 1475: @item iris
! 1476: The Mips computer, as delivered by Iris. Note that GNU CC cannot
! 1477: generate debugging information in the unusual format used on the Mips.
1.1.1.5 root 1478: @item convex-c1
1479: Convex C1 computer.
1480: @item convex-c2
1481: Convex C2 computer.
1.1.1.8 ! root 1482: @item pyramid
! 1483: Pyramid computer.
1.1.1.4 root 1484: @item hp9k320
1.1.1.7 root 1485: HP 9000 series 300 using HPUX assembler. Note there is no
1486: support in GNU CC for HP's debugger; thus, @samp{-g} is not
1487: available in this configuration.
1.1.1.8 ! root 1488: @item hp9k320-gas
1.1.1.4 root 1489: HP 9000 series 300 using GNU assembler, linker and debugger.
1.1.1.7 root 1490: This requires the HP-adapt package, which is available along with
1491: the GNU linker as part of the ``binutils'' distribution.
1492: This is on the GNU CC distribution tape.
1.1.1.8 ! root 1493: @item hp9k320-old
! 1494: HP 9000 series 300 using HPUX assembler, in operating system versions
! 1495: older than 6.5. Note there is no support in GNU CC for HP's debugger;
! 1496: thus, @samp{-g} is not available in this configuration.
! 1497: @item hp9k320-bsd
! 1498: HP 9000 series 300 running BSD.
1.1.1.4 root 1499: @item isi68
1.1.1.8 ! root 1500: ISI 68000 or 68020 system with a 68881.
! 1501: @item isi68-nfp
! 1502: ISI 68000 or 68020 system without a 68881.
1.1.1.4 root 1503: @item news800
1504: Sony NEWS 68020 system.
1.1.1.6 root 1505: @item next
1506: NeXT system.
1.1.1.7 root 1507: @item altos
1508: Altos 3068. Note that you must use the GNU assembler, linker and
1509: debugger, with COFF-encapsulation. Also, you must fix a kernel
1510: bug. Details in the file @file{ALTOS-README}.
1.1.1.4 root 1511: @item 3b1
1.1.1.8 ! root 1512: AT&T 3b1, a.k.a. 7300 PC. Note that special procedures are needed
! 1513: to compile GNU CC with this machine's standard C compiler, due to
! 1514: bugs in that compiler. @xref{3b1 Install}. You can bootstrap it
! 1515: more easily with previous versions of GNU CC if you have them.
1.1.1.4 root 1516: @item sequent-ns32k
1517: Sequent containing ns32000 processors.
1518: @item encore
1519: Encore ns32000 system.
1520: @item genix
1521: National Semiconductor ns32000 system.
1522: @item 88000
1523: Motorola 88000 processor. This port is not finished.
1524: @end table
1.1.1.2 root 1525:
1.1.1.4 root 1526: Here we spell out what files need to be set up:
1.1 root 1527:
1528: @itemize @bullet
1529: @item
1530: Make a symbolic link named @file{config.h} to the top-level
1531: config file for the machine you are using (@pxref{Config}). This
1532: file is responsible for defining information about the host
1533: machine. It includes @file{tm.h}.
1534:
1.1.1.7 root 1535: The file is located in the subdirectory @file{config}. Its name
1536: should be @file{xm-@var{machine}.h}, with these exceptions:
1.1 root 1537:
1538: @table @file
1.1.1.3 root 1539: @item xm-vms.h
1.1 root 1540: for vaxen running VMS.
1.1.1.3 root 1541: @item xm-vaxv.h
1.1 root 1542: for vaxen running system V.
1.1.1.3 root 1543: @item xm-i386v.h
1.1 root 1544: for Intel 80386's running system V.
1.1.1.3 root 1545: @item xm-sun386i.h
1546: for Sun roadrunner running any version of the operating system.
1547: @item xm-hp9k320.h
1.1 root 1548: for the HP 9000 series 300.
1.1.1.4 root 1549: @item xm-genix.h
1.1 root 1550: for the ns32000 running Genix
1551: @end table
1552:
1553: If your system does not support symbolic links, you might want to
1554: set up @file{config.h} to contain a @samp{#include} command which
1555: refers to the appropriate file.
1556:
1557: @item
1558: Make a symbolic link named @file{tm.h} to the machine-description
1.1.1.7 root 1559: macro file for your machine. It should be in the subdirectory
1560: @file{config} and its name should be @file{tm-@var{machine}.h}.
1.1 root 1561:
1562: If your system is a 68000, don't use the file @file{tm-m68k.h}
1563: directly. Instead, use one of these files:
1564:
1565: @table @file
1566: @item tm-sun3.h
1.1.1.5 root 1567: for Sun 3 machines with 68881.
1568: @item tm-sun3-nfp.h
1569: for Sun 3 machines with no hardware floating point.
1.1.1.8 ! root 1570: @item tm-sun3os3.h
! 1571: for Sun 3 machines with 68881, running Sunos version 3.
! 1572: @item tm-sun3os3nf.h
! 1573: for Sun 3 machines with no hardware floating point, running Sunos
! 1574: version 3.
1.1 root 1575: @item tm-sun2.h
1576: for Sun 2 machines.
1577: @item tm-3b1.h
1578: for AT&T 3b1 (aka 7300 Unix PC).
1579: @item tm-isi68.h
1.1.1.3 root 1580: for Integrated Solutions systems. This file assumes you
1581: use the GNU assembler.
1.1.1.8 ! root 1582: @item tm-isi68-nfp.h
! 1583: for Integrated Solutions systems without a 68881. This file assumes you
! 1584: use the GNU assembler.
1.1 root 1585: @item tm-news800.h
1.1.1.8 ! root 1586: for Sony NEWS systems.
1.1 root 1587: @item tm-hp9k320.h
1588: for HPUX systems, if you are using GNU CC with the system's
1589: assembler and linker.
1590: @item tm-hp9k320g.h
1591: for HPUX systems, if you are using the GNU assembler, linker and
1592: other utilities. Not all of the pieces of GNU software needed
1593: for this mode of operation are as yet in distribution; full
1594: instructions will appear here in the future.@refill
1595: @end table
1596:
1597: For the vax, use @file{tm-vax.h} on BSD Unix, @file{tm-vaxv.h} on
1598: system V, or @file{tm-vms.h} on VMS.@refill
1599:
1600: For the Motorola 88000, use @file{tm-m88k.h}. The support for the
1601: 88000 has a few unfinished spots because there was no way to run the
1.1.1.2 root 1602: output. Bugs are suspected in handling of branch-tables and in the
1603: function prologue and epilogue.
1.1 root 1604:
1605: For the 80386, don't use @file{tm-i386.h} directly. Use
1606: @file{tm-i386v.h} if the target machine is running system V,
1.1.1.5 root 1607: @file{tm-i386gas.h} if it is running system V but you are using the
1608: GNU assembler and linker, @file{tm-seq386.h} for a Sequent 386 system,
1609: or @file{tm-compaq.h} for a Compaq, or @file{tm-sun386i.h} for a Sun
1610: 386 system.
1.1 root 1611:
1.1.1.8 ! root 1612: For the Mips computer, there are five choices: @file{tm-mips.h} for the
! 1613: M series, @file{tm-mips-bsd.h} for the RS series with BSD,
! 1614: @file{tm-mips-sysv.h} for the RS series with System V, @file{tm-iris.h}
! 1615: for the Iris version of the machine, and @file{tm-decstatn.h} for the
! 1616: Decstation.
! 1617:
1.1 root 1618: For the 32000, use @file{tm-sequent.h} if you are using a Sequent
1619: machine, or @file{tm-encore.h} for an Encore machine, or
1.1.1.4 root 1620: @file{tm-genix.h} if you are using Genix version 3; otherwise, perhaps
1.1 root 1621: @file{tm-ns32k.h} will work for you.
1622:
1623: Note that Genix has bugs in @code{alloca} and @code{malloc}; you must
1624: get the compiled versions of these from GNU Emacs and edit GNU CC's
1625: @file{Makefile} to use them.
1626:
1627: Note that Encore systems are supported only under BSD.
1628:
1.1.1.6 root 1629: For Sparc (Sun 4) machines, use @file{tm-sparc.h} with operating system
1630: version 4, and @file{tm-sun4os3.h} with system version 3.
1631:
1.1 root 1632: @item
1633: Make a symbolic link named @file{md} to the machine description
1.1.1.7 root 1634: pattern file. It should be in the @file{config} subdirectory and its
1635: name should be @file{@var{machine}.md}; but @var{machine} is often not
1636: the same as the name used in the @file{tm.h} file because the
1637: @file{md} files are more general.
1.1 root 1638:
1639: @item
1640: Make a symbolic link named @file{aux-output.c} to the output
1.1.1.7 root 1641: subroutine file for your machine. It should be in the @file{config}
1642: subdirectory and its name should be @file{out-@var{machine}.c}.
1.1 root 1643: @end itemize
1644:
1645: @item
1646: Make sure the Bison parser generator is installed. (This is
1647: unnecessary if the Bison output files @file{c-parse.tab.c} and
1648: @file{cexp.c} are more recent than @file{c-parse.y} and @file{cexp.y}
1649: and you do not plan to change the @samp{.y} files.)
1650:
1651: Bison versions older that Sept 8, 1988 will produce incorrect output
1652: for @file{c-parse.tab.c}.
1653:
1654: @item
1655: Build the compiler. Just type @samp{make} in the compiler directory.
1656:
1.1.1.2 root 1657: Ignore any warnings you may see about ``statement not reached'' in the
1658: @file{insn-emit.c}; they are normal. Any other compilation errors may
1659: represent bugs in the port to your machine or operating system, and
1660: should be investigated and reported (@pxref{Bugs}).
1661:
1.1 root 1662: @item
1.1.1.7 root 1663: Optionally, install the library functions for 64-bit integer
1664: arithmetic. You do this with the command @samp{make gnulib2}. In the
1665: future this will happen automatically; for now, it is optional, until
1666: we are sure it works on all machines.
1667:
1668: @item
1.1.1.5 root 1669: If you are using COFF-encapsulation, you must convert @file{gnulib} to
1670: a GNU-format library at this point. See the file @file{README-ENCAP}
1671: in the directory containing the GNU binary file utilities, for
1672: directions.
1673:
1674: @item
1.1 root 1675: Move the first-stage object files and executables into a subdirectory
1676: with this command:
1677:
1678: @example
1679: make stage1
1680: @end example
1681:
1682: The files are moved into a subdirectory named @file{stage1}.
1683: Once installation is complete, you may wish to delete these files
1684: with @code{rm -r stage1}.
1685:
1686: @item
1687: Recompile the compiler with itself, with this command:
1688:
1689: @example
1690: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/"
1691: @end example
1692:
1693: On a 68000 or 68020 system lacking floating point hardware,
1694: unless you have selected a @file{tm.h} file that expects by default
1695: that there is no such hardware, do this instead:
1696:
1697: @example
1698: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -msoft-float"
1699: @end example
1700:
1701: @item
1702: If you wish to test the compiler by compiling it with itself one more
1.1.1.7 root 1703: time, do this (in C shell):
1.1 root 1704:
1705: @example
1706: make stage2
1707: make CC=stage2/gcc CFLAGS="-g -O -Bstage2/"
1708: foreach file (*.o)
1709: cmp $file stage2/$file
1710: end
1711: @end example
1712:
1.1.1.7 root 1713: @noindent
1.1 root 1714: Aside from the @samp{-B} option, the options should be the same as
1715: when you made stage 2.
1716:
1.1.1.7 root 1717: The @code{foreach} command (written in C shell) will notify you if any of
1718: these stage 3 object files differs from those of stage 2. On BSD systems,
1719: any difference, no matter how innocuous, indicates that the stage 2
1720: compiler has compiled GNU CC incorrectly, and is therefore a potentially
1721: serious bug which you should investigate and report (@pxref{Bugs}).
1722:
1723: On systems that use COFF object files, bytes 5 to 8 will always be
1724: different, since it is a timestamp. On these systems, you can do the
1725: comparison as follows (in Bourne shell):
1726:
1727: @example
1728: for file in *.o; do
1729: echo $file
1730: tail +10 $file > foo1
1731: tail +10 stage2/$file > foo2
1732: cmp foo1 foo2
1733: done
1734: @end example
1735:
1.1 root 1736: @item
1737: Install the compiler driver, the compiler's passes and run-time support.
1738: You can use the following command:
1739:
1740: @example
1741: make install
1742: @end example
1743:
1744: @noindent
1745: This copies the files @file{cc1}, @file{cpp} and @file{gnulib} to
1746: files @file{gcc-cc1}, @file{gcc-cpp} and @file{gcc-gnulib} in
1747: directory @file{/usr/local/lib}, which is where the compiler driver
1748: program looks for them. It also copies the driver program @file{gcc}
1.1.1.6 root 1749: into the directory @file{/usr/local/bin}, so that it appears in typical
1.1 root 1750: execution search paths.@refill
1751:
1752: @strong{Warning: there is a bug in @code{alloca} in the Sun library.
1753: To avoid this bug, install the binaries of GNU CC that were compiled
1754: by GNU CC. They use @code{alloca} as a built-in function and never
1755: the one in the library.}
1756:
1757: @strong{Warning: the GNU CPP may not work for @file{ioctl.h},
1758: @file{ttychars.h} and other system header files unless the
1759: @samp{-traditional} option is used.} The bug is in the header files:
1760: at least on some machines, they rely on behavior that is incompatible
1761: with ANSI C. This behavior consists of substituting for macro
1762: argument names when they appear inside of character constants. The
1763: @samp{-traditional} option tells GNU CC to behave the way these
1764: headers expect.
1765:
1766: Because of this problem, you might prefer to configure GNU CC to use
1767: the system's own C preprocessor. To do so, make the file
1768: @file{/usr/local/lib/gcc-cpp} a link to @file{/lib/cpp}.
1769:
1770: Alternatively, on Sun systems and 4.3BSD at least, you can correct the
1771: include files by running the shell script @file{fixincludes}. This
1772: installs modified, corrected copies of the files @file{ioctl.h},
1773: @file{ttychars.h} and many others, in a special directory where only
1.1.1.2 root 1774: GNU CC will normally look for them. This script will work on various
1.1.1.6 root 1775: systems because it chooses the files by searching all the system
1.1.1.2 root 1776: headers for the problem cases that we know about.
1.1 root 1777: @end enumerate
1778:
1779: If you cannot install the compiler's passes and run-time support in
1780: @file{/usr/local/lib}, you can alternatively use the @samp{-B} option to
1781: specify a prefix by which they may be found. The compiler concatenates
1782: the prefix with the names @file{cpp}, @file{cc1} and @file{gnulib}.
1783: Thus, you can put the files in a directory @file{/usr/foo/gcc} and
1784: specify @samp{-B/usr/foo/gcc/} when you run GNU CC.
1785:
1786: Also, you can specify an alternative default directory for these files
1787: by setting the Make variable @code{libdir} when you make GNU CC.
1788:
1.1.1.8 ! root 1789: @node Other Dir, Sun Install, Installation, Installation
! 1790: @section Compilation in a Separate Directory
1.1 root 1791:
1.1.1.8 ! root 1792: If you wish to build the object files and executables in a directory
! 1793: other than the one containing the source files, here is what you must
! 1794: do differently:
! 1795:
! 1796: @enumerate
! 1797: @item
! 1798: Go to that directory before running @file{config.gcc}:
! 1799:
! 1800: @example
! 1801: mkdir gcc-sun3
! 1802: cd gcc-sun3
! 1803: @end example
1.1.1.4 root 1804:
1.1.1.8 ! root 1805: On systems that do not support symbolic links, this directory must be
! 1806: on the same file system as the source code directory.
! 1807:
! 1808: @item
! 1809: Specify where to find @file{config.gcc} when you run it:
! 1810:
! 1811: @example
! 1812: ../gcc-1.36/config.gcc @dots{}
! 1813: @end example
! 1814:
! 1815: @item
! 1816: Specify where to find the sources, as an argument to @file{config.gcc}:
! 1817:
! 1818: @example
! 1819: ../gcc-1.36/config.gcc -srcdir=../gcc-1.36 sun3
! 1820: @end example
! 1821:
! 1822: The @samp{-srcdir=@var{dir}} option is not needed when the source
! 1823: directory is the parent of the current directory, because
! 1824: @file{config.gcc} detects that case automatically.
! 1825: @end enumerate
! 1826:
! 1827: Now, you can run @code{make} in that directory. You need not repeat the
! 1828: configuration steps shown above, when ordinary source files change. You
! 1829: must, however, run @code{config.gcc} again when the configuration files
! 1830: change, if your system does not support symbolic links.
! 1831:
! 1832: @node Sun Install, 3b1 Install, Other Dir, Installation
! 1833: @section Installing GNU CC on the Sun
! 1834:
! 1835: Make sure the environment variable @code{FLOAT_OPTION} is not set when
! 1836: you compile @file{gnulib}. If this option were set to @code{f68881}
! 1837: when @file{gnulib} is compiled, the resulting code would demand to be
! 1838: linked with a special startup file and would not link properly without
! 1839: special pains.
! 1840:
! 1841: There is a bug in @code{alloca} in certain versions of the Sun library.
! 1842: To avoid this bug, install the binaries of GNU CC that were compiled by
! 1843: GNU CC. They use @code{alloca} as a built-in function and never the one
! 1844: in the library.
! 1845:
! 1846: Some versions of the Sun compiler crash when compiling GNU CC.
! 1847: The problem is a segmentation fault in cpp.
! 1848:
! 1849: This problem seems to be due to the bulk of data in the environment
! 1850: variables. You may be able to avoid it by using the following
! 1851: command to compile GNU CC with Sun CC:
! 1852:
! 1853: @example
! 1854: make CC="TERMCAP=x OBJS=x LIBFUNCS=x STAGESTUFF=x cc"
! 1855: @end example
! 1856:
! 1857: @node 3b1 Install, VMS Install, Sun Install, Installation
! 1858: @section Installing GNU CC on the 3b1
! 1859:
! 1860: Installing GNU CC on the 3b1 is difficult if you do not already have
! 1861: GNU CC running, due to bugs in the installed C compiler. However,
! 1862: the following procedure might work. We are unable to test it.
1.1 root 1863:
1864: @enumerate
1865: @item
1.1.1.8 ! root 1866: Comment out the @samp{#include "config.h"} line on line 37 of
! 1867: @file{cccp.c} and do @samp{make cpp}. This makes a preliminary version
! 1868: of GNU cpp.
1.1 root 1869:
1870: @item
1.1.1.8 ! root 1871: Save the old @file{/lib/cpp} and copy the preliminary GNU cpp to that
! 1872: file name.
1.1.1.5 root 1873:
1.1.1.8 ! root 1874: @item
! 1875: Undo your change in @file{cccp.c}, or reinstall the original version,
! 1876: and do @samp{make cpp} again.
! 1877:
! 1878: @item
! 1879: Copy this final version of GNU cpp into @file{/lib/cpp}.
! 1880:
! 1881: @item
! 1882: Replace every occurance of @code{obstack_free} in @file{tree.c}
! 1883: with @code{_obstack_free}.
! 1884:
! 1885: @item
! 1886: Run @code{make} to get the first-stage GNU CC.
! 1887:
! 1888: @item
! 1889: Reinstall the original version of @file{/lib/cpp}.
! 1890:
! 1891: @item
! 1892: Now you can compile GNU CC with itself and install it in the normal
! 1893: fashion.
1.1 root 1894: @end enumerate
1895:
1.1.1.8 ! root 1896: @node VMS Install,, 3B1 Install, Installation
! 1897: @section Installing GNU CC on VMS
! 1898:
! 1899: The VMS version of GNU CC is distributed in a backup saveset containing
! 1900: both source code and precompiled binaries.
! 1901:
! 1902: To install the @file{gcc} command so you can use the compiler easily, in
1.1 root 1903: the same manner as you use the VMS C compiler, you must install the VMS CLD
1904: file for GNU CC as follows:
1905:
1906: @enumerate
1907: @item
1908: Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE}
1909: to point to the directories where the GNU CC executables
1.1.1.8 ! root 1910: (@file{gcc-cpp}, @file{gcc-cc1}, etc.) and the C include files are
1.1 root 1911: kept. This should be done with the commands:@refill
1912:
1913: @example
1.1.1.8 ! root 1914: $ assign /super /system disk:[gcc.] gnu_cc
! 1915: $ assign /super /system disk:[gcc.include.] gnu_cc_include
1.1 root 1916: @end example
1917:
1918: @noindent
1919: with the appropriate disk and directory names. These commands can be
1920: placed in your system startup file so they will be executed whenever
1.1.1.8 ! root 1921: the machine is rebooted. You may, if you choose, do this via the
! 1922: @file{GCC_INSTALL.COM} script in the @file{[GCC]} directory.
1.1 root 1923:
1924: @item
1.1.1.8 ! root 1925: Install the @file{GCC} command with the command line:
1.1 root 1926:
1927: @example
1.1.1.8 ! root 1928: $ set command /table=sys$library:dcltables gnu_cc:[000000]gcc
1.1 root 1929: @end example
1930:
1.1.1.7 root 1931: @item
1932: To install the help file, do the following:
1933:
1934: @example
1935: $ lib/help sys$library:helplib.hlb gcc.hlp
1936: @end example
1937:
1.1 root 1938: @noindent
1939: Now you can invoke the compiler with a command like @samp{gcc /verbose
1940: file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in
1941: Unix.
1942: @end enumerate
1943:
1.1.1.8 ! root 1944: We try to put corresponding binaries and sources on the VMS distribution
! 1945: tape. But sometimes the binaries will be from an older version that the
! 1946: sources, because we don't always have time to update them. (Use the
! 1947: @samp{/verbose} option to determine the version number of the binaries and
! 1948: compare it with the source file @file{version.c} to tell whether this is
! 1949: so.) In this case, you should use the binaries you get to recompile the
! 1950: sources. If you must recompile, here is how:
! 1951:
! 1952: @enumerate
! 1953: @item
! 1954: Copy the file @file{tm-vms.h} to @file{tm.h}, @file{xm-vms.h} to
! 1955: @file{config.h}, @file{vax.md} to @file{md.} and @file{out-vax.c}
! 1956: to @file{aux-output.c}. The files to be copied are found in the
! 1957: subdirectory named @file{config}; they should be copied to the
! 1958: main directory of GNU CC.@refill
! 1959:
! 1960: @item
! 1961: Setup the logical names and command tables as defined above. In
! 1962: addition, define the vms logical name @samp{GNU_BISON} to point at the
! 1963: to the directories where the Bison executable is kept. This should be
! 1964: done with the command:@refill
! 1965:
! 1966: @example
! 1967: $ assign /super /system disk:[bison.] gnu_bison
! 1968: @end example
! 1969:
! 1970: You may, if you choose, use the @file{INSTALL_BISON.COM} script in the
! 1971: @file{[BISON]} directory.
! 1972:
! 1973: @item
! 1974: Install the @samp{BISON} command with the command line:@refill
! 1975:
! 1976: @example
! 1977: $ set command /table=sys$library:dcltables gnu_bison:[000000]bison
! 1978: @end example
! 1979:
! 1980: @item
! 1981: Type @samp{@@make} to do recompile everything.
! 1982:
! 1983: If you are compiling with a version of GNU CC older than 1.33, specify
! 1984: @samp{/DEFINE=("inline=")} as an option in all the compilations. This
! 1985: requires editing all the @code{gcc} commands in @file{make-cc1.com}.
! 1986: (The older versions had problems supporting @code{inline}.) Once you
! 1987: have a working 1.33 or newer GNU CC, you can change this file back.
! 1988: @end enumerate
! 1989:
1.1.1.5 root 1990: There is a known problem on VMS: @code{const} global variables don't
1991: work compatibly with the VMS C compiler; we don't know a way to get
1992: them to the linker properly.
1993:
1.1.1.7 root 1994: Note that GNU CC on VMS does not generate debugging information to
1995: describe the program's symbols. It is not straightforward to implement
1996: this, and we have no time to spend on it, but we might consent to
1997: install a very modular implementation if you write it. You will
1998: probably have to modify GAS as well as GNU CC.
1999:
1.1 root 2000: @node Trouble, Incompatibilities, Installation, Top
2001: @chapter Known Causes of Trouble with GNU CC.
2002:
2003: Here are some of the things that have caused trouble for people installing
2004: or using GNU CC.
2005:
2006: @itemize @bullet
2007: @item
2008: On certain systems, defining certain environment variables such as
1.1.1.8 ! root 2009: @code{CC} can interfere with the functioning of @code{make}.
1.1 root 2010:
2011: @item
2012: Cross compilation can run into trouble for certain machines because
2013: some target machines' assemblers require floating point numbers to be
2014: written as @emph{integer} constants in certain contexts.
2015:
2016: The compiler writes these integer constants by examining the floating
2017: point value as an integer and printing that integer, because this is
2018: simple to write and independent of the details of the floating point
2019: representation. But this does not work if the compiler is running on
2020: a different machine with an incompatible floating point format, or
2021: even a different byte-ordering.
2022:
1.1.1.5 root 2023: In addition, correct constant folding of floating point values
2024: requires representing them in the target machine's format.
2025: (The C standard does not quite require this, but in practice
2026: it is the only way to win.)
2027:
2028: It is now possible to overcome these problems by defining macros such
2029: as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
2030: work for each target machine. @xref{Cross-compilation}.
1.1 root 2031:
2032: @item
2033: DBX rejects some files produced by GNU CC, though it accepts similar
2034: constructs in output from PCC. Until someone can supply a coherent
2035: description of what is valid DBX input and what is not, there is
2036: nothing I can do about these problems. You are on your own.
1.1.1.2 root 2037:
2038: @item
2039: Users often think it is a bug when GNU CC reports an error for code
2040: like this:
2041:
2042: @example
2043: int foo (short);
2044:
2045: int foo (x)
2046: short x;
2047: @{@dots{}@}
2048: @end example
2049:
1.1.1.4 root 2050: The error message is correct: this code really is erroneous, because the
2051: old-style non-prototype definition passes subword integers in their
2052: promoted types. In other words, the argument is really an @code{int},
2053: not a @code{short}. The correct prototype is this:
1.1.1.2 root 2054:
2055: @example
2056: int foo (int);
2057: @end example
2058:
2059: @item
2060: Users often think it is a bug when GNU CC reports an error for code
2061: like this:
2062:
2063: @example
2064: int foo (struct mumble *);
2065:
2066: struct mumble @{ @dots{} @};
2067:
2068: int foo (struct mumble *x)
2069: @{ @dots{} @}
2070: @end example
2071:
2072: This code really is erroneous, because the scope of @code{struct
2073: mumble} the prototype is limited to the argument list containing it.
2074: It does not refer to the @code{struct mumble} defined with file scope
2075: immediately below---they are two unrelated types with similar names in
2076: different scopes.
2077:
2078: But in the definition of @code{foo}, the file-scope type is used
2079: because that is available to be inherited. Thus, the definition and
2080: the prototype do not match, and you get an error.
2081:
2082: This behavior may seem silly, but it's what the ANSI standard
2083: specifies. It is easy enough for you to make your code work by moving
2084: the definition of @code{struct mumble} above the prototype. I don't
2085: think it's worth being incompatible for.
1.1 root 2086: @end itemize
2087:
2088: @node Incompatibilities, Extensions, Trouble, Top
2089: @chapter Incompatibilities of GNU CC
2090:
2091: There are several noteworthy incompatibilities between GNU C and most
2092: existing (non-ANSI) versions of C.
2093:
2094: Ultimately our intention is that the @samp{-traditional} option will
2095: eliminate most of these incompatibilities by telling GNU C to behave
2096: like the other C compilers.
2097:
2098: @itemize @bullet
2099: @item
2100: GNU CC normally makes string constants read-only. If several
2101: identical-looking string constants are used, GNU CC stores only one
2102: copy of the string.
2103:
2104: One consequence is that you cannot call @code{mktemp} with a string
2105: constant argument. The function @code{mktemp} always alters the
2106: string its argument points to.
2107:
2108: Another consequence is that @code{sscanf} does not work on some
2109: systems when passed a string constant as its format control string.
2110: This is because @code{sscanf} incorrectly tries to write into the
1.1.1.4 root 2111: string constant. Likewise @code{fscanf} and @code{scanf}.
1.1 root 2112:
2113: The best solution to these problems is to change the program to use
2114: @code{char}-array variables with initialization strings for these
2115: purposes instead of string constants. But if this is not possible,
2116: you can use the @samp{-fwritable-strings} flag, which directs GNU CC
2117: to handle string constants the same way most C compilers do.
1.1.1.8 ! root 2118: @samp{-traditional} also has this effect, among others.
1.1 root 2119:
2120: @item
2121: GNU CC does not substitute macro arguments when they appear inside of
2122: string constants. For example, the following macro in GNU CC
2123:
2124: @example
2125: #define foo(a) "a"
2126: @end example
2127:
2128: @noindent
1.1.1.8 ! root 2129: will produce output @code{"a"} regardless of what the argument @var{a} is.
1.1 root 2130:
2131: The @samp{-traditional} option directs GNU CC to handle such cases
2132: (among others) in the old-fashioned (non-ANSI) fashion.
2133:
2134: @item
2135: When you use @code{setjmp} and @code{longjmp}, the only automatic
2136: variables guaranteed to remain valid are those declared
2137: @code{volatile}. This is a consequence of automatic register
2138: allocation. Consider this function:
2139:
2140: @example
2141: jmp_buf j;
2142:
2143: foo ()
2144: @{
2145: int a, b;
2146:
2147: a = fun1 ();
2148: if (setjmp (j))
2149: return a;
2150:
2151: a = fun2 ();
2152: /* @r{@code{longjmp (j)} may be occur in @code{fun3}.} */
2153: return a + fun3 ();
2154: @}
2155: @end example
2156:
2157: Here @code{a} may or may not be restored to its first value when the
2158: @code{longjmp} occurs. If @code{a} is allocated in a register, then
2159: its first value is restored; otherwise, it keeps the last value stored
2160: in it.
2161:
2162: If you use the @samp{-W} option with the @samp{-O} option, you will
2163: get a warning when GNU CC thinks such a problem might be possible.
2164:
1.1.1.2 root 2165: The @samp{-traditional} option directs GNU C to put variables in
2166: the stack by default, rather than in registers, in functions that
2167: call @code{setjmp}. This results in the behavior found in
2168: traditional C compilers.
2169:
1.1 root 2170: @item
2171: Declarations of external variables and functions within a block apply
2172: only to the block containing the declaration. In other words, they
2173: have the same scope as any other declaration in the same place.
2174:
2175: In some other C compilers, a @code{extern} declaration affects all the
2176: rest of the file even if it happens within a block.
2177:
2178: The @samp{-traditional} option directs GNU C to treat all @code{extern}
2179: declarations as global, like traditional compilers.
2180:
2181: @item
2182: In traditional C, you can combine @code{long}, etc., with a typedef name,
2183: as shown here:
2184:
2185: @example
2186: typedef int foo;
2187: typedef long foo bar;
2188: @end example
2189:
2190: In ANSI C, this is not allowed: @code{long} and other type modifiers
2191: require an explicit @code{int}. Because this criterion is expressed
2192: by Bison grammar rules rather than C code, the @samp{-traditional}
2193: flag cannot alter it.
2194:
2195: @item
2196: PCC allows typedef names to be used as function parameters. The
2197: difficulty described immediately above applies here too.
2198:
2199: @item
2200: PCC allows whitespace in the middle of compound assignment operators
2201: such as @samp{+=}. GNU CC, following the ANSI standard, does not
2202: allow this. The difficulty described immediately above applies here
2203: too.
2204:
2205: @item
2206: GNU CC will flag unterminated character constants inside of preprocessor
2207: conditionals that fail. Some programs have English comments enclosed in
2208: conditionals that are guaranteed to fail; if these comments contain
2209: apostrophes, GNU CC will probably report an error. For example,
2210: this code would produce an error:
2211:
2212: @example
2213: #if 0
2214: You can't expect this to work.
2215: #endif
2216: @end example
2217:
2218: The best solution to such a problem is to put the text into an actual
2219: C comment delimited by @samp{/*@dots{}*/}. However,
2220: @samp{-traditional} suppresses these error messages.
2221:
2222: @item
2223: When compiling functions that return @code{float}, PCC converts it to
2224: a double. GNU CC actually returns a @code{float}. If you are concerned
2225: with PCC compatibility, you should declare your functions to return
2226: @code{double}; you might as well say what you mean.
2227:
2228: @item
2229: When compiling functions that return structures or unions, GNU CC
1.1.1.6 root 2230: output code normally uses a method different from that used on most
2231: versions of Unix. As a result, code compiled with GNU CC cannot call
2232: a structure-returning function compiled with PCC, and vice versa.
1.1 root 2233:
1.1.1.6 root 2234: The method used by GNU CC is as follows: a structure or union which is 1,
1.1 root 2235: 2, 4 or 8 bytes long is returned like a scalar. A structure or union
2236: with any other size is stored into an address supplied by the caller
2237: in a special, fixed register.
2238:
2239: PCC usually handles all sizes of structures and unions by returning
2240: the address of a block of static storage containing the value. This
1.1.1.6 root 2241: method is not used in GNU CC because it is slower and nonreentrant.
1.1.1.5 root 2242:
1.1.1.6 root 2243: You can tell GNU CC to use the PCC convention with the option
2244: @samp{-fpcc-struct-return}.
1.1.1.8 ! root 2245:
! 2246: @item
! 2247: On the Sparc, GNU CC uses an incompatible calling convention for
! 2248: structures. It passes them by including their contents in the argument
! 2249: list, whereas the standard compiler passes them effectively by
! 2250: reference.
! 2251:
! 2252: This really ought to be fixed, but such calling conventions are not
! 2253: yet supported in GNU CC, so it isn't straightforward to fix it.
! 2254:
! 2255: The convention for structure returning is also incompatible, and
! 2256: @samp{-fpcc-struct-return} does not help.
1.1 root 2257: @end itemize
2258:
2259: @node Extensions, Bugs, Incompatibilities, Top
2260: @chapter GNU Extensions to the C Language
2261:
2262: GNU C provides several language features not found in ANSI standard C.
2263: (The @samp{-pedantic} option directs GNU CC to print a warning message if
2264: any of these features is used.) To test for the availability of these
2265: features in conditional compilation, check for a predefined macro
2266: @code{__GNUC__}, which is always defined under GNU CC.
2267:
2268: @menu
2269: * Statement Exprs:: Putting statements and declarations inside expressions.
2270: * Naming Types:: Giving a name to the type of some expression.
2271: * Typeof:: @code{typeof}: referring to the type of an expression.
2272: * Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues.
2273: * Conditionals:: Omitting the middle operand of a @samp{?:} expression.
2274: * Zero-Length:: Zero-length arrays.
2275: * Variable-Length:: Arrays whose length is computed at run time.
2276: * Subscripting:: Any array can be subscripted, even if not an lvalue.
2277: * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
1.1.1.5 root 2278: * Initializers:: Non-constant initializers.
1.1 root 2279: * Constructors:: Constructor expressions give structures, unions
2280: or arrays as values.
1.1.1.5 root 2281: * Function Attributes:: Declaring that functions have no side effects,
2282: or that they can never return.
1.1 root 2283: * Dollar Signs:: Dollar sign is allowed in identifiers.
2284: * Alignment:: Inquiring about the alignment of a type or variable.
2285: * Inline:: Defining inline functions (as fast as macros).
2286: * Extended Asm:: Assembler instructions with C expressions as operands.
2287: (With them you can define ``built-in'' functions.)
2288: * Asm Labels:: Specifying the assembler name to use for a C symbol.
1.1.1.8 ! root 2289: * Explicit Reg Vars:: Defining variables residing in specified registers.
! 2290: * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
1.1 root 2291: @end menu
2292:
2293: @node Statement Exprs, Naming Types, Extensions, Extensions
2294: @section Statements and Declarations inside of Expressions
2295:
2296: A compound statement in parentheses may appear inside an expression in GNU
2297: C. This allows you to declare variables within an expression. For
2298: example:
2299:
2300: @example
2301: (@{ int y = foo (); int z;
2302: if (y > 0) z = y;
2303: else z = - y;
2304: z; @})
2305: @end example
2306:
2307: @noindent
2308: is a valid (though slightly more complex than necessary) expression
2309: for the absolute value of @code{foo ()}.
2310:
2311: This feature is especially useful in making macro definitions ``safe'' (so
2312: that they evaluate each operand exactly once). For example, the
2313: ``maximum'' function is commonly defined as a macro in standard C as
2314: follows:
2315:
2316: @example
2317: #define max(a,b) ((a) > (b) ? (a) : (b))
2318: @end example
2319:
2320: @noindent
2321: But this definition computes either @var{a} or @var{b} twice, with bad
2322: results if the operand has side effects. In GNU C, if you know the
2323: type of the operands (here let's assume @code{int}), you can define
2324: the macro safely as follows:
2325:
2326: @example
2327: #define maxint(a,b) \
2328: (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
2329: @end example
2330:
2331: Embedded statements are not allowed in constant expressions, such as
2332: the value of an enumeration constant, the width of a bit field, or
2333: the initial value of a static variable.
2334:
2335: If you don't know the type of the operand, you can still do this, but you
2336: must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming
2337: Types}).
2338:
2339: @node Naming Types, Typeof, Statement Exprs, Extensions
2340: @section Naming an Expression's Type
2341:
2342: You can give a name to the type of an expression using a @code{typedef}
2343: declaration with an initializer. Here is how to define @var{name} as a
2344: type name for the type of @var{exp}:
2345:
2346: @example
2347: typedef @var{name} = @var{exp};
2348: @end example
2349:
2350: This is useful in conjunction with the statements-within-expressions
2351: feature. Here is how the two together can be used to define a safe
2352: ``maximum'' macro that operates on any arithmetic type:
2353:
2354: @example
2355: #define max(a,b) \
2356: (@{typedef _ta = (a), _tb = (b); \
2357: _ta _a = (a); _tb _b = (b); \
2358: _a > _b ? _a : _b; @})
2359: @end example
2360:
2361: The reason for using names that start with underscores for the local
2362: variables is to avoid conflicts with variable names that occur within the
2363: expressions that are substituted for @code{a} and @code{b}. Eventually we
2364: hope to design a new form of declaration syntax that allows you to declare
2365: variables whose scopes start only after their initializers; this will be a
2366: more reliable way to prevent such conflicts.
2367:
2368: @node Typeof, Lvalues, Naming Types, Extensions
2369: @section Referring to a Type with @code{typeof}
2370:
2371: Another way to refer to the type of an expression is with @code{typeof}.
2372: The syntax of using of this keyword looks like @code{sizeof}, but the
2373: construct acts semantically like a type name defined with @code{typedef}.
2374:
2375: There are two ways of writing the argument to @code{typeof}: with an
2376: expression or with a type. Here is an example with an expression:
2377:
2378: @example
2379: typeof (x[0](1))
2380: @end example
2381:
2382: @noindent
2383: This assumes that @code{x} is an array of functions; the type described
2384: is that of the values of the functions.
2385:
2386: Here is an example with a typename as the argument:
2387:
2388: @example
2389: typeof (int *)
2390: @end example
2391:
2392: @noindent
2393: Here the type described is that of pointers to @code{int}.
2394:
1.1.1.7 root 2395: If you are writing a header file that must work when included in ANSI C
1.1.1.8 ! root 2396: programs, write @code{__typeof__} instead of @code{typeof}.
1.1.1.7 root 2397: @xref{Alternate Keywords}.
2398:
1.1 root 2399: A @code{typeof}-construct can be used anywhere a typedef name could be
2400: used. For example, you can use it in a declaration, in a cast, or inside
2401: of @code{sizeof} or @code{typeof}.
2402:
2403: @itemize @bullet
2404: @item
2405: This declares @code{y} with the type of what @code{x} points to.
2406:
2407: @example
2408: typeof (*x) y;
2409: @end example
2410:
2411: @item
2412: This declares @code{y} as an array of such values.
2413:
2414: @example
2415: typeof (*x) y[4];
2416: @end example
2417:
2418: @item
2419: This declares @code{y} as an array of pointers to characters:
2420:
2421: @example
2422: typeof (typeof (char *)[4]) y;
2423: @end example
2424:
2425: @noindent
2426: It is equivalent to the following traditional C declaration:
2427:
2428: @example
2429: char *y[4];
2430: @end example
2431:
2432: To see the meaning of the declaration using @code{typeof}, and why it
2433: might be a useful way to write, let's rewrite it with these macros:
2434:
2435: @example
2436: #define pointer(T) typeof(T *)
2437: #define array(T, N) typeof(T [N])
2438: @end example
2439:
2440: @noindent
2441: Now the declaration can be rewritten this way:
2442:
2443: @example
2444: array (pointer (char), 4) y;
2445: @end example
2446:
2447: @noindent
1.1.1.8 ! root 2448: Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
1.1 root 2449: pointers to @code{char}.
2450: @end itemize
2451:
2452: @node Lvalues, Conditionals, Typeof, Extensions
2453: @section Generalized Lvalues
2454:
2455: Compound expressions, conditional expressions and casts are allowed as
2456: lvalues provided their operands are lvalues. This means that you can take
2457: their addresses or store values into them.
2458:
2459: For example, a compound expression can be assigned, provided the last
2460: expression in the sequence is an lvalue. These two expressions are
2461: equivalent:
2462:
2463: @example
2464: (a, b) += 5
2465: a, (b += 5)
2466: @end example
2467:
2468: Similarly, the address of the compound expression can be taken. These two
2469: expressions are equivalent:
2470:
2471: @example
2472: &(a, b)
2473: a, &b
2474: @end example
2475:
2476: A conditional expression is a valid lvalue if its type is not void and the
2477: true and false branches are both valid lvalues. For example, these two
2478: expressions are equivalent:
2479:
2480: @example
2481: (a ? b : c) = 5
2482: (a ? b = 5 : (c = 5))
2483: @end example
2484:
2485: A cast is a valid lvalue if its operand is valid. Taking the address of
2486: the cast is the same as taking the address without a cast, except for the
2487: type of the result. For example, these two expressions are equivalent (but
1.1.1.8 ! root 2488: the second may be valid when the type of @code{a} does not permit a cast to
! 2489: @code{int *}).
1.1 root 2490:
2491: @example
2492: &(int *)a
2493: (int **)&a
2494: @end example
2495:
2496: A simple assignment whose left-hand side is a cast works by converting the
2497: right-hand side first to the specified type, then to the type of the inner
2498: left-hand side expression. After this is stored, the value is converter
2499: back to the specified type to become the value of the assignment. Thus, if
1.1.1.8 ! root 2500: @code{a} has type @code{char *}, the following two expressions are
1.1 root 2501: equivalent:
2502:
2503: @example
2504: (int)a = 5
2505: (int)(a = (char *)5)
2506: @end example
2507:
2508: An assignment-with-arithmetic operation such as @samp{+=} applied to a cast
2509: performs the arithmetic using the type resulting from the cast, and then
2510: continues as in the previous case. Therefore, these two expressions are
2511: equivalent:
2512:
2513: @example
2514: (int)a += 5
2515: (int)(a = (char *) ((int)a + 5))
2516: @end example
2517:
2518: @node Conditionals, Zero-Length, Lvalues, Extensions
2519: @section Conditional Expressions with Omitted Middle-Operands
2520:
2521: The middle operand in a conditional expression may be omitted. Then
2522: if the first operand is nonzero, its value is the value of the conditional
2523: expression.
2524:
2525: Therefore, the expression
2526:
2527: @example
2528: x ? : y
2529: @end example
2530:
2531: @noindent
2532: has the value of @code{x} if that is nonzero; otherwise, the value of
2533: @code{y}.
2534:
2535: This example is perfectly equivalent to
2536:
2537: @example
2538: x ? x : y
2539: @end example
2540:
2541: @noindent
2542: In this simple case, the ability to omit the middle operand is not
2543: especially useful. When it becomes useful is when the first operand does,
2544: or may (if it is a macro argument), contain a side effect. Then repeating
2545: the operand in the middle would perform the side effect twice. Omitting
2546: the middle operand uses the value already computed without the undesirable
2547: effects of recomputing it.
2548:
2549: @node Zero-Length, Variable-Length, Conditionals, Extensions
2550: @section Arrays of Length Zero
2551:
2552: Zero-length arrays are allowed in GNU C. They are very useful as the last
2553: element of a structure which is really a header for a variable-length
2554: object:
2555:
2556: @example
2557: struct line @{
2558: int length;
2559: char contents[0];
2560: @};
2561:
2562: @{
2563: struct line *thisline
2564: = (struct line *) malloc (sizeof (struct line) + this_length);
2565: thisline->length = this_length;
2566: @}
2567: @end example
2568:
2569: In standard C, you would have to give @code{contents} a length of 1, which
2570: means either you waste space or complicate the argument to @code{malloc}.
2571:
2572: @node Variable-Length, Subscripting, Zero-Length, Extensions
2573: @section Arrays of Variable Length
2574:
2575: Variable-length automatic arrays are allowed in GNU C. These arrays are
2576: declared like any other automatic arrays, but with a length that is not a
2577: constant expression. The storage is allocated at that time and
2578: deallocated when the brace-level is exited. For example:
2579:
2580: @example
2581: FILE *concat_fopen (char *s1, char *s2, char *mode)
2582: @{
2583: char str[strlen (s1) + strlen (s2) + 1];
2584: strcpy (str, s1);
2585: strcat (str, s2);
2586: return fopen (str, mode);
2587: @}
2588: @end example
2589:
1.1.1.7 root 2590: You can also use variable-length arrays as arguments to functions:
1.1 root 2591:
2592: @example
2593: struct entry
1.1.1.7 root 2594: tester (int len, char data[len])
1.1 root 2595: @{
1.1.1.7 root 2596: @dots{}
1.1 root 2597: @}
2598: @end example
2599:
2600: The length of an array is computed on entry to the brace-level where the
2601: array is declared and is remembered for the scope of the array in case you
2602: access it with @code{sizeof}.
2603:
2604: Jumping or breaking out of the scope of the array name will also deallocate
2605: the storage. Jumping into the scope is not allowed; you will get an error
2606: message for it.
2607:
2608: You can use the function @code{alloca} to get an effect much like
2609: variable-length arrays. The function @code{alloca} is available in
2610: many other C implementations (but not in all). On the other hand,
2611: variable-length arrays are more elegant.
2612:
2613: There are other differences between these two methods. Space allocated
2614: with @code{alloca} exists until the containing @emph{function} returns.
2615: The space for a variable-length array is deallocated as soon as the array
2616: name's scope ends. (If you use both variable-length arrays and
2617: @code{alloca} in the same function, deallocation of a variable-length array
2618: will also deallocate anything more recently allocated with @code{alloca}.)
2619:
2620: @node Subscripting, Pointer Arith, Variable-Length, Extensions
2621: @section Non-Lvalue Arrays May Have Subscripts
2622:
2623: Subscripting is allowed on arrays that are not lvalues, even though the
2624: unary @samp{&} operator is not. For example, this is valid in GNU C though
2625: not valid in other C dialects:
2626:
2627: @example
2628: struct foo @{int a[4];@};
2629:
2630: struct foo f();
2631:
2632: bar (int index)
2633: @{
2634: return f().a[index];
2635: @}
2636: @end example
2637:
2638: @node Pointer Arith, Initializers, Subscripting, Extensions
2639: @section Arithmetic on @code{void}-Pointers and Function Pointers
2640:
2641: In GNU C, addition and subtraction operations are supported on pointers to
2642: @code{void} and on pointers to functions. This is done by treating the
2643: size of a @code{void} or of a function as 1.
2644:
2645: A consequence of this is that @code{sizeof} is also allowed on @code{void}
2646: and on function types, and returns 1.
2647:
1.1.1.8 ! root 2648: The option @samp{-Wpointer-arith} requests a warning if these extensions
! 2649: are used.
! 2650:
1.1 root 2651: @node Initializers, Constructors, Pointer Arith, Extensions
2652: @section Non-Constant Initializers
2653:
1.1.1.8 ! root 2654: The elements of an aggregate initializer for an automatic variable are
! 2655: not required to be constant expressions in GNU C. Here is an example of
! 2656: an initializer with run-time varying elements:
1.1 root 2657:
2658: @example
2659: foo (float f, float g)
2660: @{
2661: float beat_freqs[2] = @{ f-g, f+g @};
2662: @dots{}
2663: @}
2664: @end example
2665:
1.1.1.5 root 2666: @node Constructors, Function Attributes, Initializers, Extensions
1.1 root 2667: @section Constructor Expressions
2668:
2669: GNU C supports constructor expressions. A constructor looks like a cast
2670: containing an initializer. Its value is an object of the type specified in
2671: the cast, containing the elements specified in the initializer. The type
2672: must be a structure, union or array type.
2673:
2674: Assume that @code{struct foo} and @code{structure} are declared as shown:
2675:
2676: @example
2677: struct foo @{int a; char b[2];@} structure;
2678: @end example
2679:
2680: @noindent
1.1.1.8 ! root 2681: Here is an example of constructing a @code{struct foo} with a constructor:
1.1 root 2682:
2683: @example
2684: structure = ((struct foo) @{x + y, 'a', 0@});
2685: @end example
2686:
2687: @noindent
2688: This is equivalent to writing the following:
2689:
2690: @example
2691: @{
2692: struct foo temp = @{x + y, 'a', 0@};
2693: structure = temp;
2694: @}
2695: @end example
2696:
2697: You can also construct an array. If all the elements of the constructor
2698: are (made up of) simple constant expressions, suitable for use in
2699: initializers, then the constructor is an lvalue and can be coerced to a
2700: pointer to its first element, as shown here:
2701:
2702: @example
2703: char **foo = (char *[]) @{ "x", "y", "z" @};
2704: @end example
2705:
2706: Array constructors whose elements are not simple constants are not very
2707: useful, because the constructor is not an lvalue. There are only two valid
2708: ways to use it: to subscript it, or initialize an array variable with it.
2709: The former is probably slower than a @code{switch} statement, while the
2710: latter does the same thing an ordinary C initializer would do.
2711:
2712: @example
2713: output = ((int[]) @{ 2, x, 28 @}) [input];
2714: @end example
2715:
1.1.1.8 ! root 2716: @node Function Attributes, Dollar Signs, Constructors, Extensions
1.1.1.5 root 2717: @section Declaring Attributes of Functions
2718:
2719: In GNU C, you declare certain things about functions called in your program
2720: which help the compiler optimize function calls.
2721:
2722: A few functions, such as @code{abort} and @code{exit}, cannot return.
2723: These functions should be declared @code{volatile}. For example,
2724:
2725: @example
2726: extern volatile void abort ();
2727: @end example
2728:
2729: @noindent
2730: tells the compiler that it can assume that @code{abort} will not return.
2731: This makes slightly better code, but more importantly it helps avoid
2732: spurious warnings of uninitialized variables.
2733:
2734: Many functions do not examine any values except their arguments, and
2735: have no effects except the return value. Such a function can be subject
2736: to common subexpression elimination and loop optimization just as an
2737: arithmetic operator would be. These functions should be declared
2738: @code{const}. For example,
2739:
2740: @example
2741: extern const void square ();
2742: @end example
2743:
2744: @noindent
2745: says that the hypothetical function @code{square} is safe to call
2746: fewer times than the program says.
2747:
2748: Note that a function that has pointer arguments and examines the data
2749: pointed to must @emph{not} be declared @code{const}. Likewise, a
2750: function that calls a non-@code{const} function must not be
2751: @code{const}.
2752:
2753: Some people object to this feature, claiming that ANSI C's @code{#pragma}
2754: should be used instead. There are two reasons I did not do this.
2755:
2756: @enumerate
2757: @item
2758: It is impossible to generate @code{#pragma} commands from a macro.
2759:
2760: @item
2761: The @code{#pragma} command is just as likely as these keywords to mean
2762: something else in another compiler.
2763: @end enumerate
2764:
2765: These two reasons apply to @emph{any} application whatever: as far as
2766: I can see, @code{#pragma} is never useful.
2767:
2768: @node Dollar Signs, Alignment, Function Attributes, Extensions
1.1 root 2769: @section Dollar Signs in Identifier Names
2770:
2771: In GNU C, you may use dollar signs in identifier names. This is because
2772: many traditional C implementations allow such identifiers.
2773:
2774: @node Alignment, Inline, Dollar Signs, Extensions
2775: @section Inquiring about the Alignment of a Type or Variable
2776:
1.1.1.8 ! root 2777: The keyword @code{__alignof__} allows you to inquire about how an object
1.1 root 2778: is aligned, or the minimum alignment usually required by a type. Its
2779: syntax is just like @code{sizeof}.
2780:
2781: For example, if the target machine requires a @code{double} value to be
1.1.1.8 ! root 2782: aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
! 2783: This is true on many RISC machines. On more traditional machine
! 2784: designs, @code{__alignof__ (double)} is 4 or even 2.
1.1 root 2785:
2786: Some machines never actually require alignment; they allow reference to any
1.1.1.8 ! root 2787: data type even at an odd addresses. For these machines, @code{__alignof__}
1.1 root 2788: reports the @emph{recommended} alignment of a type.
2789:
1.1.1.8 ! root 2790: When the operand of @code{__alignof__} is an lvalue rather than a type, the
1.1 root 2791: value is the largest alignment that the lvalue is known to have. It may
2792: have this alignment as a result of its data type, or because it is part of
2793: a structure and inherits alignment from that structure. For example, after
2794: this declaration:
2795:
2796: @example
2797: struct foo @{ int x; char y; @} foo1;
2798: @end example
2799:
2800: @noindent
1.1.1.8 ! root 2801: the value of @code{__alignof__ (foo1.y)} is probably 2 or 4, the same as
! 2802: @code{__alignof__ (int)}, even though the data type of @code{foo1.y}
! 2803: does not itself demand any alignment.@refill
1.1 root 2804:
2805: @node Inline, Extended Asm, Alignment, Extensions
2806: @section An Inline Function is As Fast As a Macro
2807:
2808: By declaring a function @code{inline}, you can direct GNU CC to integrate
2809: that function's code into the code for its callers. This makes execution
2810: faster by eliminating the function-call overhead; in addition, if any of
2811: the actual argument values are constant, their known values may permit
2812: simplifications at compile time so that not all of the inline function's
2813: code needs to be included.
2814:
2815: To declare a function inline, use the @code{inline} keyword in its
2816: declaration, like this:
2817:
2818: @example
2819: inline int
2820: inc (int *a)
2821: @{
2822: (*a)++;
2823: @}
2824: @end example
2825:
1.1.1.7 root 2826: (If you are writing a header file to be included in ANSI C programs, write
1.1.1.8 ! root 2827: @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.)
1.1.1.7 root 2828:
2829: You can also make all ``simple enough'' functions inline with the option
2830: @samp{-finline-functions}. Note that certain usages in a function
2831: definition can make it unsuitable for inline substitution.
1.1 root 2832:
2833: When a function is both inline and @code{static}, if all calls to the
1.1.1.8 ! root 2834: function are integrated into the caller, and the function's address is
! 2835: never used, then the function's own assembler code is never referenced.
! 2836: In this case, GNU CC does not actually output assembler code for the
! 2837: function, unless you specify the option @samp{-fkeep-inline-functions}.
! 2838: Some calls cannot be integrated for various reasons (in particular,
! 2839: calls that precede the function's definition cannot be integrated, and
! 2840: neither can recursive calls within the definition). If there is a
! 2841: nonintegrated call, then the function is compiled to assembler code as
! 2842: usual. The function must also be compiled as usual if the program
! 2843: refers to its address, because that can't be inlined.
1.1 root 2844:
2845: When an inline function is not @code{static}, then the compiler must assume
2846: that there may be calls from other source files; since a global symbol can
2847: be defined only once in any program, the function must not be defined in
2848: the other source files, so the calls therein cannot be integrated.
2849: Therefore, a non-@code{static} inline function is always compiled on its
2850: own in the usual fashion.
2851:
1.1.1.8 ! root 2852: If you specify both @code{inline} and @code{extern} in the function
! 2853: definition, then the definition is used only for inlining. In no case
! 2854: is the function compiled on its own, not even if you refer to its
! 2855: address explicitly. Such an address becomes an external reference, as
! 2856: if you had only declared the function, and had not defined it.
! 2857:
! 2858: This combination of @code{inline} and @code{extern} has almost the
! 2859: effect of a macro. The way to use it is to put a function definition in
! 2860: a header file with these keywords, and put another copy of the
! 2861: definition (lacking @code{inline} and @code{extern}) in a library file.
! 2862: The definition in the header file will cause most calls to the function
! 2863: to be inlined. If any uses of the function remain, they will refer to
! 2864: the single copy in the library.
! 2865:
1.1 root 2866: @node Extended Asm, Asm Labels, Inline, Extensions
2867: @section Assembler Instructions with C Expression Operands
2868:
2869: In an assembler instruction using @code{asm}, you can now specify the
2870: operands of the instruction using C expressions. This means no more
2871: guessing which registers or memory locations will contain the data you want
2872: to use.
2873:
2874: You must specify an assembler instruction template much like what appears
2875: in a machine description, plus an operand constraint string for each
2876: operand.
2877:
2878: For example, here is how to use the 68881's @code{fsinx} instruction:
2879:
2880: @example
2881: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
2882: @end example
2883:
2884: @noindent
2885: Here @code{angle} is the C expression for the input operand while
2886: @code{result} is that of the output operand. Each has @samp{"f"} as its
2887: operand constraint, saying that a floating-point register is required. The
1.1.1.5 root 2888: @samp{=} in @samp{=f} indicates that the operand is an output; all output
1.1.1.4 root 2889: operands' constraints must use @samp{=}. The constraints use the same
2890: language used in the machine description (@pxref{Constraints}).
1.1 root 2891:
2892: Each operand is described by an operand-constraint string followed by the C
2893: expression in parentheses. A colon separates the assembler template from
2894: the first output operand, and another separates the last output operand
2895: from the first input, if any. Commas separate output operands and separate
1.1.1.4 root 2896: inputs. The total number of operands is limited to the maximum number of
1.1 root 2897: operands in any instruction pattern in the machine description.
2898:
1.1.1.4 root 2899: If there are no output operands, and there are input operands, then there
2900: must be two consecutive colons surrounding the place where the output
2901: operands would go.
2902:
1.1 root 2903: Output operand expressions must be lvalues; the compiler can check this.
2904: The input operands need not be lvalues. The compiler cannot check whether
2905: the operands have data types that are reasonable for the instruction being
2906: executed. It does not parse the assembler instruction template and does
2907: not know what it means, or whether it is valid assembler input. The
2908: extended @code{asm} feature is most often used for machine instructions
2909: that the compiler itself does not know exist.
2910:
2911: The output operands must be write-only; GNU CC will assume that the values
2912: in these operands before the instruction are dead and need not be
1.1.1.8 ! root 2913: generated. Extended asm does not support input-output or read-write
! 2914: operands. For this reason, the constraint character @samp{+}, which
! 2915: indicates such an operand, may not be used.
! 2916:
! 2917: When the assembler instruction has a read-write operand, or an operand
! 2918: in which only some of the bits are to be changed, you must logically
1.1 root 2919: split its function into two separate operands, one input operand and one
2920: write-only output operand. The connection between them is expressed by
2921: constraints which say they need to be in the same location when the
1.1.1.8 ! root 2922: instruction executes. You can use the same C expression for both
! 2923: operands, or different expressions. For example, here we write the
! 2924: (fictitious) @samp{combine} instruction with @code{bar} as its read-only
! 2925: source operand and @code{foo} as its read-write destination:
1.1 root 2926:
2927: @example
2928: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
2929: @end example
2930:
2931: @noindent
2932: The constraint @samp{"0"} for operand 1 says that it must occupy the same
1.1.1.5 root 2933: location as operand 0. A digit in constraint is allowed only in an input
2934: operand, and it must refer to an output operand.
1.1 root 2935:
2936: Only a digit in the constraint can guarantee that one operand will be in
2937: the same place as another. The mere fact that @code{foo} is the value of
2938: both operands is not enough to guarantee that they will be in the same
2939: place in the generated assembler code. The following would not work:
2940:
2941: @example
2942: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
2943: @end example
2944:
2945: Various optimizations or reloading could cause operands 0 and 1 to be in
2946: different registers; GNU CC knows no reason not to do so. For example, the
2947: compiler might find a copy of the value of @code{foo} in one register and
2948: use it for operand 1, but generate the output operand 0 in a different
2949: register (copying it afterward to @code{foo}'s own address). Of course,
2950: since the register for operand 1 is not even mentioned in the assembler
2951: code, the result will not work, but GNU CC can't tell that.
2952:
2953: Unless an output operand has the @samp{&} constraint modifier, GNU CC may
2954: allocate it in the same register as an unrelated input operand, on the
2955: assumption that the inputs are consumed before the outputs are produced.
2956: This assumption may be false if the assembler code actually consists of
2957: more than one instruction. In such a case, use @samp{&} for each output
2958: operand that may not overlap an input. @xref{Modifiers}.
2959:
1.1.1.4 root 2960: Some instructions clobber specific hard registers. To describe this, write
2961: a third colon after the input operands, followed by the names of the
2962: clobbered hard registers (given as strings). Here is a realistic example
2963: for the vax:
1.1 root 2964:
2965: @example
2966: asm volatile ("movc3 %0,%1,%2"
2967: : /* no outputs */
2968: : "g" (from), "g" (to), "g" (count)
2969: : "r0", "r1", "r2", "r3", "r4", "r5");
2970: @end example
2971:
1.1.1.4 root 2972: You can put multiple assembler instructions together in a single @code{asm}
1.1.1.7 root 2973: template, separated either with newlines (written as @samp{\n}) or with
2974: semicolons if the assembler allows such semicolons. The GNU assembler
2975: allows semicolons and all Unix assemblers seem to do so. The input
2976: operands are guaranteed not to use any of the clobbered registers, and
2977: neither will the output operands' addresses, so you can read and write the
2978: clobbered registers as many times as you like. Here is an example of
2979: multiple instructions in a template; it assumes that the subroutine
2980: @code{_foo} accepts arguments in registers 9 and 10:
1.1.1.4 root 2981:
2982: @example
2983: asm ("movl %0,r9;movl %1,r10;call _foo"
2984: : /* no outputs */
2985: : "g" (from), "g" (to)
2986: : "r9", "r10");
2987: @end example
2988:
1.1.1.7 root 2989: If you want to test the condition code produced by an assembler instruction,
2990: you must include a branch and a label in the @code{asm} construct, as follows:
2991:
2992: @example
2993: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
2994: : "g" (result)
2995: : "g" (input));
2996: @end example
2997:
2998: @noindent
2999: This assumes your assembler supports local labels, as the GNU assembler
3000: and most Unix assemblers do.
3001:
1.1 root 3002: Usually the most convenient way to use these @code{asm} instructions is to
3003: encapsulate them in macros that look like functions. For example,
3004:
3005: @example
3006: #define sin(x) \
3007: (@{ double __value, __arg = (x); \
3008: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
3009: __value; @})
3010: @end example
3011:
3012: @noindent
3013: Here the variable @code{__arg} is used to make sure that the instruction
3014: operates on a proper @code{double} value, and to accept only those
3015: arguments @code{x} which can convert automatically to a @code{double}.
3016:
3017: Another way to make sure the instruction operates on the correct data type
3018: is to use a cast in the @code{asm}. This is different from using a
3019: variable @code{__arg} in that it converts more different types. For
3020: example, if the desired type were @code{int}, casting the argument to
3021: @code{int} would accept a pointer with no complaint, while assigning the
3022: argument to an @code{int} variable named @code{__arg} would warn about
3023: using a pointer unless the caller explicitly casts it.
3024:
1.1.1.4 root 3025: If an @code{asm} has output operands, GNU CC assumes for optimization
3026: purposes that the instruction has no side effects except to change the
3027: output operands. This does not mean that instructions with a side effect
3028: cannot be used, but you must be careful, because the compiler may eliminate
3029: them if the output operands aren't used, or move them out of loops, or
3030: replace two with one if they constitute a common subexpression. Also, if
3031: your instruction does have a side effect on a variable that otherwise
3032: appears not to change, the old value of the variable may be reused later if
3033: it happens to be found in a register.
1.1 root 3034:
3035: You can prevent an @code{asm} instruction from being deleted, moved or
3036: combined by writing the keyword @code{volatile} after the @code{asm}. For
3037: example:
3038:
3039: @example
3040: #define set_priority(x) \
3041: asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
3042: @end example
3043:
1.1.1.7 root 3044: @noindent
3045: (However, an instruction without output operands will not be deleted
3046: or moved, regardless, unless it is unreachable.)
1.1.1.4 root 3047:
1.1 root 3048: It is a natural idea to look for a way to give access to the condition
3049: code left by the assembler instruction. However, when we attempted to
3050: implement this, we found no way to make it work reliably. The problem
3051: is that output operands might need reloading, which would result in
3052: additional following ``store'' instructions. On most machines, these
3053: instructions would alter the condition code before there was time to
3054: test it. This problem doesn't arise for ordinary ``test'' and
3055: ``compare'' instructions because they don't have any output operands.
3056:
1.1.1.7 root 3057: If you are writing a header file that should be includable in ANSI C
1.1.1.8 ! root 3058: programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate
1.1.1.7 root 3059: Keywords}.
3060:
1.1.1.8 ! root 3061: @node Asm Labels, Explicit Reg Vars, Extended Asm, Extensions
1.1 root 3062: @section Controlling Names Used in Assembler Code
3063:
1.1.1.8 ! root 3064: You can specify the name to be used in the assembler code for a C
! 3065: function or variable by writing the @code{asm} (or @code{__asm__})
! 3066: keyword after the declarator as follows:
1.1 root 3067:
3068: @example
3069: int foo asm ("myfoo") = 2;
3070: @end example
3071:
3072: @noindent
3073: This specifies that the name to be used for the variable @code{foo} in
3074: the assembler code should be @samp{myfoo} rather than the usual
3075: @samp{_foo}.
3076:
3077: On systems where an underscore is normally prepended to the name of a C
3078: function or variable, this feature allows you to define names for the
3079: linker that do not start with an underscore.
3080:
3081: You cannot use @code{asm} in this way in a function @emph{definition}; but
3082: you can get the same effect by writing a declaration for the function
3083: before its definition and putting @code{asm} there, like this:
3084:
3085: @example
3086: extern func () asm ("FUNC");
3087:
3088: func (x, y)
3089: int x, y;
3090: @dots{}
3091: @end example
3092:
3093: It is up to you to make sure that the assembler names you choose do not
3094: conflict with any other assembler symbols. Also, you must not use a
3095: register name; that would produce completely invalid assembler code. GNU
3096: CC does not as yet have the ability to store static variables in registers.
3097: Perhaps that will be added.
3098:
1.1.1.8 ! root 3099: @node Explicit Reg Vars, Alternate Keywords, Asm Labels, Extensions
! 3100: @section Variables in Specified Registers
! 3101:
! 3102: GNU C allows you to put a few global variables into specified hardware
! 3103: registers. You can also specify the register in which an ordinary
! 3104: register variable should be allocated.
! 3105:
! 3106: @itemize @bullet
! 3107: @item
! 3108: Global register variables reserve registers throughout the program.
! 3109: This may be useful in programs such as programming language
! 3110: interpreters which have a couple of global variables that are accessed
! 3111: very often.
! 3112:
! 3113: @item
! 3114: Local register variables in specific registers do not reserve the
! 3115: registers. The compiler's data flow analysis is capable of
! 3116: determining where the specified registers contain live values, and
! 3117: where they are available for other uses. These local variables are
! 3118: sometimes convenient for use with the extended @code{asm} feature
! 3119: (@pxref{Extended Asm}).
! 3120: @end itemize
! 3121:
! 3122: @menu
! 3123: * Global Reg Vars::
! 3124: * Local Reg Vars::
! 3125: @end menu
1.1.1.5 root 3126:
1.1.1.8 ! root 3127: @node Global Reg Vars, Local Reg Vars, Explicit Reg Vars, Explicit Reg Vars
! 3128: @subsection Defining Global Register Variables
1.1.1.5 root 3129:
3130: You can define a global register variable in GNU C like this:
3131:
3132: @example
3133: register int *foo asm ("a5");
3134: @end example
3135:
3136: @noindent
3137: Here @code{a5} is the name of the register which should be used. Choose a
3138: register which is normally saved and restored by function calls on your
3139: machine, so that library routines will not clobber it.
3140:
3141: Naturally the register name is cpu-dependent, so you would need to
3142: conditionalize your program according to cpu type. The register
3143: @code{a5} would be a good choice on a 68000 for a variable of pointer
3144: type. On machines with register windows, be sure to choose a ``global''
1.1.1.8 ! root 3145: register that is not affected magically by the function call mechanism.
1.1.1.5 root 3146:
3147: In addition, operating systems on one type of cpu may differ in how they
3148: name the registers; then you would need additional conditionals. For
3149: example, some 68000 operating systems call this register @code{%a5}.
3150:
3151: Eventually there may be a way of asking the compiler to choose a register
3152: automatically, but first we need to figure out how it should choose and
1.1.1.6 root 3153: how to enable you to guide the choice. No solution is evident.
1.1.1.5 root 3154:
3155: Defining a global register variable in a certain register reserves that
3156: register entirely for this use, at least within the current compilation.
3157: The register will not be allocated for any other purpose in the functions
3158: in the current compilation. The register will not be saved and restored by
3159: these functions. Stores into this register are never deleted even if they
3160: would appear to be dead, but references may be deleted or moved or
3161: simplified.
3162:
3163: It is not safe to access the global register variables from signal
3164: handlers, or from more than one thread of control, because the system
3165: library routines may temporarily use the register for other things (unless
3166: you recompile them specially for the task at hand).
3167:
3168: It is not safe for one function that uses a global register variable to
3169: call another such function @code{foo} by way of a third function
3170: @code{lose} that was compiled without knowledge of this variable (i.e. in a
3171: different source file in which the variable wasn't declared). This is
3172: because @code{lose} might save the register and put some other value there.
3173: For example, you can't expect a global register variable to be available in
3174: the comparison-function that you pass to @code{qsort}, since @code{qsort}
3175: might have put something else in that register. (If you are prepared to
3176: recompile @code{qsort} with the same global register variable, you can
3177: solve this problem.)
3178:
3179: If you want to recompile @code{qsort} or other source files which do not
3180: actually use your global register variable, so that they will not use that
3181: register for any other purpose, then it suffices to specify the compiler
3182: option @samp{-ffixed-@var{reg}}. You need not actually add a global
3183: register declaration to their source code.
3184:
3185: A function which can alter the value of a global register variable cannot
3186: safely be called from a function compiled without this variable, because it
3187: could clobber the value the caller expects to find there on return.
3188: Therefore, the function which is the entry point into the part of the
3189: program that uses the global register variable must explicitly save and
3190: restore the value which belongs to its caller.
3191:
3192: On most machines, @code{longjmp} will restore to each global register
3193: variable the value it had at the time of the @code{setjmp}. On some
3194: machines, however, @code{longjmp} will not change the value of global
3195: register variables. To be portable, the function that called @code{setjmp}
3196: should make other arrangements to save the values of the global register
3197: variables, and to restore them if a @code{longjmp}. This way, the the same
3198: thing will happen regardless of what @code{longjmp} does.
3199:
3200: All global register variable declarations must precede all function
3201: definitions. If such a declaration could appear after function
3202: definitions, the declaration would be too late to prevent the register from
3203: being used for other purposes in the preceding functions.
3204:
1.1.1.6 root 3205: Global register variables may not have initial values, because an
3206: executable file has no means to supply initial contents for a register.
3207:
1.1.1.8 ! root 3208: @node Local Reg Vars,, Local Reg Vars, Explicit Reg Vars
! 3209: @subsection Specifying Registers for Local Variables
! 3210:
! 3211: You can define a local register variable with a specified register
! 3212: like this:
! 3213:
! 3214: @example
! 3215: register int *foo asm ("a5");
! 3216: @end example
! 3217:
! 3218: @noindent
! 3219: Here @code{a5} is the name of the register which should be used. Note
! 3220: that this is the same syntax used for defining global register
! 3221: variables, but for a local variable it would appear within a function.
! 3222:
! 3223: Naturally the register name is cpu-dependent, but this is not a
! 3224: problem, since specific registers are most often useful with explicit
! 3225: assembler instructions (@pxref{Extended Asm}). Both of these things
! 3226: generally require that you conditionalize your program according to
! 3227: cpu type.
! 3228:
! 3229: In addition, operating systems on one type of cpu may differ in how they
! 3230: name the registers; then you would need additional conditionals. For
! 3231: example, some 68000 operating systems call this register @code{%a5}.
! 3232:
! 3233: Eventually there may be a way of asking the compiler to choose a register
! 3234: automatically, but first we need to figure out how it should choose and
! 3235: how to enable you to guide the choice. No solution is evident.
! 3236:
! 3237: Defining such a register variable does not reserve the register; it
! 3238: remains available for other uses in places where flow control
! 3239: determines the variable's value is not live. However, these registers
! 3240: made unavailable for use in the reload pass. I would not be surprised
! 3241: if excessive use of this feature leaves the compiler too few available
! 3242: registers to compile certain functions.
! 3243:
! 3244: @node Alternate Keywords,, Explicit Reg Vars, Extensions
1.1.1.7 root 3245: @section Alternate Keywords
3246:
3247: The option @samp{-traditional} disables certain keywords; @samp{-ansi}
3248: disables certain others. This causes trouble when you want to use GNU C
3249: extensions, or ANSI C features, in a general-purpose header file that
3250: should be usable by all programs, including ANSI C programs and traditional
3251: ones. The keywords @code{asm}, @code{typeof} and @code{inline} cannot be
3252: used since they won't work in a program compiled with @samp{-ansi}, while
3253: the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof}
3254: and @code{inline} won't work in a program compiled with
3255: @samp{-traditional}.@refill
3256:
1.1.1.8 ! root 3257: The way to solve these problems is to put @samp{__} at the beginning and
! 3258: end of each problematical keyword. For example, use @code{__asm__}
! 3259: instead of @code{asm}, @code{__const__} instead of @code{const}, and
! 3260: @code{__inline__} instead of @code{inline}.
1.1.1.7 root 3261:
3262: Other C compilers won't accept these alternative keywords; if you want to
3263: compile with another compiler, you can define the alternate keywords as
3264: macros to replace them with the customary keywords. It looks like this:
3265:
3266: @example
3267: #ifndef __GNUC__
1.1.1.8 ! root 3268: #define __asm__ asm
1.1.1.7 root 3269: #endif
3270: @end example
3271:
1.1 root 3272: @node Bugs, Portability, Extensions, Top
3273: @chapter Reporting Bugs
3274:
3275: Your bug reports play an essential role in making GNU CC reliable.
3276:
3277: Reporting a bug may help you by bringing a solution to your problem, or it
3278: may not. But in any case the important function of a bug report is to help
3279: the entire community by making the next version of GNU CC work better. Bug
3280: reports are your contribution to the maintenance of GNU CC.
3281:
3282: In order for a bug report to serve its purpose, you must include the
3283: information that makes for fixing the bug.
3284:
3285: @menu
3286: * Criteria: Bug Criteria. Have you really found a bug?
3287: * Reporting: Bug Reporting. How to report a bug effectively.
3288: @end menu
3289:
3290: @node Bug Criteria, Bug Reporting, Bugs, Bugs
3291: @section Have You Found a Bug?
3292:
3293: If you are not sure whether you have found a bug, here are some guidelines:
3294:
3295: @itemize @bullet
3296: @item
3297: If the compiler gets a fatal signal, for any input whatever, that is a
3298: compiler bug. Reliable compilers never crash.
3299:
3300: @item
3301: If the compiler produces invalid assembly code, for any input whatever
3302: (except an @code{asm} statement), that is a compiler bug, unless the
3303: compiler reports errors (not just warnings) which would ordinarily
3304: prevent the assembler from being run.
3305:
3306: @item
3307: If the compiler produces valid assembly code that does not correctly
3308: execute the input source code, that is a compiler bug.
3309:
3310: However, you must double-check to make sure, because you may have run
3311: into an incompatibility between GNU C and traditional C
3312: (@pxref{Incompatibilities}). These incompatibilities might be considered
3313: bugs, but they are inescapable consequences of valuable features.
3314:
3315: Or you may have a program whose behavior is undefined, which happened
3316: by chance to give the desired results with another C compiler.
3317:
3318: For example, in many nonoptimizing compilers, you can write @samp{x;}
3319: at the end of a function instead of @samp{return x;}, with the same
1.1.1.8 ! root 3320: results. But the value of the function is undefined if @code{return}
1.1 root 3321: is omitted; it is not a bug when GNU CC produces different results.
3322:
3323: Problems often result from expressions with two increment operators,
1.1.1.8 ! root 3324: as in @code{f (*p++, *p++)}. Your previous compiler might have
1.1 root 3325: interpreted that expression the way you intended; GNU CC might
1.1.1.8 ! root 3326: interpret it another way. Neither compiler is wrong. The bug is
! 3327: in your code.
1.1 root 3328:
3329: After you have localized the error to a single source line, it should
3330: be easy to check for these things. If your program is correct and
3331: well defined, you have found a compiler bug.
3332:
3333: @item
3334: If the compiler produces an error message for valid input, that is a
3335: compiler bug.
3336:
3337: Note that the following is not valid input, and the error message for
3338: it is not a bug:
3339:
3340: @example
3341: int foo (char);
3342:
3343: int
3344: foo (x)
3345: char x;
3346: @{ @dots{} @}
3347: @end example
3348:
3349: @noindent
3350: The prototype says to pass a @code{char}, while the definition says to
3351: pass an @code{int} and treat the value as a @code{char}. This is what
3352: the ANSI standard says, and it makes sense.
3353:
3354: @item
3355: If the compiler does not produce an error message for invalid input,
3356: that is a compiler bug. However, you should note that your idea of
3357: ``invalid input'' might be my idea of ``an extension'' or ``support
3358: for traditional practice''.
3359:
3360: @item
3361: If you are an experienced user of C compilers, your suggestions
3362: for improvement of GNU CC are welcome in any case.
3363: @end itemize
3364:
3365: @node Bug Reporting,, Bug Criteria, Bugs
3366: @section How to Report Bugs
3367:
3368: Send bug reports for GNU C to one of these addresses:
3369:
3370: @example
3371: bug-gcc@@prep.ai.mit.edu
3372: @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gcc
3373: @end example
3374:
1.1.1.8 ! root 3375: @strong{Do not send bug reports to @samp{info-gcc}, or to the newsgroup
! 3376: @samp{gnu.gcc}.} Most users of GNU CC do not want to receive bug
! 3377: reports. Those that do, have asked to be on @samp{bug-gcc}.
! 3378:
! 3379: The mailing list @samp{bug-gcc} has a newsgroup which serves as a
! 3380: repeater. The mailing list and the newsgroup carry exactly the same
! 3381: messages. Often people think of posting bug reports to the newsgroup
! 3382: instead of mailing them. This appears to work, but it has one problem
! 3383: which can be crucial: a newsgroup posting does not contain a mail path
! 3384: back to the sender. Thus, if I need to ask for more information, I
! 3385: may be unable to reach you. For this reason, it is better to send bug
! 3386: reports to the mailing list.
! 3387:
! 3388: As a last resort, send bug reports on paper to:
1.1 root 3389:
3390: @example
3391: GNU Compiler Bugs
3392: 545 Tech Sq
3393: Cambridge, MA 02139
3394: @end example
3395:
3396: The fundamental principle of reporting bugs usefully is this:
1.1.1.8 ! root 3397: @strong{report all the facts}. If you are not sure whether to state a
! 3398: fact or leave it out, state it!
1.1 root 3399:
3400: Often people omit facts because they think they know what causes the
3401: problem and they conclude that some details don't matter. Thus, you might
3402: assume that the name of the variable you use in an example does not matter.
3403: Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
3404: stray memory reference which happens to fetch from the location where that
3405: name is stored in memory; perhaps, if the name were different, the contents
3406: of that location would fool the compiler into doing the right thing despite
1.1.1.8 ! root 3407: the bug. Play it safe and give a specific, complete example. That is the
! 3408: easiest thing for you to do, and the most helpful.
1.1 root 3409:
1.1.1.8 ! root 3410: Keep in mind that the purpose of a bug report is to enable me to fix
! 3411: the bug if it is not known. It isn't very important what happens if
! 3412: the bug is already known. Therefore, always write your bug reports on
! 3413: the assumption that the bug is not known.
! 3414:
! 3415: Sometimes people give a few sketchy facts and ask, ``Does this ring a
! 3416: bell?'' Those bug reports are useless, and I urge everyone to
! 3417: @emph{refuse to respond to them} except to chide the sender to report
! 3418: bugs properly.
! 3419:
! 3420: To enable me to fix the bug, you should include all these things:
1.1 root 3421:
3422: @itemize @bullet
3423: @item
3424: The version of GNU CC. You can get this by running it with the
3425: @samp{-v} option.
3426:
3427: Without this, I won't know whether there is any point in looking for
3428: the bug in the current version of GNU CC.
3429:
3430: @item
3431: A complete input file that will reproduce the bug. If the bug is in
3432: the C preprocessor, send me a source file and any header files that it
3433: requires. If the bug is in the compiler proper (@file{cc1}), run your
3434: source file through the C preprocessor by doing @samp{gcc -E
3435: @var{sourcefile} > @var{outfile}}, then include the contents of
3436: @var{outfile} in the bug report. (Any @samp{-I}, @samp{-D} or
3437: @samp{-U} options that you used in actual compilation should also be
3438: used when doing this.)
3439:
3440: A single statement is not enough of an example. In order to compile
3441: it, it must be embedded in a function definition; and the bug might
3442: depend on the details of how this is done.
3443:
3444: Without a real example I can compile, all I can do about your bug
3445: report is wish you luck. It would be futile to try to guess how to
3446: provoke the bug. For example, bugs in register allocation and
3447: reloading frequently depend on every little detail of the function
3448: they happen in.
3449:
3450: @item
3451: The command arguments you gave GNU CC to compile that example and
3452: observe the bug. For example, did you use @samp{-O}? To guarantee
3453: you won't omit something important, list them all.
3454:
3455: If I were to try to guess the arguments, I would probably guess wrong
3456: and then I would not encounter the bug.
3457:
3458: @item
3459: The names of the files that you used for @file{tm.h} and @file{md}
3460: when you installed the compiler.
3461:
3462: @item
3463: The type of machine you are using, and the operating system name and
3464: version number.
3465:
3466: @item
3467: A description of what behavior you observe that you believe is
3468: incorrect. For example, ``It gets a fatal signal,'' or, ``There is an
3469: incorrect assembler instruction in the output.''
3470:
3471: Of course, if the bug is that the compiler gets a fatal signal, then I
3472: will certainly notice it. But if the bug is incorrect output, I might
3473: not notice unless it is glaringly wrong. I won't study all the
3474: assembler code from a 50-line C program just on the off chance that it
3475: might be wrong.
3476:
3477: Even if the problem you experience is a fatal signal, you should still
3478: say so explicitly. Suppose something strange is going on, such as,
3479: your copy of the compiler is out of synch, or you have encountered a
3480: bug in the C library on your system. (This has happened!) Your copy
3481: might crash and mine would not. If you @i{told} me to expect a crash,
3482: then when mine fails to crash, I would know that the bug was not
3483: happening for me. If you had not told me to expect a crash, then I
3484: would not be able to draw any conclusion from my observations.
3485:
1.1.1.8 ! root 3486: Often the observed symptom is incorrect output when your program is run.
! 3487: Sad to say, this is not enough information for me unless the program is
! 3488: short and simple. If you send me a large program, I don't have time to
! 3489: figure out how it would work if compiled correctly, much less which line
! 3490: of it was compiled wrong. So you will have to do that. Tell me which
! 3491: source line it is, and what incorrect result happens when that line is
! 3492: executed. A person who understands the test program can find this as
! 3493: easily as a bug in the program itself.
1.1 root 3494:
3495: @item
3496: If you send me examples of output from GNU CC, please use @samp{-g}
3497: when you make them. The debugging information includes source line
3498: numbers which are essential for correlating the output with the input.
3499:
3500: @item
3501: If you wish to suggest changes to the GNU CC source, send me context
3502: diffs. If you even discuss something in the GNU CC source, refer to
3503: it by context, not by line number.
3504:
3505: The line numbers in my development sources don't match those in your
3506: sources. Your line numbers would convey no useful information to me.
3507:
3508: @item
3509: Additional information from a debugger might enable me to find
3510: a problem on a machine which I do not have available myself.
3511: However, you need to think when you collect this information if
3512: you want it to have any chance of being useful.
3513:
3514: For example, many people send just a backtrace, but that is never
3515: useful by itself. A simple backtrace with arguments conveys little
3516: about GNU CC because the compiler is largely data-driven; the same
3517: functions are called over and over for different RTL insns, doing
3518: different things depending on the details of the insn.
3519:
3520: Most of the arguments listed in the backtrace are useless because they
3521: are pointers to RTL list structure. The numeric values of the
3522: pointers, which the debugger prints in the backtrace, have no
3523: significance whatever; all that matters is the contents of the objects
3524: they point to (and most of the contents are other such pointers).
3525:
3526: In addition, most compiler passes consist of one or more loops that
3527: scan the RTL insn sequence. The most vital piece of information about
1.1.1.8 ! root 3528: such a loop---which insn it has reached---is usually in a local variable,
1.1 root 3529: not in an argument.
3530:
3531: What you need to provide in addition to a backtrace are the values of
3532: the local variables for several stack frames up. When a local
3533: variable or an argument is an RTX, first print its value and then use
3534: the GDB command @code{pr} to print the RTL expression that it points
3535: to. (If GDB doesn't run on your machine, use your debugger to call
3536: the function @code{debug_rtx} with the RTX as an argument.) In
3537: general, whenever a variable is a pointer, its value is no use
3538: without the data it points to.
3539:
3540: In addition, include a debugging dump from just before the pass
3541: in which the crash happens. Most bugs involve a series of insns,
3542: not just one.
3543: @end itemize
3544:
3545: Here are some things that are not necessary:
3546:
3547: @itemize @bullet
3548: @item
3549: A description of the envelope of the bug.
3550:
3551: Often people who encounter a bug spend a lot of time investigating
3552: which changes to the input file will make the bug go away and which
3553: changes will not affect it.
3554:
3555: This is often time consuming and not very useful, because the way I
3556: will find the bug is by running a single example under the debugger
3557: with breakpoints, not by pure deduction from a series of examples.
1.1.1.8 ! root 3558: I recommend that you save your time for something else.
1.1 root 3559:
3560: Of course, if you can find a simpler example to report @emph{instead}
3561: of the original one, that is a convenience for me. Errors in the
3562: output will be easier to spot, running under the debugger will take
3563: less time, etc. Most GNU CC bugs involve just one function, so the
3564: most straightforward way to simplify an example is to delete all the
3565: function definitions except the one where the bug occurs. Those
3566: earlier in the file may be replaced by external declarations if the
1.1.1.8 ! root 3567: crucial function depends on them. (Exception: inline functions may
! 3568: affect compilation of functions defined later in the file.)
1.1 root 3569:
3570: However, simplification is not vital; if you don't want to do this,
1.1.1.8 ! root 3571: report the bug anyway and send me the entire test case you used.
1.1 root 3572:
3573: @item
3574: A patch for the bug.
3575:
3576: A patch for the bug does help me if it is a good one. But don't omit
1.1.1.8 ! root 3577: the necessary information, such as the test case, on the assumption that
! 3578: a patch is all I need. I might see problems with your patch and decide
! 3579: to fix the problem another way, or I might not understand it at all.
1.1 root 3580:
3581: Sometimes with a program as complicated as GNU CC it is very hard to
3582: construct an example that will make the program follow a certain path
3583: through the code. If you don't send me the example, I won't be able
3584: to construct one, so I won't be able to verify that the bug is fixed.
3585:
1.1.1.8 ! root 3586: And if I can't understand what bug you are trying to fix, or why your
! 3587: patch should be an improvement, I won't install it. A test case will
! 3588: help me to understand.
! 3589:
1.1 root 3590: @item
3591: A guess about what the bug is or what it depends on.
3592:
3593: Such guesses are usually wrong. Even I can't guess right about such
1.1.1.8 ! root 3594: things without first using the debugger to find the facts.
1.1 root 3595: @end itemize
3596:
3597: @node Portability, Interface, Bugs, Top
3598: @chapter GNU CC and Portability
3599:
3600: The main goal of GNU CC was to make a good, fast compiler for machines in
3601: the class that the GNU system aims to run on: 32-bit machines that address
3602: 8-bit bytes and have several general registers. Elegance, theoretical
3603: power and simplicity are only secondary.
3604:
3605: GNU CC gets most of the information about the target machine from a machine
3606: description which gives an algebraic formula for each of the machine's
3607: instructions. This is a very clean way to describe the target. But when
3608: the compiler needs information that is difficult to express in this
3609: fashion, I have not hesitated to define an ad-hoc parameter to the machine
3610: description. The purpose of portability is to reduce the total work needed
3611: on the compiler; it was not of interest for its own sake.
3612:
3613: GNU CC does not contain machine dependent code, but it does contain code
3614: that depends on machine parameters such as endianness (whether the most
3615: significant byte has the highest or lowest address of the bytes in a word)
3616: and the availability of autoincrement addressing. In the RTL-generation
3617: pass, it is often necessary to have multiple strategies for generating code
3618: for a particular kind of syntax tree, strategies that are usable for different
3619: combinations of parameters. Often I have not tried to address all possible
3620: cases, but only the common ones or only the ones that I have encountered.
3621: As a result, a new target may require additional strategies. You will know
3622: if this happens because the compiler will call @code{abort}. Fortunately,
3623: the new strategies can be added in a machine-independent fashion, and will
3624: affect only the target machines that need them.
3625:
3626: @node Interface, Passes, Portability, Top
3627: @chapter Interfacing to GNU CC Output
3628:
3629: GNU CC is normally configured to use the same function calling convention
3630: normally in use on the target system. This is done with the
3631: machine-description macros described (@pxref{Machine Macros}).
3632:
3633: However, returning of structure and union values is done differently on
3634: some target machines. As a result, functions compiled with PCC
3635: returning such types cannot be called from code compiled with GNU CC,
3636: and vice versa. This does not cause trouble often because few Unix
3637: library routines return structures or unions.
3638:
3639: GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes
3640: long in the same registers used for @code{int} or @code{double} return
3641: values. (GNU CC typically allocates variables of such types in
3642: registers also.) Structures and unions of other sizes are returned by
3643: storing them into an address passed by the caller (usually in a
3644: register). The machine-description macros @code{STRUCT_VALUE} and
3645: @code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address.
3646:
3647: By contrast, PCC on most target machines returns structures and unions
3648: of any size by copying the data into an area of static storage, and then
3649: returning the address of that storage as if it were a pointer value.
3650: The caller must copy the data from that memory area to the place where
3651: the value is wanted. This is slower than the method used by GNU CC, and
3652: fails to be reentrant.
3653:
3654: On some target machines, such as RISC machines and the 80386, the
3655: standard system convention is to pass to the subroutine the address of
3656: where to return the value. On these machines, GNU CC has been
3657: configured to be compatible with the standard compiler, when this method
3658: is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3659:
3660: GNU CC uses the system's standard convention for passing arguments. On
3661: some machines, the first few arguments are passed in registers; in
3662: others, all are passed on the stack. It would be possible to use
3663: registers for argument passing on any machine, and this would probably
3664: result in a significant speedup. But the result would be complete
3665: incompatibility with code that follows the standard convention. So this
3666: change is practical only if you are switching to GNU CC as the sole C
3667: compiler for the system. We may implement register argument passing on
3668: certain machines once we have a complete GNU system so that we can
3669: compile the libraries with GNU CC.
3670:
3671: If you use @code{longjmp}, beware of automatic variables. ANSI C says that
3672: automatic variables that are not declared @code{volatile} have undefined
3673: values after a @code{longjmp}. And this is all GNU CC promises to do,
3674: because it is very difficult to restore register variables correctly, and
3675: one of GNU CC's features is that it can put variables in registers without
3676: your asking it to.
3677:
3678: If you want a variable to be unaltered by @code{longjmp}, and you don't
3679: want to write @code{volatile} because old C compilers don't accept it,
3680: just take the address of the variable. If a variable's address is ever
3681: taken, even if just to compute it and ignore it, then the variable cannot
3682: go in a register:
3683:
3684: @example
3685: @{
3686: int careful;
3687: &careful;
3688: @dots{}
3689: @}
3690: @end example
3691:
3692: Code compiled with GNU CC may call certain library routines. Most of
3693: them handle arithmetic for which there are no instructions. This
3694: includes multiply and divide on some machines, and floating point
3695: operations on any machine for which floating point support is disabled
3696: with @samp{-msoft-float}. Some standard parts of the C library, such as
3697: @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3698: function call interface is used for calling the library routines.
3699:
3700: These library routines should be defined in the library @file{gnulib},
3701: which GNU CC automatically searches whenever it links a program. On
3702: machines that have multiply and divide instructions, if hardware
3703: floating point is in use, normally @file{gnulib} is not needed, but it
3704: is searched just in case.
3705:
3706: Each arithmetic function is defined in @file{gnulib.c} to use the
3707: corresponding C arithmetic operator. As long as the file is compiled
3708: with another C compiler, which supports all the C arithmetic operators,
3709: this file will work portably. However, @file{gnulib.c} does not work if
3710: compiled with GNU CC, because each arithmetic function would compile
3711: into a call to itself!
3712:
3713: @node Passes, RTL, Interface, Top
3714: @chapter Passes and Files of the Compiler
3715:
3716: The overall control structure of the compiler is in @file{toplev.c}. This
3717: file is responsible for initialization, decoding arguments, opening and
3718: closing files, and sequencing the passes.
3719:
3720: The parsing pass is invoked only once, to parse the entire input. The RTL
3721: intermediate code for a function is generated as the function is parsed, a
3722: statement at a time. Each statement is read in as a syntax tree and then
3723: converted to RTL; then the storage for the tree for the statement is
3724: reclaimed. Storage for types (and the expressions for their sizes),
3725: declarations, and a representation of the binding contours and how they nest,
3726: remains until the function is finished being compiled; these are all needed
3727: to output the debugging information.
3728:
3729: Each time the parsing pass reads a complete function definition or
3730: top-level declaration, it calls the function
3731: @code{rest_of_compilation} or @code{rest_of_decl_compilation} in
3732: @file{toplev.c}, which are responsible for all further processing
3733: necessary, ending with output of the assembler language. All other
3734: compiler passes run, in sequence, within @code{rest_of_compilation}.
3735: When that function returns from compiling a function definition, the
3736: storage used for that function definition's compilation is entirely
3737: freed, unless it is an inline function (@pxref{Inline}).
3738:
3739: Here is a list of all the passes of the compiler and their source files.
3740: Also included is a description of where debugging dumps can be requested
3741: with @samp{-d} options.
3742:
3743: @itemize @bullet
3744: @item
3745: Parsing. This pass reads the entire text of a function definition,
3746: constructing partial syntax trees. This and RTL generation are no longer
3747: truly separate passes (formerly they were), but it is easier to think
3748: of them as separate.
3749:
3750: The tree representation does not entirely follow C syntax, because it is
3751: intended to support other languages as well.
3752:
3753: C data type analysis is also done in this pass, and every tree node
3754: that represents an expression has a data type attached. Variables are
3755: represented as declaration nodes.
3756:
3757: Constant folding and associative-law simplifications are also done
3758: during this pass.
3759:
3760: The source files for parsing are @file{c-parse.y}, @file{c-decl.c},
3761: @file{c-typeck.c}, @file{c-convert.c}, @file{stor-layout.c},
3762: @file{fold-const.c}, and @file{tree.c}. The last three files are
3763: intended to be language-independent. There are also header files
3764: @file{c-parse.h}, @file{c-tree.h}, @file{tree.h} and @file{tree.def}.
3765: The last two define the format of the tree representation.@refill
3766:
3767: @item
3768: RTL generation. This is the conversion of syntax tree into RTL code.
3769: It is actually done statement-by-statement during parsing, but for
3770: most purposes it can be thought of as a separate pass.
3771:
3772: This is where the bulk of target-parameter-dependent code is found,
3773: since often it is necessary for strategies to apply only when certain
3774: standard kinds of instructions are available. The purpose of named
3775: instruction patterns is to provide this information to the RTL
3776: generation pass.
3777:
3778: Optimization is done in this pass for @code{if}-conditions that are
3779: comparisons, boolean operations or conditional expressions. Tail
3780: recursion is detected at this time also. Decisions are made about how
3781: best to arrange loops and how to output @code{switch} statements.
3782:
3783: The source files for RTL generation are @file{stmt.c}, @file{expr.c},
3784: @file{explow.c}, @file{expmed.c}, @file{optabs.c} and @file{emit-rtl.c}.
3785: Also, the file @file{insn-emit.c}, generated from the machine description
3786: by the program @code{genemit}, is used in this pass. The header files
3787: @file{expr.h} is used for communication within this pass.@refill
3788:
3789: The header files @file{insn-flags.h} and @file{insn-codes.h},
3790: generated from the machine description by the programs @code{genflags}
3791: and @code{gencodes}, tell this pass which standard names are available
3792: for use and which patterns correspond to them.@refill
3793:
3794: Aside from debugging information output, none of the following passes
3795: refers to the tree structure representation of the function (only
3796: part of which is saved).
3797:
3798: The decision of whether the function can and should be expanded inline
3799: in its subsequent callers is made at the end of rtl generation. The
3800: function must meet certain criteria, currently related to the size of
3801: the function and the types and number of parameters it has. Note that
3802: this function may contain loops, recursive calls to itself
3803: (tail-recursive functions can be inlined!), gotos, in short, all
3804: constructs supported by GNU CC.
3805:
3806: The option @samp{-dr} causes a debugging dump of the RTL code after
3807: this pass. This dump file's name is made by appending @samp{.rtl} to
3808: the input file name.
3809:
3810: @item
3811: Jump optimization. This pass simplifies jumps to the following
3812: instruction, jumps across jumps, and jumps to jumps. It deletes
3813: unreferenced labels and unreachable code, except that unreachable code
3814: that contains a loop is not recognized as unreachable in this pass.
3815: (Such loops are deleted later in the basic block analysis.)
3816:
3817: Jump optimization is performed two or three times. The first time is
3818: immediately following RTL generation. The second time is after CSE,
3819: but only if CSE says repeated jump optimization is needed. The
3820: last time is right before the final pass. That time, cross-jumping
3821: and deletion of no-op move instructions are done together with the
3822: optimizations described above.
3823:
3824: The source file of this pass is @file{jump.c}.
3825:
3826: The option @samp{-dj} causes a debugging dump of the RTL code after
3827: this pass is run for the first time. This dump file's name is made by
3828: appending @samp{.jump} to the input file name.
3829:
3830: @item
3831: Register scan. This pass finds the first and last use of each
3832: register, as a guide for common subexpression elimination. Its source
3833: is in @file{regclass.c}.
3834:
3835: @item
3836: Common subexpression elimination. This pass also does constant
3837: propagation. Its source file is @file{cse.c}. If constant
3838: propagation causes conditional jumps to become unconditional or to
3839: become no-ops, jump optimization is run again when CSE is finished.
3840:
3841: The option @samp{-ds} causes a debugging dump of the RTL code after
3842: this pass. This dump file's name is made by appending @samp{.cse} to
3843: the input file name.
3844:
3845: @item
1.1.1.8 ! root 3846: Loop optimization. This pass moves constant expressions out of loops,
! 3847: and optionally does strength-reduction as well. Its source file is
! 3848: @file{loop.c}.
1.1 root 3849:
3850: The option @samp{-dL} causes a debugging dump of the RTL code after
3851: this pass. This dump file's name is made by appending @samp{.loop} to
3852: the input file name.
3853:
3854: @item
3855: Stupid register allocation is performed at this point in a
3856: nonoptimizing compilation. It does a little data flow analysis as
3857: well. When stupid register allocation is in use, the next pass
3858: executed is the reloading pass; the others in between are skipped.
3859: The source file is @file{stupid.c}.
3860:
3861: @item
3862: Data flow analysis (@file{flow.c}). This pass divides the program
3863: into basic blocks (and in the process deletes unreachable loops); then
3864: it computes which pseudo-registers are live at each point in the
3865: program, and makes the first instruction that uses a value point at
3866: the instruction that computed the value.
3867:
3868: This pass also deletes computations whose results are never used, and
3869: combines memory references with add or subtract instructions to make
3870: autoincrement or autodecrement addressing.
3871:
3872: The option @samp{-df} causes a debugging dump of the RTL code after
3873: this pass. This dump file's name is made by appending @samp{.flow} to
3874: the input file name. If stupid register allocation is in use, this
3875: dump file reflects the full results of such allocation.
3876:
3877: @item
3878: Instruction combination (@file{combine.c}). This pass attempts to
3879: combine groups of two or three instructions that are related by data
3880: flow into single instructions. It combines the RTL expressions for
3881: the instructions by substitution, simplifies the result using algebra,
3882: and then attempts to match the result against the machine description.
3883:
3884: The option @samp{-dc} causes a debugging dump of the RTL code after
3885: this pass. This dump file's name is made by appending @samp{.combine}
3886: to the input file name.
3887:
3888: @item
3889: Register class preferencing. The RTL code is scanned to find out
3890: which register class is best for each pseudo register. The source
3891: file is @file{regclass.c}.
3892:
3893: @item
3894: Local register allocation (@file{local-alloc.c}). This pass allocates
3895: hard registers to pseudo registers that are used only within one basic
3896: block. Because the basic block is linear, it can use fast and
3897: powerful techniques to do a very good job.
3898:
3899: The option @samp{-dl} causes a debugging dump of the RTL code after
3900: this pass. This dump file's name is made by appending @samp{.lreg} to
3901: the input file name.
3902:
3903: @item
3904: Global register allocation (@file{global-alloc.c}). This pass
3905: allocates hard registers for the remaining pseudo registers (those
3906: whose life spans are not contained in one basic block).
3907:
3908: @item
3909: Reloading. This pass renumbers pseudo registers with the hardware
3910: registers numbers they were allocated. Pseudo registers that did not
3911: get hard registers are replaced with stack slots. Then it finds
3912: instructions that are invalid because a value has failed to end up in
3913: a register, or has ended up in a register of the wrong kind. It fixes
3914: up these instructions by reloading the problematical values
3915: temporarily into registers. Additional instructions are generated to
3916: do the copying.
3917:
3918: Source files are @file{reload.c} and @file{reload1.c}, plus the header
3919: @file{reload.h} used for communication between them.
3920:
3921: The option @samp{-dg} causes a debugging dump of the RTL code after
3922: this pass. This dump file's name is made by appending @samp{.greg} to
3923: the input file name.
3924:
3925: @item
3926: Jump optimization is repeated, this time including cross-jumping
1.1.1.5 root 3927: and deletion of no-op move instructions.
1.1 root 3928:
3929: The option @samp{-dJ} causes a debugging dump of the RTL code after
3930: this pass. This dump file's name is made by appending @samp{.jump2}
3931: to the input file name.
3932:
3933: @item
1.1.1.8 ! root 3934: Delayed branch scheduling may be done at this point. The source file
! 3935: name is @file{dbranch.c}.
! 3936:
! 3937: The option @samp{-dd} causes a debugging dump of the RTL code after
! 3938: this pass. This dump file's name is made by appending @samp{.dbr}
! 3939: to the input file name.
! 3940:
! 3941: @item
1.1 root 3942: Final. This pass outputs the assembler code for the function. It is
3943: also responsible for identifying spurious test and compare
1.1.1.5 root 3944: instructions. Machine-specific peephole optimizations are performed
3945: at the same time. The function entry and exit sequences are generated
1.1 root 3946: directly as assembler code in this pass; they never exist as RTL.
3947:
3948: The source files are @file{final.c} plus @file{insn-output.c}; the
3949: latter is generated automatically from the machine description by the
3950: tool @file{genoutput}. The header file @file{conditions.h} is used
3951: for communication between these files.
3952:
3953: @item
3954: Debugging information output. This is run after final because it must
3955: output the stack slot offsets for pseudo registers that did not get
3956: hard registers. Source files are @file{dbxout.c} for DBX symbol table
3957: format and @file{symout.c} for GDB's own symbol table format.
3958: @end itemize
3959:
3960: Some additional files are used by all or many passes:
3961:
3962: @itemize @bullet
3963: @item
3964: Every pass uses @file{machmode.def}, which defines the machine modes.
3965:
3966: @item
3967: All the passes that work with RTL use the header files @file{rtl.h}
3968: and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
3969: @code{gen*} also use these files to read and work with the machine
3970: description RTL.
3971:
3972: @item
3973: Several passes refer to the header file @file{insn-config.h} which
3974: contains a few parameters (C macro definitions) generated
3975: automatically from the machine description RTL by the tool
3976: @code{genconfig}.
3977:
3978: @item
3979: Several passes use the instruction recognizer, which consists of
3980: @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3981: and @file{insn-extract.c} that are generated automatically from the
3982: machine description by the tools @file{genrecog} and
3983: @file{genextract}.@refill
3984:
3985: @item
3986: Several passes use the header files @file{regs.h} which defines the
3987: information recorded about pseudo register usage, and @file{basic-block.h}
3988: which defines the information recorded about basic blocks.
3989:
3990: @item
3991: @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3992: with a bit for each hard register, and some macros to manipulate it.
3993: This type is just @code{int} if the machine has few enough hard registers;
3994: otherwise it is an array of @code{int} and some of the macros expand
3995: into loops.
3996: @end itemize
3997:
3998: @node RTL, Machine Desc, Passes, Top
3999: @chapter RTL Representation
4000:
4001: Most of the work of the compiler is done on an intermediate representation
4002: called register transfer language. In this language, the instructions to be
4003: output are described, pretty much one by one, in an algebraic form that
4004: describes what the instruction does.
4005:
4006: RTL is inspired by Lisp lists. It has both an internal form, made up of
4007: structures that point at other structures, and a textual form that is used
4008: in the machine description and in printed debugging dumps. The textual
4009: form uses nested parentheses to indicate the pointers in the internal form.
4010:
4011: @menu
4012: * RTL Objects:: Expressions vs vectors vs strings vs integers.
4013: * Accessors:: Macros to access expression operands or vector elts.
4014: * Flags:: Other flags in an RTL expression.
4015: * Machine Modes:: Describing the size and format of a datum.
4016: * Constants:: Expressions with constant values.
4017: * Regs and Memory:: Expressions representing register contents or memory.
4018: * Arithmetic:: Expressions representing arithmetic on other expressions.
4019: * Comparisons:: Expressions representing comparison of expressions.
4020: * Bit Fields:: Expressions representing bit-fields in memory or reg.
4021: * Conversions:: Extending, truncating, floating or fixing.
4022: * RTL Declarations:: Declaring volatility, constancy, etc.
4023: * Side Effects:: Expressions for storing in registers, etc.
4024: * Incdec:: Embedded side-effects for autoincrement addressing.
4025: * Assembler:: Representing @code{asm} with operands.
4026: * Insns:: Expression types for entire insns.
4027: * Calls:: RTL representation of function call insns.
4028: * Sharing:: Some expressions are unique; others *must* be copied.
4029: @end menu
4030:
4031: @node RTL Objects, Accessors, RTL, RTL
4032: @section RTL Object Types
4033:
4034: RTL uses four kinds of objects: expressions, integers, strings and vectors.
4035: Expressions are the most important ones. An RTL expression (``RTX'', for
4036: short) is a C structure, but it is usually referred to with a pointer; a
4037: type that is given the typedef name @code{rtx}.
4038:
4039: An integer is simply an @code{int}, and a string is a @code{char *}.
1.1.1.8 ! root 4040: Within RTL code, strings appear only inside @code{symbol_ref} expressions,
1.1 root 4041: but they appear in other contexts in the RTL expressions that make up
4042: machine descriptions. Their written form uses decimal digits.
4043:
4044: A string is a sequence of characters. In core it is represented as a
4045: @code{char *} in usual C fashion, and it is written in C syntax as well.
4046: However, strings in RTL may never be null. If you write an empty string in
4047: a machine description, it is represented in core as a null pointer rather
4048: than as a pointer to a null character. In certain contexts, these null
4049: pointers instead of strings are valid.
4050:
4051: A vector contains an arbitrary, specified number of pointers to
4052: expressions. The number of elements in the vector is explicitly present in
4053: the vector. The written form of a vector consists of square brackets
4054: (@samp{[@dots{}]}) surrounding the elements, in sequence and with
4055: whitespace separating them. Vectors of length zero are not created; null
4056: pointers are used instead.
4057:
4058: Expressions are classified by @dfn{expression codes} (also called RTX
4059: codes). The expression code is a name defined in @file{rtl.def}, which is
4060: also (in upper case) a C enumeration constant. The possible expression
4061: codes and their meanings are machine-independent. The code of an RTX can
4062: be extracted with the macro @code{GET_CODE (@var{x})} and altered with
4063: @code{PUT_CODE (@var{x}, @var{newcode})}.
4064:
4065: The expression code determines how many operands the expression contains,
4066: and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
4067: by looking at an operand what kind of object it is. Instead, you must know
4068: from its context---from the expression code of the containing expression.
1.1.1.8 ! root 4069: For example, in an expression of code @code{subreg}, the first operand is
1.1 root 4070: to be regarded as an expression and the second operand as an integer. In
1.1.1.8 ! root 4071: an expression of code @code{plus}, there are two operands, both of which
! 4072: are to be regarded as expressions. In a @code{symbol_ref} expression,
1.1 root 4073: there is one operand, which is to be regarded as a string.
4074:
4075: Expressions are written as parentheses containing the name of the
4076: expression type, its flags and machine mode if any, and then the operands
4077: of the expression (separated by spaces).
4078:
4079: Expression code names in the @samp{md} file are written in lower case,
4080: but when they appear in C code they are written in upper case. In this
1.1.1.8 ! root 4081: manual, they are shown as follows: @code{const_int}.
1.1 root 4082:
4083: In a few contexts a null pointer is valid where an expression is normally
1.1.1.4 root 4084: wanted. The written form of this is @code{(nil)}.
1.1 root 4085:
4086: @node Accessors, Flags, RTL Objects, RTL
4087: @section Access to Operands
4088:
4089: For each expression type @file{rtl.def} specifies the number of contained
4090: objects and their kinds, with four possibilities: @samp{e} for expression
4091: (actually a pointer to an expression), @samp{i} for integer, @samp{s} for
4092: string, and @samp{E} for vector of expressions. The sequence of letters
4093: for an expression code is called its @dfn{format}. Thus, the format of
1.1.1.8 ! root 4094: @code{subreg} is @samp{ei}.@refill
1.1 root 4095:
4096: Two other format characters are used occasionally: @samp{u} and @samp{0}.
4097: @samp{u} is equivalent to @samp{e} except that it is printed differently in
4098: debugging dumps, and @samp{0} means a slot whose contents do not fit any
4099: normal category. @samp{0} slots are not printed at all in dumps, and are
4100: often used in special ways by small parts of the compiler.@refill
4101:
4102: There are macros to get the number of operands and the format of an
4103: expression code:
4104:
4105: @table @code
4106: @item GET_RTX_LENGTH (@var{code})
4107: Number of operands of an RTX of code @var{code}.
4108:
4109: @item GET_RTX_FORMAT (@var{code})
4110: The format of an RTX of code @var{code}, as a C string.
4111: @end table
4112:
4113: Operands of expressions are accessed using the macros @code{XEXP},
4114: @code{XINT} and @code{XSTR}. Each of these macros takes two arguments: an
4115: expression-pointer (RTX) and an operand number (counting from zero).
4116: Thus,@refill
4117:
4118: @example
4119: XEXP (@var{x}, 2)
4120: @end example
4121:
4122: @noindent
4123: accesses operand 2 of expression @var{x}, as an expression.
4124:
4125: @example
4126: XINT (@var{x}, 2)
4127: @end example
4128:
4129: @noindent
4130: accesses the same operand as an integer. @code{XSTR}, used in the same
4131: fashion, would access it as a string.
4132:
4133: Any operand can be accessed as an integer, as an expression or as a string.
4134: You must choose the correct method of access for the kind of value actually
4135: stored in the operand. You would do this based on the expression code of
4136: the containing expression. That is also how you would know how many
4137: operands there are.
4138:
1.1.1.8 ! root 4139: For example, if @var{x} is a @code{subreg} expression, you know that it has
1.1 root 4140: two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
4141: and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
4142: would get the address of the expression operand but cast as an integer;
4143: that might occasionally be useful, but it would be cleaner to write
4144: @code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
4145: compile without error, and would return the second, integer operand cast as
4146: an expression pointer, which would probably result in a crash when
4147: accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
4148: but this will access memory past the end of the expression with
4149: unpredictable results.@refill
4150:
4151: Access to operands which are vectors is more complicated. You can use the
4152: macro @code{XVEC} to get the vector-pointer itself, or the macros
4153: @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
4154: vector.
4155:
4156: @table @code
4157: @item XVEC (@var{exp}, @var{idx})
4158: Access the vector-pointer which is operand number @var{idx} in @var{exp}.
4159:
4160: @item XVECLEN (@var{exp}, @var{idx})
4161: Access the length (number of elements) in the vector which is
4162: in operand number @var{idx} in @var{exp}. This value is an @code{int}.
4163:
4164: @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
4165: Access element number @var{eltnum} in the vector which is
4166: in operand number @var{idx} in @var{exp}. This value is an RTX.
4167:
4168: It is up to you to make sure that @var{eltnum} is not negative
4169: and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
4170: @end table
4171:
4172: All the macros defined in this section expand into lvalues and therefore
4173: can be used to assign the operands, lengths and vector elements as well as
4174: to access them.
4175:
4176: @node Flags, Machine Modes, Accessors, RTL
4177: @section Flags in an RTL Expression
4178:
4179: RTL expressions contain several flags (one-bit bit-fields) that are used
4180: in certain types of expression. Most often they are accessed with the
4181: following macros:
4182:
4183: @table @code
4184: @item MEM_VOLATILE_P (@var{x})
1.1.1.8 ! root 4185: In @code{mem} expressions, nonzero for volatile memory references.
1.1 root 4186: Stored in the @code{volatil} field and printed as @samp{/v}.
4187:
4188: @item MEM_IN_STRUCT_P (@var{x})
1.1.1.8 ! root 4189: In @code{mem} expressions, nonzero for reference to an entire
1.1 root 4190: structure, union or array, or to a component of one. Zero for
4191: references to a scalar variable or through a pointer to a scalar.
4192: Stored in the @code{in_struct} field and printed as @samp{/s}.
4193:
4194: @item REG_USER_VAR_P (@var{x})
1.1.1.8 ! root 4195: In a @code{reg}, nonzero if it corresponds to a variable present in
1.1 root 4196: the user's source code. Zero for temporaries generated internally by
4197: the compiler. Stored in the @code{volatil} field and printed as
4198: @samp{/v}.
4199:
4200: @item REG_FUNCTION_VALUE_P (@var{x})
1.1.1.8 ! root 4201: Nonzero in a @code{reg} if it is the place in which this function's
1.1 root 4202: value is going to be returned. (This happens only in a hard
4203: register.) Stored in the @code{integrated} field and printed as
4204: @samp{/i}.
4205:
4206: The same hard register may be used also for collecting the values of
4207: functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
4208: in this kind of use.
4209:
4210: @item RTX_UNCHANGING_P (@var{x})
1.1.1.8 ! root 4211: Nonzero in a @code{reg} or @code{mem} if the value is not changed
1.1 root 4212: explicitly by the current function. (If it is a memory reference then
4213: it may be changed by other functions or by aliasing.) Stored in the
4214: @code{unchanging} field and printed as @samp{/u}.
4215:
4216: @item RTX_INTEGRATED_P (@var{insn})
4217: Nonzero in an insn if it resulted from an in-line function call.
4218: Stored in the @code{integrated} field and printed as @samp{/i}. This
4219: may be deleted; nothing currently depends on it.
4220:
4221: @item INSN_DELETED_P (@var{insn})
4222: In an insn, nonzero if the insn has been deleted. Stored in the
4223: @code{volatil} field and printed as @samp{/v}.
4224:
4225: @item CONSTANT_POOL_ADDRESS_P (@var{x})
1.1.1.8 ! root 4226: Nonzero in a @code{symbol_ref} if it refers to part of the current
1.1 root 4227: function's ``constants pool''. These are addresses close to the
4228: beginning of the function, and GNU CC assumes they can be addressed
4229: directly (perhaps with the help of base registers). Stored in the
4230: @code{unchanging} field and printed as @samp{/u}.
4231: @end table
4232:
4233: These are the fields which the above macros refer to:
4234:
4235: @table @code
4236: @item used
4237: This flag is used only momentarily, at the end of RTL generation for a
4238: function, to count the number of times an expression appears in insns.
4239: Expressions that appear more than once are copied, according to the
4240: rules for shared structure (@pxref{Sharing}).
4241:
4242: @item volatil
1.1.1.8 ! root 4243: This flag is used in @code{mem} and @code{reg} expressions and in insns.
1.1 root 4244: In RTL dump files, it is printed as @samp{/v}.
4245:
1.1.1.8 ! root 4246: In a @code{mem} expression, it is 1 if the memory reference is volatile.
1.1 root 4247: Volatile memory references may not be deleted, reordered or combined.
4248:
1.1.1.8 ! root 4249: In a @code{reg} expression, it is 1 if the value is a user-level variable.
1.1 root 4250: 0 indicates an internal compiler temporary.
4251:
4252: In an insn, 1 means the insn has been deleted.
4253:
4254: @item in_struct
1.1.1.8 ! root 4255: This flag is used in @code{mem} expressions. It is 1 if the memory
1.1 root 4256: datum referred to is all or part of a structure or array; 0 if it is (or
4257: might be) a scalar variable. A reference through a C pointer has 0
4258: because the pointer might point to a scalar variable.
4259:
4260: This information allows the compiler to determine something about possible
4261: cases of aliasing.
4262:
4263: In an RTL dump, this flag is represented as @samp{/s}.
4264:
4265: @item unchanging
1.1.1.8 ! root 4266: This flag is used in @code{reg} and @code{mem} expressions. 1 means
1.1 root 4267: that the value of the expression never changes (at least within the
4268: current function).
4269:
4270: In an RTL dump, this flag is represented as @samp{/u}.
4271:
4272: @item integrated
4273: In some kinds of expressions, including insns, this flag means the
4274: rtl was produced by procedure integration.
4275:
1.1.1.8 ! root 4276: In a @code{reg} expression, this flag indicates the register
1.1 root 4277: containing the value to be returned by the current function. On
4278: machines that pass parameters in registers, the same register number
4279: may be used for parameters as well, but this flag is not set on such
4280: uses.
4281: @end table
4282:
4283: @node Machine Modes, Constants, Flags, RTL
4284: @section Machine Modes
4285:
4286: A machine mode describes a size of data object and the representation used
4287: for it. In the C code, machine modes are represented by an enumeration
4288: type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
4289: expression has room for a machine mode and so do certain kinds of tree
4290: expressions (declarations and types, to be precise).
4291:
4292: In debugging dumps and machine descriptions, the machine mode of an RTL
4293: expression is written after the expression code with a colon to separate
4294: them. The letters @samp{mode} which appear at the end of each machine mode
1.1.1.8 ! root 4295: name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
1.1 root 4296: expression with machine mode @code{SImode}. If the mode is
4297: @code{VOIDmode}, it is not written at all.
4298:
4299: Here is a table of machine modes.
4300:
4301: @table @code
4302: @item QImode
4303: ``Quarter-Integer'' mode represents a single byte treated as an integer.
4304:
4305: @item HImode
4306: ``Half-Integer'' mode represents a two-byte integer.
4307:
1.1.1.7 root 4308: @item PSImode
4309: ``Partial Single Integer'' mode represents an integer which occupies
4310: four bytes but which doesn't really use all four. On some machines,
4311: this is the right mode to use for pointers.
4312:
1.1 root 4313: @item SImode
4314: ``Single Integer'' mode represents a four-byte integer.
4315:
1.1.1.7 root 4316: @item PDImode
4317: ``Partial Double Integer'' mode represents an integer which occupies
4318: eight bytes but which doesn't really use all eight. On some machines,
4319: this is the right mode to use for certain pointers.
4320:
1.1 root 4321: @item DImode
4322: ``Double Integer'' mode represents an eight-byte integer.
4323:
4324: @item TImode
4325: ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
4326:
4327: @item SFmode
4328: ``Single Floating'' mode represents a single-precision (four byte) floating
4329: point number.
4330:
4331: @item DFmode
4332: ``Double Floating'' mode represents a double-precision (eight byte) floating
4333: point number.
4334:
1.1.1.7 root 4335: @item XFmode
4336: ``Extended Floating'' mode represents a triple-precision (twelve byte)
4337: floating point number. This mode is used for IEEE extended floating
4338: point.
4339:
1.1 root 4340: @item TFmode
4341: ``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
4342: floating point number.
4343:
4344: @item BLKmode
4345: ``Block'' mode represents values that are aggregates to which none of
4346: the other modes apply. In RTL, only memory references can have this mode,
4347: and only if they appear in string-move or vector instructions. On machines
4348: which have no such instructions, @code{BLKmode} will not appear in RTL.
4349:
4350: @item VOIDmode
4351: Void mode means the absence of a mode or an unspecified mode.
1.1.1.8 ! root 4352: For example, RTL expressions of code @code{const_int} have mode
1.1 root 4353: @code{VOIDmode} because they can be taken to have whatever mode the context
4354: requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
4355: the absence of any mode.
4356:
4357: @item EPmode
4358: ``Entry Pointer'' mode is intended to be used for function variables in
4359: Pascal and other block structured languages. Such values contain
4360: both a function address and a static chain pointer for access to
4361: automatic variables of outer levels. This mode is only partially
4362: implemented since C does not use it.
4363:
4364: @item CSImode@r{, @dots{}}
4365: ``Complex Single Integer'' mode stands for a complex number represented
4366: as a pair of @code{SImode} integers. Any of the integer and floating modes
4367: may have @samp{C} prefixed to its name to obtain a complex number mode.
4368: For example, there are @code{CQImode}, @code{CSFmode}, and @code{CDFmode}.
4369: Since C does not support complex numbers, these machine modes are only
4370: partially implemented.
4371:
4372: @item BImode
4373: This is the machine mode of a bit-field in a structure. It is used
4374: only in the syntax tree, never in RTL, and in the syntax tree it appears
4375: only in declaration nodes. In C, it appears only in @code{FIELD_DECL}
4376: nodes for structure fields defined with a bit size.
4377: @end table
4378:
4379: The machine description defines @code{Pmode} as a C macro which expands
4380: into the machine mode used for addresses. Normally this is @code{SImode}.
4381:
4382: The only modes which a machine description @i{must} support are
4383: @code{QImode}, @code{SImode}, @code{SFmode} and @code{DFmode}. The
4384: compiler will attempt to use @code{DImode} for two-word structures and
1.1.1.7 root 4385: unions, but this can be prevented by overriding the definition of
4386: @code{MAX_FIXED_MODE_SIZE}. Likewise, you can arrange for the C type
4387: @code{short int} to avoid using @code{HImode}. In the long term it
4388: might be desirable to make the set of available machine modes
4389: machine-dependent and eliminate all assumptions about specific machine
4390: modes or their uses from the machine-independent code of the compiler.
1.1 root 4391:
1.1.1.4 root 4392: To help begin this process, the machine modes are divided into mode
4393: classes. These are represented by the enumeration type @code{enum
4394: mode_class} defined in @file{rtl.h}. The possible mode classes are:
4395:
4396: @table @code
4397: @item MODE_INT
4398: Integer modes. By default these are @code{QImode}, @code{HImode},
4399: @code{SImode}, @code{DImode}, @code{TImode}, and also @code{BImode}.
4400:
4401: @item MODE_FLOAT
4402: Floating-point modes. By default these are @code{QFmode},
4403: @code{HFmode}, @code{SFmode}, @code{DFmode} and @code{TFmode}, but the
4404: MC68881 also defines @code{XFmode} to be an 80-bit extended-precision
4405: floating-point mode.
4406:
4407: @item MODE_COMPLEX_INT
4408: Complex integer modes. By default these are @code{CQImode},
4409: @code{CHImode}, @code{CSImode}, @code{CDImode} and @code{CTImode}.
4410:
4411: @item MODE_COMPLEX_FLOAT
4412: Complex floating-point modes. By default these are @code{CQFmode},
4413: @code{CHFmode}, @code{CSFmode}, @code{CDFmode} and @code{CTFmode},
4414:
4415: @item MODE_FUNCTION
4416: Algol or Pascal function variables including a static chain.
4417: (These are not currently implemented).
4418:
4419: @item MODE_RANDOM
4420: This is a catchall mode class for modes which don't fit into the above
4421: classes. Currently @code{VOIDmode}, @code{BLKmode} and @code{EPmode}
4422: are in @code{MODE_RANDOM}.
4423: @end table
4424:
1.1 root 4425: Here are some C macros that relate to machine modes:
4426:
4427: @table @code
4428: @item GET_MODE (@var{x})
4429: Returns the machine mode of the RTX @var{x}.
4430:
4431: @item PUT_MODE (@var{x}, @var{newmode})
4432: Alters the machine mode of the RTX @var{x} to be @var{newmode}.
4433:
1.1.1.4 root 4434: @item NUM_MACHINE_MODES
4435: Stands for the number of machine modes available on the target
4436: machine. This is one greater than the largest numeric value of any
4437: machine mode.
4438:
4439: @item GET_MODE_NAME (@var{m})
4440: Returns the name of mode @var{m} as a string.
4441:
4442: @item GET_MODE_CLASS (@var{m})
4443: Returns the mode class of mode @var{m}.
4444:
1.1 root 4445: @item GET_MODE_SIZE (@var{m})
4446: Returns the size in bytes of a datum of mode @var{m}.
4447:
4448: @item GET_MODE_BITSIZE (@var{m})
4449: Returns the size in bits of a datum of mode @var{m}.
4450:
4451: @item GET_MODE_UNIT_SIZE (@var{m})
4452: Returns the size in bits of the subunits of a datum of mode @var{m}.
4453: This is the same as @code{GET_MODE_SIZE} except in the case of
4454: complex modes and @code{EPmode}. For them, the unit size is the
4455: size of the real or imaginary part, or the size of the function
4456: pointer or the context pointer.
4457: @end table
4458:
4459: @node Constants, Regs and Memory, Machine Modes, RTL
4460: @section Constant Expression Types
4461:
4462: The simplest RTL expressions are those that represent constant values.
4463:
4464: @table @code
4465: @item (const_int @var{i})
4466: This type of expression represents the integer value @var{i}. @var{i}
4467: is customarily accessed with the macro @code{INTVAL} as in
4468: @code{INTVAL (@var{exp})}, which is equivalent to @code{XINT (@var{exp}, 0)}.
4469:
4470: There is only one expression object for the integer value zero;
4471: it is the value of the variable @code{const0_rtx}. Likewise, the
4472: only expression for integer value one is found in @code{const1_rtx}.
1.1.1.8 ! root 4473: Any attempt to create an expression of code @code{const_int} and
1.1 root 4474: value zero or one will return @code{const0_rtx} or @code{const1_rtx}
4475: as appropriate.
4476:
4477: @item (const_double:@var{m} @var{i0} @var{i1})
1.1.1.6 root 4478: Represents a 64-bit constant of mode @var{m}. All floating point
1.1 root 4479: constants are represented in this way, and so are 64-bit @code{DImode}
4480: integer constants.
4481:
4482: The two integers @var{i0} and @var{i1} together contain the bits of
4483: the value. If the constant is floating point (either single or double
4484: precision), then they represent a @code{double}. To convert them to a
4485: @code{double}, do
4486:
4487: @example
4488: union @{ double d; int i[2];@} u;
1.1.1.8 ! root 4489: u.i[0] = CONST_DOUBLE_LOW(x);
! 4490: u.i[1] = CONST_DOUBLE_HIGH(x);
1.1 root 4491: @end example
4492:
4493: @noindent
4494: and then refer to @code{u.d}.
4495:
4496: The global variables @code{dconst0_rtx} and @code{fconst0_rtx} hold
1.1.1.8 ! root 4497: @code{const_double} expressions with value 0, in modes @code{DFmode}
1.1.1.7 root 4498: and @code{SFmode}, respectively. The macro @code{CONST0_RTX
1.1.1.8 ! root 4499: (@var{mode})} refers to a @code{const_double} expression with value 0
1.1.1.7 root 4500: in mode @var{mode}. The mode @var{mode} must be of mode class
4501: @code{MODE_FLOAT}.
1.1 root 4502:
4503: @item (symbol_ref @var{symbol})
4504: Represents the value of an assembler label for data. @var{symbol} is
4505: a string that describes the name of the assembler label. If it starts
4506: with a @samp{*}, the label is the rest of @var{symbol} not including
4507: the @samp{*}. Otherwise, the label is @var{symbol}, prefixed with
4508: @samp{_}.
4509:
4510: @item (label_ref @var{label})
4511: Represents the value of an assembler label for code. It contains one
1.1.1.8 ! root 4512: operand, an expression, which must be a @code{code_label} that appears
1.1 root 4513: in the instruction sequence to identify the place where the label
4514: should go.
4515:
4516: The reason for using a distinct expression type for code label
4517: references is so that jump optimization can distinguish them.
4518:
4519: @item (const @var{exp})
4520: Represents a constant that is the result of an assembly-time
4521: arithmetic computation. The operand, @var{exp}, is an expression that
1.1.1.8 ! root 4522: contains only constants (@code{const_int}, @code{symbol_ref} and
! 4523: @code{label_ref} expressions) combined with @code{plus} and
! 4524: @code{minus}. However, not all combinations are valid, since the
1.1 root 4525: assembler cannot do arbitrary arithmetic on relocatable symbols.
4526: @end table
4527:
4528: @node Regs and Memory, Arithmetic, Constants, RTL
4529: @section Registers and Memory
4530:
4531: Here are the RTL expression types for describing access to machine
4532: registers and to main memory.
4533:
4534: @table @code
4535: @item (reg:@var{m} @var{n})
4536: For small values of the integer @var{n} (less than
4537: @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
4538: register number @var{n}: a @dfn{hard register}. For larger values of
4539: @var{n}, it stands for a temporary value or @dfn{pseudo register}.
4540: The compiler's strategy is to generate code assuming an unlimited
4541: number of such pseudo registers, and later convert them into hard
4542: registers or into memory references.
4543:
4544: The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
4545: description, since the number of hard registers on the machine is an
4546: invariant characteristic of the machine. Note, however, that not
4547: all of the machine registers must be general registers. All the
4548: machine registers that can be used for storage of data are given
4549: hard register numbers, even those that can be used only in certain
4550: instructions or can hold only certain types of data.
4551:
4552: Each pseudo register number used in a function's RTL code is
1.1.1.8 ! root 4553: represented by a unique @code{reg} expression.
1.1 root 4554:
4555: @var{m} is the machine mode of the reference. It is necessary because
4556: machines can generally refer to each register in more than one mode.
4557: For example, a register may contain a full word but there may be
4558: instructions to refer to it as a half word or as a single byte, as
4559: well as instructions to refer to it as a floating point number of
4560: various precisions.
4561:
4562: Even for a register that the machine can access in only one mode,
4563: the mode must always be specified.
4564:
4565: A hard register may be accessed in various modes throughout one
4566: function, but each pseudo register is given a natural mode
4567: and is accessed only in that mode. When it is necessary to describe
1.1.1.8 ! root 4568: an access to a pseudo register using a nonnatural mode, a @code{subreg}
1.1 root 4569: expression is used.
4570:
1.1.1.8 ! root 4571: A @code{reg} expression with a machine mode that specifies more than
1.1 root 4572: one word of data may actually stand for several consecutive registers.
4573: If in addition the register number specifies a hardware register, then
4574: it actually represents several consecutive hardware registers starting
4575: with the specified one.
4576:
1.1.1.8 ! root 4577: Such multi-word hardware register @code{reg} expressions must not be live
1.1 root 4578: across the boundary of a basic block. The lifetime analysis pass does not
4579: know how to record properly that several consecutive registers are
4580: actually live there, and therefore register allocation would be confused.
4581: The CSE pass must go out of its way to make sure the situation does
4582: not arise.
4583:
4584: @item (subreg:@var{m} @var{reg} @var{wordnum})
1.1.1.8 ! root 4585: @code{subreg} expressions are used to refer to a register in a machine
1.1 root 4586: mode other than its natural one, or to refer to one register of
1.1.1.8 ! root 4587: a multi-word @code{reg} that actually refers to several registers.
1.1 root 4588:
4589: Each pseudo-register has a natural mode. If it is necessary to
4590: operate on it in a different mode---for example, to perform a fullword
1.1.1.8 ! root 4591: move instruction on a pseudo-register that contains a single
! 4592: byte---the pseudo-register must be enclosed in a @code{subreg}. In
! 4593: such a case, @var{wordnum} is zero.
1.1 root 4594:
1.1.1.8 ! root 4595: The other use of @code{subreg} is to extract the individual registers
1.1 root 4596: of a multi-register value. Machine modes such as @code{DImode} and
4597: @code{EPmode} indicate values longer than a word, values which usually
4598: require two consecutive registers. To access one of the registers,
1.1.1.8 ! root 4599: use a @code{subreg} with mode @code{SImode} and a @var{wordnum} that
1.1 root 4600: says which register.
4601:
4602: The compilation parameter @code{WORDS_BIG_ENDIAN}, if defined, says
4603: that word number zero is the most significant part; otherwise, it is
4604: the least significant part.
4605:
4606: Between the combiner pass and the reload pass, it is possible to have
1.1.1.8 ! root 4607: a @code{subreg} which contains a @code{mem} instead of a @code{reg} as
1.1 root 4608: its first operand. The reload pass eliminates these cases by
1.1.1.8 ! root 4609: reloading the @code{mem} into a suitable register.
1.1 root 4610:
4611: Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
1.1.1.8 ! root 4612: using a @code{subreg}. On some machines the most significant part of a
1.1 root 4613: @code{DFmode} value does not have the same format as a single-precision
4614: floating value.
4615:
4616: @item (cc0)
4617: This refers to the machine's condition code register. It has no
4618: operands and may not have a machine mode. It may be validly used in
4619: only two contexts: as the destination of an assignment (in test and
4620: compare instructions) and in comparison operators comparing against
1.1.1.8 ! root 4621: zero (@code{const_int} with value zero; that is to say,
1.1 root 4622: @code{const0_rtx}).
4623:
1.1.1.8 ! root 4624: There is only one expression object of code @code{cc0}; it is the
1.1 root 4625: value of the variable @code{cc0_rtx}. Any attempt to create an
1.1.1.8 ! root 4626: expression of code @code{cc0} will return @code{cc0_rtx}.
1.1 root 4627:
4628: One special thing about the condition code register is that
4629: instructions can set it implicitly. On many machines, nearly all
4630: instructions set the condition code based on the value that they
4631: compute or store. It is not necessary to record these actions
4632: explicitly in the RTL because the machine description includes a
4633: prescription for recognizing the instructions that do so (by means of
4634: the macro @code{NOTICE_UPDATE_CC}). Only instructions whose sole
4635: purpose is to set the condition code, and instructions that use the
4636: condition code, need mention @code{(cc0)}.
4637:
4638: @item (pc)
4639: This represents the machine's program counter. It has no operands and
4640: may not have a machine mode. @code{(pc)} may be validly used only in
4641: certain specific contexts in jump instructions.
4642:
1.1.1.8 ! root 4643: There is only one expression object of code @code{pc}; it is the value
1.1 root 4644: of the variable @code{pc_rtx}. Any attempt to create an expression of
1.1.1.8 ! root 4645: code @code{pc} will return @code{pc_rtx}.
1.1 root 4646:
4647: All instructions that do not jump alter the program counter implicitly
4648: by incrementing it, but there is no need to mention this in the RTL.
4649:
4650: @item (mem:@var{m} @var{addr})
4651: This RTX represents a reference to main memory at an address
4652: represented by the expression @var{addr}. @var{m} specifies how large
4653: a unit of memory is accessed.
4654: @end table
4655:
4656: @node Arithmetic, Comparisons, Regs and Memory, RTL
4657: @section RTL Expressions for Arithmetic
4658:
4659: @table @code
4660: @item (plus:@var{m} @var{x} @var{y})
4661: Represents the sum of the values represented by @var{x} and @var{y}
4662: carried out in machine mode @var{m}. This is valid only if
4663: @var{x} and @var{y} both are valid for mode @var{m}.
4664:
4665: @item (minus:@var{m} @var{x} @var{y})
1.1.1.8 ! root 4666: Like @code{plus} but represents subtraction.
1.1 root 4667:
1.1.1.6 root 4668: @item (compare @var{x} @var{y})
1.1 root 4669: Represents the result of subtracting @var{y} from @var{x}
4670: for purposes of comparison. The absence of a machine mode
1.1.1.8 ! root 4671: in the @code{compare} expression indicates that the result is
1.1 root 4672: computed without overflow, as if with infinite precision.
4673:
4674: Of course, machines can't really subtract with infinite precision.
4675: However, they can pretend to do so when only the sign of the
4676: result will be used, which is the case when the result is stored
4677: in @code{(cc0)}. And that is the only way this kind of expression
4678: may validly be used: as a value to be stored in the condition codes.
4679:
4680: @item (neg:@var{m} @var{x})
4681: Represents the negation (subtraction from zero) of the value
4682: represented by @var{x}, carried out in mode @var{m}. @var{x} must be
4683: valid for mode @var{m}.
4684:
4685: @item (mult:@var{m} @var{x} @var{y})
4686: Represents the signed product of the values represented by @var{x} and
4687: @var{y} carried out in machine mode @var{m}. If
4688: @var{x} and @var{y} are both valid for mode @var{m}, this is ordinary
4689: size-preserving multiplication. Alternatively, both @var{x} and @var{y}
4690: may be valid for a different, narrower mode. This represents the
4691: kind of multiplication that generates a product wider than the operands.
4692: Widening multiplication and same-size multiplication are completely
4693: distinct and supported by different machine instructions; machines may
4694: support one but not the other.@refill
4695:
1.1.1.8 ! root 4696: @code{mult} may be used for floating point multiplication as well.
1.1 root 4697: Then @var{m} is a floating point machine mode.
4698:
4699: @item (umult:@var{m} @var{x} @var{y})
1.1.1.8 ! root 4700: Like @code{mult} but represents unsigned multiplication. It may be
! 4701: used in both same-size and widening forms, like @code{mult}.
! 4702: @code{umult} is used only for fixed-point multiplication.
1.1 root 4703:
4704: @item (div:@var{m} @var{x} @var{y})
4705: Represents the quotient in signed division of @var{x} by @var{y},
4706: carried out in machine mode @var{m}. If @var{m} is a floating-point
4707: mode, it represents the exact quotient; otherwise, the integerized
4708: quotient. If @var{x} and @var{y} are both valid for mode @var{m},
4709: this is ordinary size-preserving division. Some machines have
4710: division instructions in which the operands and quotient widths are
1.1.1.8 ! root 4711: not all the same; such instructions are represented by @code{div}
1.1 root 4712: expressions in which the machine modes are not all the same.
4713:
4714: @item (udiv:@var{m} @var{x} @var{y})
1.1.1.8 ! root 4715: Like @code{div} but represents unsigned division.
1.1 root 4716:
4717: @item (mod:@var{m} @var{x} @var{y})
4718: @itemx (umod:@var{m} @var{x} @var{y})
1.1.1.8 ! root 4719: Like @code{div} and @code{udiv} but represent the remainder instead of
1.1 root 4720: the quotient.
4721:
4722: @item (not:@var{m} @var{x})
4723: Represents the bitwise complement of the value represented by @var{x},
4724: carried out in mode @var{m}, which must be a fixed-point machine mode.
4725: @var{x} must be valid for mode @var{m}, which must be a fixed-point mode.
4726:
4727: @item (and:@var{m} @var{x} @var{y})
4728: Represents the bitwise logical-and of the values represented by
4729: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
4730: valid only if @var{x} and @var{y} both are valid for mode @var{m},
4731: which must be a fixed-point mode.
4732:
4733: @item (ior:@var{m} @var{x} @var{y})
4734: Represents the bitwise inclusive-or of the values represented by
4735: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
4736: valid only if @var{x} and @var{y} both are valid for mode @var{m},
4737: which must be a fixed-point mode.
4738:
4739: @item (xor:@var{m} @var{x} @var{y})
4740: Represents the bitwise exclusive-or of the values represented by
4741: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
4742: valid only if @var{x} and @var{y} both are valid for mode @var{m},
4743: which must be a fixed-point mode.
4744:
4745: @item (lshift:@var{m} @var{x} @var{c})
4746: Represents the result of logically shifting @var{x} left by @var{c}
4747: places. @var{x} must be valid for the mode @var{m}, a fixed-point
4748: machine mode. @var{c} must be valid for a fixed-point mode;
4749: which mode is determined by the mode called for in the machine
4750: description entry for the left-shift instruction. For example,
4751: on the Vax, the mode of @var{c} is @code{QImode} regardless of @var{m}.
4752:
4753: On some machines, negative values of @var{c} may be meaningful; this
4754: is why logical left shift and arithmetic left shift are distinguished.
4755: For example, Vaxes have no right-shift instructions, and right shifts
4756: are represented as left-shift instructions whose counts happen
4757: to be negative constants or else computed (in a previous instruction)
4758: by negation.
4759:
4760: @item (ashift:@var{m} @var{x} @var{c})
1.1.1.8 ! root 4761: Like @code{lshift} but for arithmetic left shift.
1.1 root 4762:
4763: @item (lshiftrt:@var{m} @var{x} @var{c})
4764: @itemx (ashiftrt:@var{m} @var{x} @var{c})
1.1.1.8 ! root 4765: Like @code{lshift} and @code{ashift} but for right shift.
1.1 root 4766:
4767: @item (rotate:@var{m} @var{x} @var{c})
4768: @itemx (rotatert:@var{m} @var{x} @var{c})
4769: Similar but represent left and right rotate.
4770:
4771: @item (abs:@var{m} @var{x})
4772: Represents the absolute value of @var{x}, computed in mode @var{m}.
4773: @var{x} must be valid for @var{m}.
4774:
4775: @item (sqrt:@var{m} @var{x})
4776: Represents the square root of @var{x}, computed in mode @var{m}.
4777: @var{x} must be valid for @var{m}. Most often @var{m} will be
4778: a floating point mode.
4779:
4780: @item (ffs:@var{m} @var{x})
4781: Represents the one plus the index of the least significant 1-bit in
4782: @var{x}, represented as an integer of mode @var{m}. (The value is
4783: zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
4784: depending on the target machine, various mode combinations may be
4785: valid.
4786: @end table
4787:
4788: @node Comparisons, Bit Fields, Arithmetic, RTL
4789: @section Comparison Operations
4790:
4791: Comparison operators test a relation on two operands and are considered to
4792: represent the value 1 if the relation holds, or zero if it does not. The
4793: mode of the comparison is determined by the operands; they must both be
4794: valid for a common machine mode. A comparison with both operands constant
4795: would be invalid as the machine mode could not be deduced from it, but such
4796: a comparison should never exist in RTL due to constant folding.
4797:
4798: Inequality comparisons come in two flavors, signed and unsigned. Thus,
1.1.1.8 ! root 4799: there are distinct expression codes @code{gt} and @code{gtu} for signed and
1.1 root 4800: unsigned greater-than. These can produce different results for the same
4801: pair of integer values: for example, 1 is signed greater-than -1 but not
4802: unsigned greater-than, because -1 when regarded as unsigned is actually
4803: @code{0xffffffff} which is greater than 1.
4804:
4805: The signed comparisons are also used for floating point values. Floating
4806: point comparisons are distinguished by the machine modes of the operands.
4807:
4808: The comparison operators may be used to compare the condition codes
4809: @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such a
4810: construct actually refers to the result of the preceding instruction in
4811: which the condition codes were set. The above example stands for 1 if the
4812: condition codes were set to say ``zero'' or ``equal'', 0 otherwise.
4813: Although the same comparison operators are used for this as may be used in
4814: other contexts on actual data, no confusion can result since the machine
4815: description would never allow both kinds of uses in the same context.
4816:
4817: @table @code
4818: @item (eq @var{x} @var{y})
4819: 1 if the values represented by @var{x} and @var{y} are equal,
4820: otherwise 0.
4821:
4822: @item (ne @var{x} @var{y})
4823: 1 if the values represented by @var{x} and @var{y} are not equal,
4824: otherwise 0.
4825:
4826: @item (gt @var{x} @var{y})
4827: 1 if the @var{x} is greater than @var{y}. If they are fixed-point,
4828: the comparison is done in a signed sense.
4829:
4830: @item (gtu @var{x} @var{y})
1.1.1.8 ! root 4831: Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
1.1 root 4832:
4833: @item (lt @var{x} @var{y})
4834: @item (ltu @var{x} @var{y})
1.1.1.8 ! root 4835: Like @code{gt} and @code{gtu} but test for ``less than''.
1.1 root 4836:
4837: @item (ge @var{x} @var{y})
4838: @item (geu @var{x} @var{y})
1.1.1.8 ! root 4839: Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
1.1 root 4840:
4841: @item (le @var{x} @var{y})
4842: @item (leu @var{x} @var{y})
1.1.1.8 ! root 4843: Like @code{gt} and @code{gtu} but test for ``less than or equal''.
1.1 root 4844:
4845: @item (if_then_else @var{cond} @var{then} @var{else})
4846: This is not a comparison operation but is listed here because it is
4847: always used in conjunction with a comparison operation. To be
4848: precise, @var{cond} is a comparison expression. This expression
4849: represents a choice, according to @var{cond}, between the value
4850: represented by @var{then} and the one represented by @var{else}.
4851:
1.1.1.8 ! root 4852: On most machines, @code{if_then_else} expressions are valid only
1.1 root 4853: to express conditional jumps.
4854: @end table
4855:
4856: @node Bit Fields, Conversions, Comparisons, RTL
4857: @section Bit-fields
4858:
4859: Special expression codes exist to represent bit-field instructions.
4860: These types of expressions are lvalues in RTL; they may appear
4861: on the left side of a assignment, indicating insertion of a value
4862: into the specified bit field.
4863:
4864: @table @code
4865: @item (sign_extract:SI @var{loc} @var{size} @var{pos})
4866: This represents a reference to a sign-extended bit-field contained or
4867: starting in @var{loc} (a memory or register reference). The bit field
4868: is @var{size} bits wide and starts at bit @var{pos}. The compilation
4869: option @code{BITS_BIG_ENDIAN} says which end of the memory unit
4870: @var{pos} counts from.
4871:
4872: Which machine modes are valid for @var{loc} depends on the machine,
4873: but typically @var{loc} should be a single byte when in memory
4874: or a full word in a register.
4875:
4876: @item (zero_extract:SI @var{loc} @var{size} @var{pos})
1.1.1.8 ! root 4877: Like @code{sign_extract} but refers to an unsigned or zero-extended
1.1 root 4878: bit field. The same sequence of bits are extracted, but they
4879: are filled to an entire word with zeros instead of by sign-extension.
4880: @end table
4881:
4882: @node Conversions, RTL Declarations, Bit Fields, RTL
4883: @section Conversions
4884:
4885: All conversions between machine modes must be represented by
4886: explicit conversion operations. For example, an expression
4887: which is the sum of a byte and a full word cannot be written as
1.1.1.8 ! root 4888: @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
1.1 root 4889: operation requires two operands of the same machine mode.
4890: Therefore, the byte-sized operand is enclosed in a conversion
4891: operation, as in
4892:
4893: @example
4894: (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
4895: @end example
4896:
4897: The conversion operation is not a mere placeholder, because there
4898: may be more than one way of converting from a given starting mode
4899: to the desired final mode. The conversion operation code says how
4900: to do it.
4901:
4902: @table @code
4903: @item (sign_extend:@var{m} @var{x})
4904: Represents the result of sign-extending the value @var{x}
4905: to machine mode @var{m}. @var{m} must be a fixed-point mode
4906: and @var{x} a fixed-point value of a mode narrower than @var{m}.
4907:
4908: @item (zero_extend:@var{m} @var{x})
4909: Represents the result of zero-extending the value @var{x}
4910: to machine mode @var{m}. @var{m} must be a fixed-point mode
4911: and @var{x} a fixed-point value of a mode narrower than @var{m}.
4912:
4913: @item (float_extend:@var{m} @var{x})
4914: Represents the result of extending the value @var{x}
4915: to machine mode @var{m}. @var{m} must be a floating point mode
4916: and @var{x} a floating point value of a mode narrower than @var{m}.
4917:
4918: @item (truncate:@var{m} @var{x})
4919: Represents the result of truncating the value @var{x}
4920: to machine mode @var{m}. @var{m} must be a fixed-point mode
4921: and @var{x} a fixed-point value of a mode wider than @var{m}.
4922:
4923: @item (float_truncate:@var{m} @var{x})
4924: Represents the result of truncating the value @var{x}
4925: to machine mode @var{m}. @var{m} must be a floating point mode
4926: and @var{x} a floating point value of a mode wider than @var{m}.
4927:
4928: @item (float:@var{m} @var{x})
4929: Represents the result of converting fixed point value @var{x},
4930: regarded as signed, to floating point mode @var{m}.
4931:
4932: @item (unsigned_float:@var{m} @var{x})
4933: Represents the result of converting fixed point value @var{x},
4934: regarded as unsigned, to floating point mode @var{m}.
4935:
4936: @item (fix:@var{m} @var{x})
4937: When @var{m} is a fixed point mode, represents the result of
4938: converting floating point value @var{x} to mode @var{m}, regarded as
4939: signed. How rounding is done is not specified, so this operation may
4940: be used validly in compiling C code only for integer-valued operands.
4941:
4942: @item (unsigned_fix:@var{m} @var{x})
4943: Represents the result of converting floating point value @var{x} to
4944: fixed point mode @var{m}, regarded as unsigned. How rounding is done
4945: is not specified.
4946:
4947: @item (fix:@var{m} @var{x})
4948: When @var{m} is a floating point mode, represents the result of
4949: converting floating point value @var{x} (valid for mode @var{m}) to an
4950: integer, still represented in floating point mode @var{m}, by rounding
4951: towards zero.
4952: @end table
4953:
4954: @node RTL Declarations, Side Effects, Conversions, RTL
4955: @section Declarations
4956:
4957: Declaration expression codes do not represent arithmetic operations
4958: but rather state assertions about their operands.
4959:
4960: @table @code
4961: @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
4962: This expression code is used in only one context: operand 0 of a
1.1.1.8 ! root 4963: @code{set} expression. In addition, the operand of this expression
! 4964: must be a @code{subreg} expression.
1.1 root 4965:
1.1.1.8 ! root 4966: The presence of @code{strict_low_part} says that the part of the
1.1 root 4967: register which is meaningful in mode @var{n}, but is not part of
4968: mode @var{m}, is not to be altered. Normally, an assignment to such
4969: a subreg is allowed to have undefined effects on the rest of the
4970: register when @var{m} is less than a word.
4971: @end table
4972:
4973: @node Side Effects, Incdec, RTL Declarations, RTL
4974: @section Side Effect Expressions
4975:
4976: The expression codes described so far represent values, not actions.
4977: But machine instructions never produce values; they are meaningful
4978: only for their side effects on the state of the machine. Special
4979: expression codes are used to represent side effects.
4980:
4981: The body of an instruction is always one of these side effect codes;
4982: the codes described above, which represent values, appear only as
4983: the operands of these.
4984:
4985: @table @code
4986: @item (set @var{lval} @var{x})
4987: Represents the action of storing the value of @var{x} into the place
4988: represented by @var{lval}. @var{lval} must be an expression
1.1.1.8 ! root 4989: representing a place that can be stored in: @code{reg} (or
! 4990: @code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or
! 4991: @code{cc0}.@refill
1.1 root 4992:
1.1.1.8 ! root 4993: If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
1.1 root 4994: machine mode; then @var{x} must be valid for that mode.@refill
4995:
1.1.1.8 ! root 4996: If @var{lval} is a @code{reg} whose machine mode is less than the full
1.1 root 4997: width of the register, then it means that the part of the register
4998: specified by the machine mode is given the specified value and the
4999: rest of the register receives an undefined value. Likewise, if
1.1.1.8 ! root 5000: @var{lval} is a @code{subreg} whose machine mode is narrower than
1.1 root 5001: @code{SImode}, the rest of the register can be changed in an undefined way.
5002:
1.1.1.8 ! root 5003: If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the
1.1 root 5004: part of the register specified by the machine mode of the
1.1.1.8 ! root 5005: @code{subreg} is given the value @var{x} and the rest of the register
1.1 root 5006: is not changed.@refill
5007:
5008: If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
5009: have any mode. This represents a ``test'' or ``compare'' instruction.@refill
5010:
5011: If @var{lval} is @code{(pc)}, we have a jump instruction, and the
5012: possibilities for @var{x} are very limited. It may be a
1.1.1.8 ! root 5013: @code{label_ref} expression (unconditional jump). It may be an
! 5014: @code{if_then_else} (conditional jump), in which case either the
1.1 root 5015: second or the third operand must be @code{(pc)} (for the case which
1.1.1.8 ! root 5016: does not jump) and the other of the two must be a @code{label_ref}
! 5017: (for the case which does jump). @var{x} may also be a @code{mem} or
! 5018: @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
! 5019: @code{mem}; these unusual patterns are used to represent jumps through
1.1 root 5020: branch tables.@refill
5021:
5022: @item (return)
5023: Represents a return from the current function, on machines where this
5024: can be done with one instruction, such as Vaxes. On machines where a
5025: multi-instruction ``epilogue'' must be executed in order to return
5026: from the function, returning is done by jumping to a label which
1.1.1.8 ! root 5027: precedes the epilogue, and the @code{return} expression code is never
1.1 root 5028: used.
5029:
5030: @item (call @var{function} @var{nargs})
1.1.1.8 ! root 5031: Represents a function call. @var{function} is a @code{mem} expression
1.1 root 5032: whose address is the address of the function to be called.
5033: @var{nargs} is an expression which can be used for two purposes: on
5034: some machines it represents the number of bytes of stack argument; on
5035: others, it represents the number of argument registers.
5036:
5037: Each machine has a standard machine mode which @var{function} must
5038: have. The machine description defines macro @code{FUNCTION_MODE} to
5039: expand into the requisite mode name. The purpose of this mode is to
5040: specify what kind of addressing is allowed, on machines where the
5041: allowed kinds of addressing depend on the machine mode being
5042: addressed.
5043:
5044: @item (clobber @var{x})
5045: Represents the storing or possible storing of an unpredictable,
1.1.1.8 ! root 5046: undescribed value into @var{x}, which must be a @code{reg} or
! 5047: @code{mem} expression.
1.1 root 5048:
5049: One place this is used is in string instructions that store standard
5050: values into particular hard registers. It may not be worth the
5051: trouble to describe the values that are stored, but it is essential to
5052: inform the compiler that the registers will be altered, lest it
5053: attempt to keep data in them across the string instruction.
5054:
5055: @var{x} may also be null---a null C pointer, no expression at all.
5056: Such a @code{(clobber (null))} expression means that all memory
5057: locations must be presumed clobbered.
5058:
5059: Note that the machine description classifies certain hard registers as
5060: ``call-clobbered''. All function call instructions are assumed by
5061: default to clobber these registers, so there is no need to use
1.1.1.8 ! root 5062: @code{clobber} expressions to indicate this fact. Also, each function
1.1.1.6 root 5063: call is assumed to have the potential to alter any memory location,
5064: unless the function is declared @code{const}.
1.1 root 5065:
1.1.1.8 ! root 5066: When a @code{clobber} expression for a register appears inside a
! 5067: @code{parallel} with other side effects, GNU CC guarantees that the
1.1.1.4 root 5068: register is unoccupied both before and after that insn. Therefore, it
5069: is safe for the assembler code produced by the insn to use the
5070: register as a temporary. You can clobber either a specific hard
5071: register or a pseudo register; in the latter case, GNU CC will
5072: allocate a hard register that is available there for use as a
5073: temporary.
5074:
1.1.1.8 ! root 5075: If you clobber a pseudo register in this way, use a pseudo register
! 5076: which appears nowhere else---generate a new one each time. Otherwise,
! 5077: you may confuse CSE.
! 5078:
! 5079: There is one other known use for clobbering a pseudo register in a
! 5080: @code{parallel}: when one of the input operands of the insn is also
! 5081: clobbered by the insn. In this case, using the same pseudo register in
! 5082: the clobber and elsewhere in the insn produces the expected results.
! 5083:
1.1 root 5084: @item (use @var{x})
5085: Represents the use of the value of @var{x}. It indicates that the
5086: value in @var{x} at this point in the program is needed, even though
5087: it may not be apparent why this is so. Therefore, the compiler will
1.1.1.4 root 5088: not attempt to delete previous instructions whose only effect is to
1.1.1.8 ! root 5089: store a value in @var{x}. @var{x} must be a @code{reg} expression.
1.1 root 5090:
5091: @item (parallel [@var{x0} @var{x1} @dots{}])
5092: Represents several side effects performed in parallel. The square
1.1.1.8 ! root 5093: brackets stand for a vector; the operand of @code{parallel} is a
1.1 root 5094: vector of expressions. @var{x0}, @var{x1} and so on are individual
1.1.1.8 ! root 5095: side effect expressions---expressions of code @code{set}, @code{call},
! 5096: @code{return}, @code{clobber} or @code{use}.@refill
1.1 root 5097:
5098: ``In parallel'' means that first all the values used in the individual
5099: side-effects are computed, and second all the actual side-effects are
5100: performed. For example,
5101:
5102: @example
5103: (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
5104: (set (mem:SI (reg:SI 1)) (reg:SI 1))])
5105: @end example
5106:
5107: @noindent
5108: says unambiguously that the values of hard register 1 and the memory
5109: location addressed by it are interchanged. In both places where
5110: @code{(reg:SI 1)} appears as a memory address it refers to the value
1.1.1.4 root 5111: in register 1 @emph{before} the execution of the insn.
5112:
1.1.1.8 ! root 5113: It follows that it is @emph{incorrect} to use @code{parallel} and
! 5114: expect the result of one @code{set} to be available for the next one.
1.1.1.4 root 5115: For example, people sometimes attempt to represent a jump-if-zero
5116: instruction this way:
5117:
5118: @example
5119: (parallel [(set (cc0) (reg:SI 34))
5120: (set (pc) (if_then_else
5121: (eq (cc0) (const_int 0))
5122: (label_ref @dots{})
5123: (pc)))])
5124: @end example
5125:
5126: @noindent
5127: But this is incorrect, because it says that the jump condition depends
5128: on the condition code value @emph{before} this instruction, not on the
5129: new value that is set by this instruction.
1.1 root 5130:
1.1.1.5 root 5131: Peephole optimization, which takes place in together with final assembly
1.1.1.8 ! root 5132: code output, can produce insns whose patterns consist of a @code{parallel}
1.1 root 5133: whose elements are the operands needed to output the resulting
1.1.1.8 ! root 5134: assembler code---often @code{reg}, @code{mem} or constant expressions.
1.1 root 5135: This would not be well-formed RTL at any other stage in compilation,
5136: but it is ok then because no further optimization remains to be done.
1.1.1.4 root 5137: However, the definition of the macro @code{NOTICE_UPDATE_CC} must
5138: deal with such insns if you define any peephole optimizations.
1.1 root 5139:
5140: @item (sequence [@var{insns} @dots{}])
5141: Represents a sequence of insns. Each of the @var{insns} that appears
5142: in the vector is suitable for appearing in the chain of insns, so it
1.1.1.8 ! root 5143: must be an @code{insn}, @code{jump_insn}, @code{call_insn},
! 5144: @code{code_label}, @code{barrier} or @code{note}.
1.1 root 5145:
1.1.1.8 ! root 5146: A @code{sequence} RTX never appears in an actual insn. It represents
! 5147: the sequence of insns that result from a @code{define_expand}
1.1 root 5148: @emph{before} those insns are passed to @code{emit_insn} to insert
5149: them in the chain of insns. When actually inserted, the individual
1.1.1.8 ! root 5150: sub-insns are separated out and the @code{sequence} is forgotten.
1.1 root 5151: @end table
5152:
5153: Three expression codes appear in place of a side effect, as the body of an
5154: insn, though strictly speaking they do not describe side effects as such:
5155:
5156: @table @code
5157: @item (asm_input @var{s})
5158: Represents literal assembler code as described by the string @var{s}.
5159:
5160: @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
5161: Represents a table of jump addresses. The vector elements @var{lr0},
1.1.1.8 ! root 5162: etc., are @code{label_ref} expressions. The mode @var{m} specifies
1.1 root 5163: how much space is given to each address; normally @var{m} would be
5164: @code{Pmode}.
5165:
5166: @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
5167: Represents a table of jump addresses expressed as offsets from
1.1.1.8 ! root 5168: @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
1.1 root 5169: expressions and so is @var{base}. The mode @var{m} specifies how much
5170: space is given to each address-difference.@refill
5171: @end table
5172:
5173: @node Incdec, Assembler, Side Effects, RTL
5174: @section Embedded Side-Effects on Addresses
5175:
5176: Four special side-effect expression codes appear as memory addresses.
5177:
5178: @table @code
5179: @item (pre_dec:@var{m} @var{x})
5180: Represents the side effect of decrementing @var{x} by a standard
5181: amount and represents also the value that @var{x} has after being
1.1.1.8 ! root 5182: decremented. @var{x} must be a @code{reg} or @code{mem}, but most
! 5183: machines allow only a @code{reg}. @var{m} must be the machine mode
1.1 root 5184: for pointers on the machine in use. The amount @var{x} is decremented
5185: by is the length in bytes of the machine mode of the containing memory
5186: reference of which this expression serves as the address. Here is an
5187: example of its use:@refill
5188:
5189: @example
5190: (mem:DF (pre_dec:SI (reg:SI 39)))
5191: @end example
5192:
5193: @noindent
5194: This says to decrement pseudo register 39 by the length of a @code{DFmode}
5195: value and use the result to address a @code{DFmode} value.
5196:
5197: @item (pre_inc:@var{m} @var{x})
5198: Similar, but specifies incrementing @var{x} instead of decrementing it.
5199:
5200: @item (post_dec:@var{m} @var{x})
1.1.1.8 ! root 5201: Represents the same side effect as @code{pre_dec} but a different
1.1 root 5202: value. The value represented here is the value @var{x} has @i{before}
5203: being decremented.
5204:
5205: @item (post_inc:@var{m} @var{x})
5206: Similar, but specifies incrementing @var{x} instead of decrementing it.
5207: @end table
5208:
5209: These embedded side effect expressions must be used with care. Instruction
5210: patterns may not use them. Until the @samp{flow} pass of the compiler,
5211: they may occur only to represent pushes onto the stack. The @samp{flow}
5212: pass finds cases where registers are incremented or decremented in one
5213: instruction and used as an address shortly before or after; these cases are
5214: then transformed to use pre- or post-increment or -decrement.
5215:
5216: Explicit popping of the stack could be represented with these embedded
5217: side effect operators, but that would not be safe; the instruction
5218: combination pass could move the popping past pushes, thus changing
5219: the meaning of the code.
5220:
5221: An instruction that can be represented with an embedded side effect
1.1.1.8 ! root 5222: could also be represented using @code{parallel} containing an additional
! 5223: @code{set} to describe how the address register is altered. This is not
1.1 root 5224: done because machines that allow these operations at all typically
5225: allow them wherever a memory address is called for. Describing them as
5226: additional parallel stores would require doubling the number of entries
5227: in the machine description.
5228:
5229: @node Assembler, Insns, IncDec, RTL
5230: @section Assembler Instructions as Expressions
5231:
1.1.1.8 ! root 5232: The RTX code @code{asm_operands} represents a value produced by a
1.1 root 5233: user-specified assembler instruction. It is used to represent
5234: an @code{asm} statement with arguments. An @code{asm} statement with
5235: a single output operand, like this:
5236:
5237: @example
1.1.1.6 root 5238: asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
1.1 root 5239: @end example
5240:
5241: @noindent
1.1.1.8 ! root 5242: is represented using a single @code{asm_operands} RTX which represents
1.1 root 5243: the value that is stored in @code{outputvar}:
5244:
5245: @example
5246: (set @var{rtx-for-outputvar}
5247: (asm_operands "foo %1,%2,%0" "a" 0
5248: [@var{rtx-for-addition-result} @var{rtx-for-*z}]
5249: [(asm_input:@var{m1} "g")
5250: (asm_input:@var{m2} "di")]))
5251: @end example
5252:
5253: @noindent
1.1.1.8 ! root 5254: Here the operands of the @code{asm_operands} RTX are the assembler
1.1 root 5255: template string, the output-operand's constraint, the index-number of the
5256: output operand among the output operands specified, a vector of input
5257: operand RTX's, and a vector of input-operand modes and constraints. The
5258: mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
5259: @code{*z}.
5260:
5261: When an @code{asm} statement has multiple output values, its insn has
1.1.1.8 ! root 5262: several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
! 5263: contains a @code{asm_operands}; all of these share the same assembler
1.1 root 5264: template and vectors, but each contains the constraint for the respective
5265: output operand. They are also distinguished by the output-operand index
5266: number, which is 0, 1, @dots{} for successive output operands.
5267:
5268: @node Insns, Calls, Assembler, RTL
5269: @section Insns
5270:
5271: The RTL representation of the code for a function is a doubly-linked
5272: chain of objects called @dfn{insns}. Insns are expressions with
5273: special codes that are used for no other purpose. Some insns are
5274: actual instructions; others represent dispatch tables for @code{switch}
5275: statements; others represent labels to jump to or various sorts of
5276: declarative information.
5277:
5278: In addition to its own specific data, each insn must have a unique id-number
5279: that distinguishes it from all other insns in the current function, and
5280: chain pointers to the preceding and following insns. These three fields
5281: occupy the same position in every insn, independent of the expression code
5282: of the insn. They could be accessed with @code{XEXP} and @code{XINT},
5283: but instead three special macros are always used:
5284:
5285: @table @code
5286: @item INSN_UID (@var{i})
5287: Accesses the unique id of insn @var{i}.
5288:
5289: @item PREV_INSN (@var{i})
5290: Accesses the chain pointer to the insn preceding @var{i}.
5291: If @var{i} is the first insn, this is a null pointer.
5292:
5293: @item NEXT_INSN (@var{i})
5294: Accesses the chain pointer to the insn following @var{i}.
5295: If @var{i} is the last insn, this is a null pointer.
5296: @end table
5297:
5298: The @code{NEXT_INSN} and @code{PREV_INSN} pointers must always
1.1.1.6 root 5299: correspond: if @var{insn} is not the first insn,
1.1 root 5300:
5301: @example
5302: NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
5303: @end example
5304:
5305: @noindent
5306: is always true.
5307:
5308: Every insn has one of the following six expression codes:
5309:
1.1.1.8 ! root 5310: @table @code
1.1 root 5311: @item insn
1.1.1.8 ! root 5312: The expression code @code{insn} is used for instructions that do not jump
! 5313: and do not do function calls. Insns with code @code{insn} have four
1.1 root 5314: additional fields beyond the three mandatory ones listed above.
5315: These four are described in a table below.
5316:
5317: @item jump_insn
1.1.1.8 ! root 5318: The expression code @code{jump_insn} is used for instructions that may jump
! 5319: (or, more generally, may contain @code{label_ref} expressions).
! 5320: @code{jump_insn} insns have the same extra fields as @code{insn} insns,
1.1 root 5321: accessed in the same way.
5322:
5323: @item call_insn
1.1.1.8 ! root 5324: The expression code @code{call_insn} is used for instructions that may do
1.1 root 5325: function calls. It is important to distinguish these instructions because
5326: they imply that certain registers and memory locations may be altered
5327: unpredictably.
5328:
1.1.1.8 ! root 5329: @code{call_insn} insns have the same extra fields as @code{insn} insns,
1.1 root 5330: accessed in the same way.
5331:
5332: @item code_label
1.1.1.8 ! root 5333: A @code{code_label} insn represents a label that a jump insn can jump to.
1.1 root 5334: It contains one special field of data in addition to the three standard ones.
5335: It is used to hold the @dfn{label number}, a number that identifies this
5336: label uniquely among all the labels in the compilation (not just in the
5337: current function). Ultimately, the label is represented in the assembler
5338: output as an assembler label @samp{L@var{n}} where @var{n} is the label number.
5339:
5340: @item barrier
5341: Barriers are placed in the instruction stream after unconditional
5342: jump instructions to indicate that the jumps are unconditional.
5343: They contain no information beyond the three standard fields.
5344:
5345: @item note
1.1.1.8 ! root 5346: @code{note} insns are used to represent additional debugging and
1.1 root 5347: declarative information. They contain two nonstandard fields, an
5348: integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
5349: string accessed with @code{NOTE_SOURCE_FILE}.
5350:
5351: If @code{NOTE_LINE_NUMBER} is positive, the note represents the
5352: position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
5353: that the line came from. These notes control generation of line
5354: number data in the assembler output.
5355:
5356: Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
5357: code with one of the following values (and @code{NOTE_SOURCE_FILE}
5358: must contain a null pointer):
5359:
5360: @table @code
5361: @item NOTE_INSN_DELETED
5362: Such a note is completely ignorable. Some passes of the compiler
5363: delete insns by altering them into notes of this kind.
5364:
5365: @item NOTE_INSN_BLOCK_BEG
5366: @itemx NOTE_INSN_BLOCK_END
5367: These types of notes indicate the position of the beginning and end
5368: of a level of scoping of variable names. They control the output
5369: of debugging information.
5370:
5371: @item NOTE_INSN_LOOP_BEG
5372: @itemx NOTE_INSN_LOOP_END
5373: These types of notes indicate the position of the beginning and end
5374: of a @code{while} or @code{for} loop. They enable the loop optimizer
5375: to find loops quickly.
1.1.1.6 root 5376: @item NOTE_INSN_FUNCTION_END
5377: Appears near the end of the function body, just before the label that
5378: @code{return} statements jump to (on machine where a single instruction
5379: does not suffice for returning). This note may be deleted by jump
5380: optimization.
5381: @item NOTE_INSN_SETJMP
5382: Appears following each call to @code{setjmp} or a related function.
1.1.1.7 root 5383:
5384: @item NOTE_INSN_LOOP_BEG
5385: Appears at the place in a loop that @code{continue} statements jump to.
1.1 root 5386: @end table
1.1.1.7 root 5387:
5388: These codes are printed symbolically when they appear in debugging dumps.
1.1 root 5389: @end table
5390:
1.1.1.6 root 5391: The machine mode of an insn is normally zero (@code{VOIDmode}), but the
5392: reload pass sets it to @code{QImode} if the insn needs reloading.
5393:
1.1.1.8 ! root 5394: Here is a table of the extra fields of @code{insn}, @code{jump_insn}
! 5395: and @code{call_insn} insns:
1.1 root 5396:
5397: @table @code
5398: @item PATTERN (@var{i})
5399: An expression for the side effect performed by this insn.
5400:
1.1.1.6 root 5401: @item INSN_CODE (@var{i})
5402: An integer that says which pattern in the machine description matches
5403: this insn, or -1 if the matching has not yet been attempted.
5404:
5405: Such matching is never attempted and this field is not used on an insn
1.1.1.8 ! root 5406: whose pattern consists of a single @code{use}, @code{clobber},
! 5407: @code{asm}, @code{addr_vec} or @code{addr_diff_vec} expression.
1.1 root 5408:
5409: @item LOG_LINKS (@var{i})
1.1.1.8 ! root 5410: A list (chain of @code{insn_list} expressions) of previous ``related''
1.1 root 5411: insns: insns which store into registers values that are used for the
5412: first time in this insn. (An additional constraint is that neither a
5413: jump nor a label may come between the related insns). This list is
5414: set up by the flow analysis pass; it is a null pointer until then.
5415:
1.1.1.6 root 5416: @item REG_NOTES (@var{i})
1.1.1.8 ! root 5417: A list (chain of @code{expr_list} expressions) giving information
1.1.1.6 root 5418: about the usage of registers in this insn. This list is set up by the
5419: flow analysis pass; it is a null pointer until then.
1.1 root 5420: @end table
5421:
1.1.1.8 ! root 5422: The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
1.1 root 5423: expressions. Each of these has two operands: the first is an insn,
1.1.1.8 ! root 5424: and the second is another @code{insn_list} expression (the next one in
! 5425: the chain). The last @code{insn_list} in the chain has a null pointer
1.1 root 5426: as second operand. The significant thing about the chain is which
1.1.1.8 ! root 5427: insns appear in it (as first operands of @code{insn_list}
1.1 root 5428: expressions). Their order is not significant.
5429:
5430: The @code{REG_NOTES} field of an insn is a similar chain but of
1.1.1.8 ! root 5431: @code{expr_list} expressions instead of @code{insn_list}. There are
1.1.1.5 root 5432: several kinds of register notes, which are distinguished by the machine
1.1.1.8 ! root 5433: mode of the @code{expr_list}, which in a register note is really
1.1.1.5 root 5434: understood as being an @code{enum reg_note}. The first operand @var{op}
1.1.1.8 ! root 5435: of the @code{expr_list} is data whose meaning depends on the kind of
1.1.1.5 root 5436: note. Here are the kinds of register note:
1.1 root 5437:
5438: @table @code
5439: @item REG_DEAD
5440: The register @var{op} dies in this insn; that is to say, altering the
5441: value immediately after this insn would not affect the future behavior
5442: of the program.
5443:
5444: @item REG_INC
5445: The register @var{op} is incremented (or decremented; at this level
5446: there is no distinction) by an embedded side effect inside this insn.
1.1.1.8 ! root 5447: This means it appears in a @code{post_inc}, @code{pre_inc},
! 5448: @code{post_dec} or @code{pre_dec} RTX.
1.1 root 5449:
5450: @item REG_EQUIV
5451: The register that is set by this insn will be equal to @var{op} at run
5452: time, and could validly be replaced in all its occurrences by
5453: @var{op}. (``Validly'' here refers to the data flow of the program;
5454: simple replacement may make some insns invalid.)
5455:
5456: The value which the insn explicitly copies into the register may look
5457: different from @var{op}, but they will be equal at run time.
5458:
5459: For example, when a constant is loaded into a register that is never
5460: assigned any other value, this kind of note is used.
5461:
5462: When a parameter is copied into a pseudo-register at entry to a function,
5463: a note of this kind records that the register is equivalent to the stack
5464: slot where the parameter was passed. Although in this case the register
5465: may be set by other insns, it is still valid to replace the register
5466: by the stack slot throughout the function.
5467:
5468: @item REG_EQUAL
5469: The register that is set by this insn will be equal to @var{op} at run
5470: time at the end of this insn (but not necessarily elsewhere in the
5471: function).
5472:
5473: The RTX @var{op} is typically an arithmetic expression. For example,
5474: when a sequence of insns such as a library call is used to perform an
5475: arithmetic operation, this kind of note is attached to the insn that
5476: produces or copies the final value. It tells the CSE pass how to
5477: think of that value.
5478:
5479: @item REG_RETVAL
5480: This insn copies the value of a library call, and @var{op} is the
5481: first insn that was generated to set up the arguments for the library
5482: call.
5483:
5484: Flow analysis uses this note to delete all of a library call whose
5485: result is dead.
5486:
5487: @item REG_WAS_0
5488: The register @var{op} contained zero before this insn. You can rely
5489: on this note if it is present; its absence implies nothing.
5490:
5491: @item REG_LIBCALL
5492: This is the inverse of @code{REG_RETVAL}: it is placed on the first
5493: insn of a library call, and it points to the last one.
5494:
5495: Loop optimization uses this note to move an entire library call out
5496: of a loop when its value is constant.
5497:
5498: @item REG_NONNEG
5499: The register @var{op} is known to have nonnegative value when this
5500: insn is reached.
5501: @end table
5502:
1.1.1.8 ! root 5503: For convenience, the machine mode in an @code{insn_list} or
! 5504: @code{expr_list} is printed using these symbolic codes in debugging dumps.
1.1.1.7 root 5505:
1.1.1.8 ! root 5506: The only difference between the expression codes @code{insn_list} and
! 5507: @code{expr_list} is that the first operand of an @code{insn_list} is
1.1 root 5508: assumed to be an insn and is printed in debugging dumps as the insn's
1.1.1.8 ! root 5509: unique id; the first operand of an @code{expr_list} is printed in the
1.1.1.7 root 5510: ordinary way as an expression.
1.1 root 5511:
5512: @node Calls, Sharing, Insns, RTL
5513: @section RTL Representation of Function-Call Insns
5514:
1.1.1.8 ! root 5515: Insns that call subroutines have the RTL expression code @code{call_insn}.
1.1 root 5516: These insns must satisfy special rules, and their bodies must use a special
1.1.1.8 ! root 5517: RTL expression code, @code{call}.
1.1 root 5518:
1.1.1.8 ! root 5519: A @code{call} expression has two operands, as follows:
1.1 root 5520:
5521: @example
1.1.1.6 root 5522: (call (mem:@var{fm} @var{addr}) @var{nbytes})
1.1 root 5523: @end example
5524:
5525: @noindent
5526: Here @var{nbytes} is an operand that represents the number of bytes of
5527: argument data being passed to the subroutine, @var{fm} is a machine mode
5528: (which must equal as the definition of the @code{FUNCTION_MODE} macro in
5529: the machine description) and @var{addr} represents the address of the
5530: subroutine.
5531:
1.1.1.8 ! root 5532: For a subroutine that returns no value, the @code{call} RTX as shown above
1.1 root 5533: is the entire body of the insn.
5534:
5535: For a subroutine that returns a value whose mode is not @code{BLKmode},
5536: the value is returned in a hard register. If this register's number is
5537: @var{r}, then the body of the call insn looks like this:
5538:
5539: @example
5540: (set (reg:@var{m} @var{r})
5541: (call @var{nbytes} (mem:@var{fm} @var{addr})))
5542: @end example
5543:
5544: @noindent
5545: This RTL expression makes it clear (to the optimizer passes) that the
5546: appropriate register receives a useful value in this insn.
5547:
5548: Immediately after RTL generation, if the value of the subroutine is
5549: actually used, this call insn is always followed closely by an insn which
5550: refers to the register @var{r}. This remains true through all the
5551: optimizer passes until cross jumping occurs.
5552:
5553: The following insn has one of two forms. Either it copies the value into a
5554: pseudo-register, like this:
5555:
5556: @example
5557: (set (reg:@var{m} @var{p}) (reg:@var{m} @var{r}))
5558: @end example
5559:
5560: @noindent
5561: or (in the case where the calling function will simply return whatever
5562: value the call produced, and no operation is needed to do this):
5563:
5564: @example
5565: (use (reg:@var{m} @var{r}))
5566: @end example
5567:
5568: @noindent
5569: Between the call insn and this following insn there may intervene only a
1.1.1.8 ! root 5570: stack-adjustment insn (and perhaps some @code{note} insns).
1.1 root 5571:
5572: When a subroutine returns a @code{BLKmode} value, it is handled by
5573: passing to the subroutine the address of a place to store the value.
5574: So the call insn itself does not ``return'' any value, and it has the
5575: same RTL form as a call that returns nothing.
5576:
5577: @node Sharing,, Calls, RTL
5578: @section Structure Sharing Assumptions
5579:
5580: The compiler assumes that certain kinds of RTL expressions are unique;
5581: there do not exist two distinct objects representing the same value.
5582: In other cases, it makes an opposite assumption: that no RTL expression
5583: object of a certain kind appears in more than one place in the
5584: containing structure.
5585:
5586: These assumptions refer to a single function; except for the RTL
5587: objects that describe global variables and external functions,
5588: no RTL objects are common to two functions.
5589:
5590: @itemize @bullet
5591: @item
1.1.1.8 ! root 5592: Each pseudo-register has only a single @code{reg} object to represent it,
1.1 root 5593: and therefore only a single machine mode.
5594:
5595: @item
1.1.1.8 ! root 5596: For any symbolic label, there is only one @code{symbol_ref} object
1.1 root 5597: referring to it.
5598:
5599: @item
1.1.1.8 ! root 5600: There is only one @code{const_int} expression with value zero,
1.1 root 5601: and only one with value one.
5602:
5603: @item
1.1.1.8 ! root 5604: There is only one @code{pc} expression.
1.1 root 5605:
5606: @item
1.1.1.8 ! root 5607: There is only one @code{cc0} expression.
1.1 root 5608:
5609: @item
1.1.1.8 ! root 5610: There is only one @code{const_double} expression with mode
1.1 root 5611: @code{SFmode} and value zero, and only one with mode @code{DFmode} and
5612: value zero.
5613:
5614: @item
1.1.1.8 ! root 5615: No @code{label_ref} appears in more than one place in the RTL
1.1 root 5616: structure; in other words, it is safe to do a tree-walk of all the
1.1.1.8 ! root 5617: insns in the function and assume that each time a @code{label_ref} is
1.1 root 5618: seen it is distinct from all others that are seen.
5619:
5620: @item
1.1.1.8 ! root 5621: Only one @code{mem} object is normally created for each static
1.1 root 5622: variable or stack slot, so these objects are frequently shared in all
5623: the places they appear. However, separate but equal objects for these
5624: variables are occasionally made.
5625:
5626: @item
1.1.1.5 root 5627: When a single @code{asm} statement has multiple output operands,
5628: a distinct @code{asm_operands} RTX is made for each output operand.
5629: However, these all share the vector which contains the sequence of
5630: input operands. Because this sharing is used later on to test whether
5631: two @code{asm_operands} RTX's come from the same statement, the sharing
5632: must be guaranteed to be preserved.
5633:
5634: @item
1.1 root 5635: No RTL object appears in more than one place in the RTL structure
5636: except as described above. Many passes of the compiler rely on this
5637: by assuming that they can modify RTL objects in place without unwanted
5638: side-effects on other insns.
5639:
5640: @item
5641: During initial RTL generation, shared structure is freely introduced.
5642: After all the RTL for a function has been generated, all shared
5643: structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
5644: after which the above rules are guaranteed to be followed.
5645:
5646: @item
5647: During the combiner pass, shared structure with an insn can exist
5648: temporarily. However, the shared structure is copied before the
5649: combiner is finished with the insn. This is done by
1.1.1.8 ! root 5650: @code{copy_substitutions} in @file{combine.c}.
1.1 root 5651: @end itemize
5652:
5653: @node Machine Desc, Machine Macros, RTL, Top
5654: @chapter Machine Descriptions
5655:
5656: A machine description has two parts: a file of instruction patterns
5657: (@file{.md} file) and a C header file of macro definitions.
5658:
5659: The @file{.md} file for a target machine contains a pattern for each
5660: instruction that the target machine supports (or at least each instruction
5661: that is worth telling the compiler about). It may also contain comments.
5662: A semicolon causes the rest of the line to be a comment, unless the semicolon
5663: is inside a quoted string.
5664:
5665: See the next chapter for information on the C header file.
5666:
5667: @menu
5668: * Patterns:: How to write instruction patterns.
1.1.1.8 ! root 5669: * Example:: An explained example of a @code{define_insn} pattern.
1.1 root 5670: * RTL Template:: The RTL template defines what insns match a pattern.
5671: * Output Template:: The output template says how to make assembler code
5672: from such an insn.
5673: * Output Statement:: For more generality, write C code to output
5674: the assembler code.
5675: * Constraints:: When not all operands are general operands.
5676: * Standard Names:: Names mark patterns to use for code generation.
5677: * Pattern Ordering:: When the order of patterns makes a difference.
5678: * Dependent Patterns:: Having one pattern may make you need another.
5679: * Jump Patterns:: Special considerations for patterns for jump insns.
5680: * Peephole Definitions::Defining machine-specific peephole optimizations.
5681: * Expander Definitions::Generating a sequence of several RTL insns
5682: for a standard operation.
5683: @end menu
5684:
5685: @node Patterns, Example, Machine Desc, Machine Desc
5686: @section Everything about Instruction Patterns
5687:
5688: Each instruction pattern contains an incomplete RTL expression, with pieces
5689: to be filled in later, operand constraints that restrict how the pieces can
5690: be filled in, and an output pattern or C code to generate the assembler
1.1.1.8 ! root 5691: output, all wrapped up in a @code{define_insn} expression.
1.1 root 5692:
1.1.1.8 ! root 5693: A @code{define_insn} is an RTL expression containing four or five operands:
1.1 root 5694:
5695: @enumerate
5696: @item
5697: An optional name. The presence of a name indicate that this instruction
5698: pattern can perform a certain standard job for the RTL-generation
5699: pass of the compiler. This pass knows certain names and will use
5700: the instruction patterns with those names, if the names are defined
5701: in the machine description.
5702:
5703: The absence of a name is indicated by writing an empty string
5704: where the name should go. Nameless instruction patterns are never
5705: used for generating RTL code, but they may permit several simpler insns
5706: to be combined later on.
5707:
5708: Names that are not thus known and used in RTL-generation have no
5709: effect; they are equivalent to no name at all.
5710:
5711: @item
5712: The @dfn{RTL template} (@pxref{RTL Template}) is a vector of
5713: incomplete RTL expressions which show what the instruction should look
1.1.1.8 ! root 5714: like. It is incomplete because it may contain @code{match_operand}
! 5715: and @code{match_dup} expressions that stand for operands of the
1.1 root 5716: instruction.
5717:
5718: If the vector has only one element, that element is what the
5719: instruction should look like. If the vector has multiple elements,
1.1.1.8 ! root 5720: then the instruction looks like a @code{parallel} expression
1.1 root 5721: containing that many elements as described.
5722:
5723: @item
5724: A condition. This is a string which contains a C expression that is
5725: the final test to decide whether an insn body matches this pattern.
5726:
5727: For a named pattern, the condition (if present) may not depend on
5728: the data in the insn being matched, but only the target-machine-type
5729: flags. The compiler needs to test these conditions during
5730: initialization in order to learn exactly which named instructions are
5731: available in a particular run.
5732:
5733: For nameless patterns, the condition is applied only when matching an
5734: individual insn, and only after the insn has matched the pattern's
5735: recognition template. The insn's operands may be found in the vector
5736: @code{operands}.
5737:
5738: @item
5739: The @dfn{output template}: a string that says how to output matching
5740: insns as assembler code. @samp{%} in this string specifies where
5741: to substitute the value of an operand. @xref{Output Template}.
5742:
5743: When simple substitution isn't general enough, you can specify a piece
5744: of C code to compute the output. @xref{Output Statement}.
5745:
5746: @item
5747: Optionally, some @dfn{machine-specific information}. The meaning
5748: of this information is defined only by an individual machine description;
5749: typically it might say whether this insn alters the condition codes,
5750: or how many bytes of output it generates.
5751:
5752: This operand is written as a string containing a C initializer
5753: (complete with braces) for the structure type @code{INSN_MACHINE_INFO},
5754: whose definition is up to you (@pxref{Misc}).
5755: @end enumerate
5756:
5757: @node Example, RTL Template, Patterns, Machine Desc
1.1.1.8 ! root 5758: @section Example of @code{define_insn}
1.1 root 5759:
5760: Here is an actual example of an instruction pattern, for the 68000/68020.
5761:
5762: @example
5763: (define_insn "tstsi"
5764: [(set (cc0)
5765: (match_operand:SI 0 "general_operand" "rm"))]
5766: ""
5767: "*
5768: @{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
5769: return \"tstl %0\";
5770: return \"cmpl #0,%0\"; @}")
5771: @end example
5772:
5773: This is an instruction that sets the condition codes based on the value of
5774: a general operand. It has no condition, so any insn whose RTL description
5775: has the form shown may be handled according to this pattern. The name
5776: @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
5777: pass that, when it is necessary to test such a value, an insn to do so
5778: can be constructed using this pattern.
5779:
5780: The output control string is a piece of C code which chooses which
5781: output template to return based on the kind of operand and the specific
5782: type of CPU for which code is being generated.
5783:
5784: @samp{"rm"} is an operand constraint. Its meaning is explained below.
5785:
5786: @node RTL Template, Output Template, Example, Machine Desc
5787: @section RTL Template for Generating and Recognizing Insns
5788:
5789: The RTL template is used to define which insns match the particular pattern
5790: and how to find their operands. For named patterns, the RTL template also
5791: says how to construct an insn from specified operands.
5792:
5793: Construction involves substituting specified operands into a copy of the
5794: template. Matching involves determining the values that serve as the
5795: operands in the insn being matched. Both of these activities are
5796: controlled by special expression types that direct matching and
5797: substitution of the operands.
5798:
5799: @table @code
1.1.1.8 ! root 5800: @item (match_operand:@var{m} @var{n} @var{pred} @var{constraint})
1.1 root 5801: This expression is a placeholder for operand number @var{n} of
5802: the insn. When constructing an insn, operand number @var{n}
5803: will be substituted at this point. When matching an insn, whatever
5804: appears at this position in the insn will be taken as operand
1.1.1.8 ! root 5805: number @var{n}; but it must satisfy @var{pred} or this instruction
1.1 root 5806: pattern will not match at all.
5807:
5808: Operand numbers must be chosen consecutively counting from zero in
1.1.1.8 ! root 5809: each instruction pattern. There may be only one @code{match_operand}
1.1 root 5810: expression in the pattern for each operand number. Usually operands
1.1.1.8 ! root 5811: are numbered in the order of appearance in @code{match_operand}
1.1 root 5812: expressions.
5813:
1.1.1.8 ! root 5814: @var{pred} is a string that is the name of a C function that accepts
! 5815: two arguments, an expression and a machine mode. During matching, the
! 5816: function will be called with the putative operand as the expression
! 5817: and @var{m} as the mode argument. If it returns zero, this
! 5818: instruction pattern fails to match. @var{pred} may be an empty
! 5819: string; then it means no test is to be done on the operand,
! 5820: so anything which occurs in this position is valid.
! 5821:
! 5822: @var{constraint} controls reloading and the choice of the best register
! 5823: class to use for a value, as explained later (@pxref{Constraints}).
! 5824:
! 5825: People are often unclear on the difference between the constraint and the
! 5826: predicate. The predicate helps decide whether a given insn matches the
! 5827: pattern. The constraint plays no role in this decision; instead, it
! 5828: controls various decisions in the case of an insn which does match.
! 5829:
! 5830: Most often, @var{pred} is @code{"general_operand"}. This function checks
! 5831: that the putative operand is either a constant, a register or a memory
! 5832: reference, and that it is valid for mode @var{m}.
1.1 root 5833:
1.1.1.8 ! root 5834: For an operand that must be a register, @var{pred} should be
1.1 root 5835: @code{"register_operand"}. It would be valid to use
5836: @code{"general_operand"}, since the reload pass would copy any
5837: non-register operands through registers, but this would make GNU CC do
5838: extra work, and it would prevent the register allocator from doing the
5839: best possible job.
5840:
1.1.1.8 ! root 5841: For an operand that must be a constant, either @var{pred} should be
1.1 root 5842: @code{"immediate_operand"}, or the instruction pattern's extra
5843: condition should check for constants, or both. You cannot expect the
5844: constraints to do this work! If the constraints allow only constants,
5845: but the predicate allows something else, the compiler will crash when
5846: that case arises.
5847:
5848: @item (match_dup @var{n})
5849: This expression is also a placeholder for operand number @var{n}.
5850: It is used when the operand needs to appear more than once in the
5851: insn.
5852:
1.1.1.8 ! root 5853: In construction, @code{match_dup} behaves exactly like
! 5854: @code{match_operand}: the operand is substituted into the insn being
! 5855: constructed. But in matching, @code{match_dup} behaves differently.
1.1 root 5856: It assumes that operand number @var{n} has already been determined by
1.1.1.8 ! root 5857: a @code{match_operand} appearing earlier in the recognition template,
1.1 root 5858: and it matches only an identical-looking expression.
5859:
1.1.1.4 root 5860: @item (match_operator:@var{m} @var{n} "@var{predicate}" [@var{operands}@dots{}])
5861: This pattern is a kind of placeholder for a variable RTL expression
5862: code.
5863:
5864: When constructing an insn, it stands for an RTL expression whose
5865: expression code is taken from that of operand @var{n}, and whose
5866: operands are constructed from the patterns @var{operands}.
5867:
5868: When matching an expression, it matches an expression if the function
5869: @var{predicate} returns nonzero on that expression @emph{and} the
5870: patterns @var{operands} match the operands of the expression.
5871:
5872: Suppose that the function @code{commutative_operator} is defined as
5873: follows, to match any expression whose operator is one of the six
5874: commutative arithmetic operators of RTL and whose mode is @var{mode}:
5875:
5876: @example
5877: int
5878: commutative_operator (x, mode)
5879: rtx x;
5880: enum machine_mode mode;
5881: @{
5882: enum rtx_code code = GET_CODE (x);
5883: if (GET_MODE (x) != mode)
5884: return 0;
5885: return (code == PLUS || code == MULT || code == UMULT
5886: || code == AND || code == IOR || code == XOR);
5887: @}
5888: @end example
5889:
5890: Then the following pattern will match any RTL expression consisting
5891: of a commutative operator applied to two general operands:
5892:
5893: @example
5894: (match_operator:SI 2 "commutative_operator"
5895: [(match_operand:SI 3 "general_operand" "g")
5896: (match_operand:SI 4 "general_operand" "g")])
5897: @end example
5898:
5899: Here the vector @code{[@var{operands}@dots{}]} contains two patterns
5900: because the expressions to be matched all contain two operands.
5901:
5902: When this pattern does match, the two operands of the commutative
5903: operator are recorded as operands 3 and 4 of the insn. (This is done
1.1.1.8 ! root 5904: by the two instances of @code{match_operand}.) Operand 2 of the insn
1.1.1.4 root 5905: will be the entire commutative expression: use @code{GET_CODE
5906: (operands[2])} to see which commutative operator was used.
5907:
1.1.1.8 ! root 5908: The machine mode @var{m} of @code{match_operator} works like that of
! 5909: @code{match_operand}: it is passed as the second argument to the
1.1.1.4 root 5910: predicate function, and that function is solely responsible for
5911: deciding whether the expression to be matched ``has'' that mode.
5912:
5913: When constructing an insn, argument 2 of the gen-function will specify
5914: the operation (i.e. the expression code) for the expression to be
5915: made. It should be an RTL expression, whose expression code is copied
5916: into a new expression whose operands are arguments 3 and 4 of the
5917: gen-function. The subexpressions of argument 2 are not used;
5918: only its expression code matters.
5919:
1.1.1.8 ! root 5920: There is no way to specify constraints in @code{match_operator}. The
! 5921: operand of the insn which corresponds to the @code{match_operator}
1.1.1.4 root 5922: never has any constraints because it is never reloaded as a whole.
5923: However, if parts of its @var{operands} are matched by
1.1.1.8 ! root 5924: @code{match_operand} patterns, those parts may have constraints of
1.1.1.4 root 5925: their own.
5926:
1.1 root 5927: @item (address (match_operand:@var{m} @var{n} "address_operand" ""))
5928: This complex of expressions is a placeholder for an operand number
5929: @var{n} in a ``load address'' instruction: an operand which specifies
5930: a memory location in the usual way, but for which the actual operand
5931: value used is the address of the location, not the contents of the
5932: location.
5933:
1.1.1.8 ! root 5934: @code{address} expressions never appear in RTL code, only in machine
1.1 root 5935: descriptions. And they are used only in machine descriptions that do
5936: not use the operand constraint feature. When operand constraints are
5937: in use, the letter @samp{p} in the constraint serves this purpose.
5938:
5939: @var{m} is the machine mode of the @emph{memory location being
5940: addressed}, not the machine mode of the address itself. That mode is
5941: always the same on a given target machine (it is @code{Pmode}, which
5942: normally is @code{SImode}), so there is no point in mentioning it;
1.1.1.8 ! root 5943: thus, no machine mode is written in the @code{address} expression. If
1.1 root 5944: some day support is added for machines in which addresses of different
5945: kinds of objects appear differently or are used differently (such as
5946: the PDP-10), different formats would perhaps need different machine
1.1.1.8 ! root 5947: modes and these modes might be written in the @code{address}
1.1 root 5948: expression.
5949: @end table
5950:
5951: @node Output Template, Output Statement, RTL Template, Machine Desc
5952: @section Output Templates and Operand Substitution
5953:
1.1.1.6 root 5954: The @dfn{output template} is a string which specifies how to output the
5955: assembler code for an instruction pattern. Most of the template is a
5956: fixed string which is output literally. The character @samp{%} is used
5957: to specify where to substitute an operand; it can also be used to
5958: identify places where different variants of the assembler require
1.1 root 5959: different syntax.
5960:
5961: In the simplest case, a @samp{%} followed by a digit @var{n} says to output
5962: operand @var{n} at that point in the string.
5963:
5964: @samp{%} followed by a letter and a digit says to output an operand in an
5965: alternate fashion. Four letters have standard, built-in meanings described
5966: below. The machine description macro @code{PRINT_OPERAND} can define
5967: additional letters with nonstandard meanings.
5968:
5969: @samp{%c@var{digit}} can be used to substitute an operand that is a
5970: constant value without the syntax that normally indicates an immediate
5971: operand.
5972:
5973: @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
5974: the constant is negated before printing.
5975:
5976: @samp{%a@var{digit}} can be used to substitute an operand as if it were a
5977: memory reference, with the actual operand treated as the address. This may
5978: be useful when outputting a ``load address'' instruction, because often the
5979: assembler syntax for such an instruction requires you to write the operand
5980: as if it were a memory reference.
5981:
5982: @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
5983: instruction.
5984:
5985: @samp{%} followed by a punctuation character specifies a substitution that
5986: does not use an operand. Only one case is standard: @samp{%%} outputs a
5987: @samp{%} into the assembler code. Other nonstandard cases can be
1.1.1.8 ! root 5988: defined in the @code{PRINT_OPERAND} macro. You must also define
! 5989: which punctuation characters are valid with the
! 5990: @code{PRINT_OPERAND_PUNCT_VALID_P} macro.
1.1 root 5991:
5992: The template may generate multiple assembler instructions. Write the text
5993: for the instructions, with @samp{\;} between them.
5994:
1.1.1.6 root 5995: When the RTL contains two operands which are required by constraint to match
1.1 root 5996: each other, the output template must refer only to the lower-numbered operand.
5997: Matching operands are not always identical, and the rest of the compiler
5998: arranges to put the proper RTL expression for printing into the lower-numbered
5999: operand.
6000:
6001: One use of nonstandard letters or punctuation following @samp{%} is to
6002: distinguish between different assembler languages for the same machine; for
6003: example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax
6004: requires periods in most opcode names, while MIT syntax does not. For
6005: example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
6006: syntax. The same file of patterns is used for both kinds of output syntax,
6007: but the character sequence @samp{%.} is used in each place where Motorola
6008: syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax
6009: defines the sequence to output a period; the macro for MIT syntax defines
6010: it to do nothing.
6011:
6012: @node Output Statement, Constraints, Output Template, Machine Desc
6013: @section C Statements for Generating Assembler Output
6014:
6015: Often a single fixed template string cannot produce correct and efficient
6016: assembler code for all the cases that are recognized by a single
6017: instruction pattern. For example, the opcodes may depend on the kinds of
6018: operands; or some unfortunate combinations of operands may require extra
6019: machine instructions.
6020:
6021: If the output control string starts with a @samp{*}, then it is not an
6022: output template but rather a piece of C program that should compute a
6023: template. It should execute a @code{return} statement to return the
6024: template-string you want. Most such templates use C string literals, which
6025: require doublequote characters to delimit them. To include these
6026: doublequote characters in the string, prefix each one with @samp{\}.
6027:
6028: The operands may be found in the array @code{operands}, whose C data type
6029: is @code{rtx []}.
6030:
6031: It is possible to output an assembler instruction and then go on to output
6032: or compute more of them, using the subroutine @code{output_asm_insn}. This
6033: receives two arguments: a template-string and a vector of operands. The
6034: vector may be @code{operands}, or it may be another array of @code{rtx}
6035: that you declare locally and initialize yourself.
6036:
6037: When an insn pattern has multiple alternatives in its constraints, often
1.1.1.5 root 6038: the appearance of the assembler code is determined mostly by which alternative
1.1 root 6039: was matched. When this is so, the C code can test the variable
6040: @code{which_alternative}, which is the ordinal number of the alternative
6041: that was actually satisfied (0 for the first, 1 for the second alternative,
6042: etc.).
6043:
6044: For example, suppose there are two opcodes for storing zero, @samp{clrreg}
6045: for registers and @samp{clrmem} for memory locations. Here is how
6046: a pattern could use @code{which_alternative} to choose between them:
6047:
6048: @example
6049: (define_insn ""
6050: [(set (match_operand:SI 0 "general_operand" "r,m")
6051: (const_int 0))]
6052: ""
6053: "*
6054: return (which_alternative == 0
6055: ? \"clrreg %0\" : \"clrmem %0\");
6056: ")
6057: @end example
6058:
6059: @node Constraints, Standard Names, Output Statement, Machine Desc
6060: @section Operand Constraints
6061:
1.1.1.8 ! root 6062: Each @code{match_operand} in an instruction pattern can specify a
1.1 root 6063: constraint for the type of operands allowed. Constraints can say whether
6064: an operand may be in a register, and which kinds of register; whether the
6065: operand can be a memory reference, and which kinds of address; whether the
6066: operand may be an immediate constant, and which possible values it may
6067: have. Constraints can also require two operands to match.
6068:
6069: @menu
6070: * Simple Constraints:: Basic use of constraints.
6071: * Multi-Alternative:: When an insn has two alternative constraint-patterns.
6072: * Class Preferences:: Constraints guide which hard register to put things in.
6073: * Modifiers:: More precise control over effects of constraints.
6074: * No Constraints:: Describing a clean machine without constraints.
6075: @end menu
6076:
6077: @node Simple Constraints, Multi-Alternative, Constraints, Constraints
6078: @subsection Simple Constraints
6079:
6080: The simplest kind of constraint is a string full of letters, each of
6081: which describes one kind of operand that is permitted. Here are
6082: the letters that are allowed:
6083:
6084: @table @asis
6085: @item @samp{m}
6086: A memory operand is allowed, with any kind of address that the machine
6087: supports in general.
6088:
6089: @item @samp{o}
6090: A memory operand is allowed, but only if the address is
1.1.1.8 ! root 6091: @dfn{offsettable}. This means that adding a small integer (actually,
1.1 root 6092: the width in bytes of the operand, as determined by its machine mode)
6093: may be added to the address and the result is also a valid memory
6094: address.
6095:
1.1.1.8 ! root 6096: For example, an address which is constant is offsettable; so is an
1.1 root 6097: address that is the sum of a register and a constant (as long as a
6098: slightly larger constant is also within the range of address-offsets
6099: supported by the machine); but an autoincrement or autodecrement
1.1.1.8 ! root 6100: address is not offsettable. More complicated indirect/indexed
! 6101: addresses may or may not be offsettable depending on the other
1.1 root 6102: addressing modes that the machine supports.
6103:
6104: Note that in an output operand which can be matched by another
6105: operand, the constraint letter @samp{o} is valid only when accompanied
6106: by both @samp{<} (if the target machine has predecrement addressing)
6107: and @samp{>} (if the target machine has preincrement addressing).
6108:
6109: When the constraint letter @samp{o} is used, the reload pass may
1.1.1.8 ! root 6110: generate instructions which copy a nonoffsettable address into an index
1.1 root 6111: register. The idea is that the register can be used as a replacement
1.1.1.8 ! root 6112: offsettable address. But this method requires that there be patterns
1.1 root 6113: to copy any kind of address into a register. Auto-increment
6114: and auto-decrement addresses are an exception; there need not be an
6115: instruction that can copy such an address into a register, because
6116: reload handles these cases specially.
6117:
6118: Most older machine designs have ``load address'' instructions which do
6119: just what is needed here. Some RISC machines do not advertise such
6120: instructions, but the possible addresses on these machines are very
6121: limited, so it is easy to fake them.
6122:
6123: @item @samp{<}
6124: A memory operand with autodecrement addressing (either predecrement or
6125: postdecrement) is allowed.
6126:
6127: @item @samp{>}
6128: A memory operand with autoincrement addressing (either preincrement or
6129: postincrement) is allowed.
6130:
6131: @item @samp{r}
6132: A register operand is allowed provided that it is in a general
6133: register.
6134:
6135: @item @samp{d}, @samp{a}, @samp{f}, @dots{}
6136: Other letters can be defined in machine-dependent fashion to stand for
6137: particular classes of registers. @samp{d}, @samp{a} and @samp{f} are
6138: defined on the 68000/68020 to stand for data, address and floating
6139: point registers.
6140:
6141: @item @samp{i}
6142: An immediate integer operand (one with constant value) is allowed.
6143: This includes symbolic constants whose values will be known only at
6144: assembly time.
6145:
6146: @item @samp{n}
6147: An immediate integer operand with a known numeric value is allowed.
6148: Many systems cannot support assembly-time constants for operands less
6149: than a word wide. Constraints for these operands should use @samp{n}
6150: rather than @samp{i}.
6151:
6152: @item @samp{I}, @samp{J}, @samp{K}, @dots{}
6153: Other letters in the range @samp{I} through @samp{M} may be defined in
6154: a machine-dependent fashion to permit immediate integer operands with
6155: explicit integer values in specified ranges. For example, on the
6156: 68000, @samp{I} is defined to stand for the range of values 1 to 8.
6157: This is the range permitted as a shift count in the shift
6158: instructions.
6159:
6160: @item @samp{F}
1.1.1.8 ! root 6161: An immediate floating operand (expression code @code{const_double}) is
1.1 root 6162: allowed.
6163:
6164: @item @samp{G}, @samp{H}
6165: @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
6166: permit immediate floating operands in particular ranges of values.
6167:
6168: @item @samp{s}
6169: An immediate integer operand whose value is not an explicit integer is
6170: allowed.
6171:
6172: This might appear strange; if an insn allows a constant operand with a
6173: value not known at compile time, it certainly must allow any known
6174: value. So why use @samp{s} instead of @samp{i}? Sometimes it allows
6175: better code to be generated.
6176:
6177: For example, on the 68000 in a fullword instruction it is possible to
6178: use an immediate operand; but if the immediate value is between -32
6179: and 31, better code results from loading the value into a register and
6180: using the register. This is because the load into the register can be
6181: done with a @samp{moveq} instruction. We arrange for this to happen
6182: by defining the letter @samp{K} to mean ``any integer outside the
6183: range -32 to 31'', and then specifying @samp{Ks} in the operand
6184: constraints.
6185:
6186: @item @samp{g}
6187: Any register, memory or immediate integer operand is allowed, except for
6188: registers that are not general registers.
6189:
6190: @item @samp{@var{n}} (a digit)
6191: An operand that matches operand number @var{n} is allowed.
6192: If a digit is used together with letters, the digit should come last.
6193:
6194: This is called a @dfn{matching constraint} and what it really means is
6195: that the assembler has only a single operand that fills two roles
6196: considered separate in the RTL insn. For example, an add insn has two
6197: input operands and one output operand in the RTL, but on most machines
6198: an add instruction really has only two operands, one of them an
6199: input-output operand.
6200:
6201: Matching constraints work only in circumstances like that add insn.
6202: More precisely, the matching constraint must appear in an input-only
6203: operand and the operand that it matches must be an output-only operand
1.1.1.5 root 6204: with a lower number. Thus, operand @var{n} must have @samp{=} in its
6205: constraint.
1.1 root 6206:
6207: For operands to match in a particular case usually means that they
6208: are identical-looking RTL expressions. But in a few special cases
6209: specific kinds of dissimilarity are allowed. For example, @code{*x}
6210: as an input operand will match @code{*x++} as an output operand.
6211: For proper results in such cases, the output template should always
6212: use the output-operand's number when printing the operand.
6213:
6214: @item @samp{p}
6215: An operand that is a valid memory address is allowed. This is
6216: for ``load address'' and ``push address'' instructions.
6217:
1.1.1.8 ! root 6218: @samp{p} in the constraint must be accompanies by @code{address_operand}
! 6219: as the predicate in the @code{match_operand}.
1.1 root 6220: @end table
6221:
6222: In order to have valid assembler code, each operand must satisfy
6223: its constraint. But a failure to do so does not prevent the pattern
6224: from applying to an insn. Instead, it directs the compiler to modify
6225: the code so that the constraint will be satisfied. Usually this is
6226: done by copying an operand into a register.
6227:
6228: Contrast, therefore, the two instruction patterns that follow:
6229:
6230: @example
6231: (define_insn ""
6232: [(set (match_operand:SI 0 "general_operand" "r")
6233: (plus:SI (match_dup 0)
6234: (match_operand:SI 1 "general_operand" "r")))]
6235: ""
6236: "@dots{}")
6237: @end example
6238:
6239: @noindent
6240: which has two operands, one of which must appear in two places, and
6241:
6242: @example
6243: (define_insn ""
6244: [(set (match_operand:SI 0 "general_operand" "r")
6245: (plus:SI (match_operand:SI 1 "general_operand" "0")
6246: (match_operand:SI 2 "general_operand" "r")))]
6247: ""
6248: "@dots{}")
6249: @end example
6250:
6251: @noindent
6252: which has three operands, two of which are required by a constraint to be
6253: identical. If we are considering an insn of the form
6254:
6255: @example
6256: (insn @var{n} @var{prev} @var{next}
6257: (set (reg:SI 3)
6258: (plus:SI (reg:SI 6) (reg:SI 109)))
6259: @dots{})
6260: @end example
6261:
6262: @noindent
6263: the first pattern would not apply at all, because this insn does not
6264: contain two identical subexpressions in the right place. The pattern would
6265: say, ``That does not look like an add instruction; try other patterns.''
6266: The second pattern would say, ``Yes, that's an add instruction, but there
6267: is something wrong with it.'' It would direct the reload pass of the
6268: compiler to generate additional insns to make the constraint true. The
6269: results might look like this:
6270:
6271: @example
6272: (insn @var{n2} @var{prev} @var{n}
6273: (set (reg:SI 3) (reg:SI 6))
6274: @dots{})
6275:
6276: (insn @var{n} @var{n2} @var{next}
6277: (set (reg:SI 3)
6278: (plus:SI (reg:SI 3) (reg:SI 109)))
6279: @dots{})
6280: @end example
6281:
6282: It is up to you to make sure that each operand, in each pattern, has
6283: constraints that can handle any RTL expression that could be present for
6284: that operand. (When multiple alternatives are in use, each pattern must,
6285: for each possible combination of operand expressions, have at least one
6286: alternative which can handle that combination of operands.) The
6287: constraints don't need to @emph{allow} any possible operand---when this is
6288: the case, they do not constrain---but they must at least point the way to
6289: reloading any possible operand so that it will fit.
6290:
6291: @itemize @bullet
6292: @item
6293: If the constraint accepts whatever operands the predicate permits,
6294: there is no problem: reloading is never necessary for this operand.
6295:
6296: For example, an operand whose constraints permit everything except
6297: registers is safe provided its predicate rejects registers.
6298:
6299: An operand whose predicate accepts only constant values is safe
6300: provided its constraints include the letter @samp{i}. If any possible
6301: constant value is accepted, then nothing less than @samp{i} will do;
1.1.1.5 root 6302: if the predicate is more selective, then the constraints may also be
1.1 root 6303: more selective.
6304:
6305: @item
6306: Any operand expression can be reloaded by copying it into a register.
6307: So if an operand's constraints allow some kind of register, it is
6308: certain to be safe. It need not permit all classes of registers; the
6309: compiler knows how to copy a register into another register of the
6310: proper class in order to make an instruction valid.
6311:
6312: @item
1.1.1.8 ! root 6313: A nonoffsettable memory reference can be reloaded by copying the
1.1 root 6314: address into a register. So if the constraint uses the letter
6315: @samp{o}, all memory references are taken care of.
6316:
6317: @item
1.1.1.8 ! root 6318: A constant operand can be reloaded by allocating space in memory to
! 6319: hold it as preinitialized data. Then the memory reference can be used
! 6320: in place of the constant. So if the constraint uses the letters
! 6321: @samp{o} or @samp{m}, constant operands are not a problem.
1.1 root 6322: @end itemize
6323:
6324: If the operand's predicate can recognize registers, but the constraint does
6325: not permit them, it can make the compiler crash. When this operand happens
6326: to be a register, the reload pass will be stymied, because it does not know
6327: how to copy a register temporarily into memory.
6328:
6329: @node Multi-Alternative, Class Preferences, Simple Constraints, Constraints
6330: @subsection Multiple Alternative Constraints
6331:
6332: Sometimes a single instruction has multiple alternative sets of possible
6333: operands. For example, on the 68000, a logical-or instruction can combine
6334: register or an immediate value into memory, or it can combine any kind of
6335: operand into a register; but it cannot combine one memory location into
6336: another.
6337:
6338: These constraints are represented as multiple alternatives. An alternative
6339: can be described by a series of letters for each operand. The overall
6340: constraint for an operand is made from the letters for this operand
6341: from the first alternative, a comma, the letters for this operand from
6342: the second alternative, a comma, and so on until the last alternative.
6343: Here is how it is done for fullword logical-or on the 68000:
6344:
6345: @example
6346: (define_insn "iorsi3"
6347: [(set (match_operand:SI 0 "general_operand" "=%m,d")
6348: (ior:SI (match_operand:SI 1 "general_operand" "0,0")
6349: (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
6350: @dots{})
6351: @end example
6352:
6353: The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
6354: operand 1 (meaning it must match operand 0), and @samp{dKs} for operand 2.
6355: The second alternative has @samp{d} (data register) for operand 0, @samp{0}
6356: for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and @samp{%} in
6357: the constraint for operand 0 are not part of any alternative; their meaning
6358: is explained in the next section.
6359:
6360: If all the operands fit any one alternative, the instruction is valid.
6361: Otherwise, for each alternative, the compiler counts how many instructions
6362: must be added to copy the operands so that that alternative applies.
6363: The alternative requiring the least copying is chosen. If two alternatives
6364: need the same amount of copying, the one that comes first is chosen.
6365: These choices can be altered with the @samp{?} and @samp{!} characters:
6366:
6367: @table @samp
6368: @item ?
6369: Disparage slightly the alternative that the @samp{?} appears in,
6370: as a choice when no alternative applies exactly. The compiler regards
6371: this alternative as one unit more costly for each @samp{?} that appears
6372: in it.
6373:
6374: @item !
6375: Disparage severely the alternative that the @samp{!} appears in.
6376: When operands must be copied into registers, the compiler will
6377: never choose this alternative as the one to strive for.
6378: @end table
6379:
1.1.1.5 root 6380: When an insn pattern has multiple alternatives in its constraints, often
6381: the appearance of the assembler code is determined mostly by which
1.1 root 6382: alternative was matched. When this is so, the C code for writing the
6383: assembler code can use the variable @code{which_alternative}, which is
1.1.1.5 root 6384: the ordinal number of the alternative that was actually satisfied (0 for
6385: the first, 1 for the second alternative, etc.). For example:
1.1 root 6386:
6387: @example
6388: (define_insn ""
6389: [(set (match_operand:SI 0 "general_operand" "r,m")
6390: (const_int 0))]
6391: ""
6392: "*
6393: return (which_alternative == 0
6394: ? \"clrreg %0\" : \"clrmem %0\");
6395: ")
6396: @end example
6397:
6398: @node Class Preferences, Modifiers, Multi-Alternative, Constraints
6399: @subsection Register Class Preferences
6400:
6401: The operand constraints have another function: they enable the compiler
6402: to decide which kind of hardware register a pseudo register is best
6403: allocated to. The compiler examines the constraints that apply to the
6404: insns that use the pseudo register, looking for the machine-dependent
6405: letters such as @samp{d} and @samp{a} that specify classes of registers.
6406: The pseudo register is put in whichever class gets the most ``votes''.
6407: The constraint letters @samp{g} and @samp{r} also vote: they vote in
6408: favor of a general register. The machine description says which registers
6409: are considered general.
6410:
6411: Of course, on some machines all registers are equivalent, and no register
6412: classes are defined. Then none of this complexity is relevant.
6413:
6414: @node Modifiers, No Constraints, Class Preferences, Constraints
6415: @subsection Constraint Modifier Characters
6416:
6417: @table @samp
6418: @item =
6419: Means that this operand is write-only for this instruction: the previous
6420: value is discarded and replaced by output data.
6421:
6422: @item +
6423: Means that this operand is both read and written by the instruction.
6424:
6425: When the compiler fixes up the operands to satisfy the constraints,
6426: it needs to know which operands are inputs to the instruction and
6427: which are outputs from it. @samp{=} identifies an output; @samp{+}
6428: identifies an operand that is both input and output; all other operands
6429: are assumed to be input only.
6430:
6431: @item &
6432: Means (in a particular alternative) that this operand is written
6433: before the instruction is finished using the input operands.
6434: Therefore, this operand may not lie in a register that is used as an
6435: input operand or as part of any memory address.
6436:
6437: @samp{&} applies only to the alternative in which it is written. In
6438: constraints with multiple alternatives, sometimes one alternative
6439: requires @samp{&} while others do not. See, for example, the
6440: @samp{movdf} insn of the 68000.
6441:
6442: @samp{&} does not obviate the need to write @samp{=}.
6443:
6444: @item %
6445: Declares the instruction to be commutative for this operand and the
6446: following operand. This means that the compiler may interchange the
6447: two operands if that is the cheapest way to make all operands fit the
6448: constraints. This is often used in patterns for addition instructions
6449: that really have only two operands: the result must go in one of the
6450: arguments. Here for example, is how the 68000 halfword-add
6451: instruction is defined:
6452:
6453: @example
6454: (define_insn "addhi3"
6455: [(set (match_operand:HI 0 "general_operand" "=m,r")
6456: (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
6457: (match_operand:HI 2 "general_operand" "di,g")))]
6458: @dots{})
6459: @end example
6460:
6461: Note that in previous versions of GNU CC the @samp{%} constraint
6462: modifier always applied to operands 1 and 2 regardless of which
6463: operand it was written in. The usual custom was to write it in
6464: operand 0. Now it must be in operand 1 if the operands to be
6465: exchanged are 1 and 2.
6466:
6467: @item #
6468: Says that all following characters, up to the next comma, are to be
6469: ignored as a constraint. They are significant only for choosing
6470: register preferences.
6471:
6472: @item *
6473: Says that the following character should be ignored when choosing
6474: register preferences. @samp{*} has no effect on the meaning of the
6475: constraint as a constraint.
6476:
6477: Here is an example: the 68000 has an instruction to sign-extend a
6478: halfword in a data register, and can also sign-extend a value by
6479: copying it into an address register. While either kind of register is
6480: acceptable, the constraints on an address-register destination are
6481: less strict, so it is best if register allocation makes an address
6482: register its goal. Therefore, @samp{*} is used so that the @samp{d}
6483: constraint letter (for data register) is ignored when computing
6484: register preferences.
6485:
6486: @example
6487: (define_insn "extendhisi2"
6488: [(set (match_operand:SI 0 "general_operand" "=*d,a")
6489: (sign_extend:SI
6490: (match_operand:HI 1 "general_operand" "0,g")))]
6491: @dots{})
6492: @end example
6493: @end table
6494:
6495: @node No Constraints,, Modifiers, Constraints
6496: @subsection Not Using Constraints
6497:
6498: Some machines are so clean that operand constraints are not required. For
6499: example, on the Vax, an operand valid in one context is valid in any other
6500: context. On such a machine, every operand constraint would be @samp{g},
6501: excepting only operands of ``load address'' instructions which are
6502: written as if they referred to a memory location's contents but actual
6503: refer to its address. They would have constraint @samp{p}.
6504:
6505: For such machines, instead of writing @samp{g} and @samp{p} for all
6506: the constraints, you can choose to write a description with empty constraints.
1.1.1.8 ! root 6507: Then you write @samp{""} for the constraint in every @code{match_operand}.
! 6508: Address operands are identified by writing an @code{address} expression
! 6509: around the @code{match_operand}, not by their constraints.
1.1 root 6510:
6511: When the machine description has just empty constraints, certain parts
1.1.1.6 root 6512: of compilation are skipped, making the compiler faster. However,
6513: few machines actually do not need constraints; all machine descriptions
6514: now in existence use constraints.
1.1 root 6515:
6516: @node Standard Names, Pattern Ordering, Constraints, Machine Desc
6517: @section Standard Names for Patterns Used in Generation
6518:
6519: Here is a table of the instruction names that are meaningful in the RTL
6520: generation pass of the compiler. Giving one of these names to an
6521: instruction pattern tells the RTL generation pass that it can use the
6522: pattern in to accomplish a certain task.
6523:
6524: @table @asis
6525: @item @samp{mov@var{m}}
1.1.1.8 ! root 6526: Here @var{m} stands for a two-letter machine mode name, in lower case.
! 6527: This instruction pattern moves data with that machine mode from operand
! 6528: 1 to operand 0. For example, @samp{movsi} moves full-word data.
1.1 root 6529:
1.1.1.8 ! root 6530: If operand 0 is a @code{subreg} with mode @var{m} of a register whose
! 6531: own mode is wider than @var{m}, the effect of this instruction is
1.1 root 6532: to store the specified value in the part of the register that corresponds
6533: to mode @var{m}. The effect on the rest of the register is undefined.
6534:
6535: This class of patterns is special in several ways. First of all, each
6536: of these names @emph{must} be defined, because there is no other way
6537: to copy a datum from one place to another.
6538:
6539: Second, these patterns are not used solely in the RTL generation pass.
6540: Even the reload pass can generate move insns to copy values from stack
1.1.1.8 ! root 6541: slots into temporary registers. When it does so, one of the operands is
! 6542: a hard register and the other is an operand that can need to be reloaded
! 6543: into a register.
! 6544:
! 6545: Therefore, when given such a pair of operands, the pattern must generate
! 6546: RTL which needs no reloading and needs no temporary registers---no
! 6547: registers other than the operands. For example, if you support the
! 6548: pattern with a @code{define_expand}, then in such a case the
! 6549: @code{define_expand} mustn't call @code{force_reg} or any other such
! 6550: function which might generate new pseudo registers.
1.1 root 6551:
6552: This requirement exists even for subword modes on a RISC machine where
6553: fetching those modes from memory normally requires several insns and
6554: some temporary registers. Look in @file{spur.md} to see how the
1.1.1.8 ! root 6555: requirement can be satisfied.
1.1 root 6556:
6557: The variety of operands that have reloads depends on the rest of the
6558: machine description, but typically on a RISC machine these can only be
6559: pseudo registers that did not get hard registers, while on other
6560: machines explicit memory references will get optional reloads.
6561:
6562: In addition, the constraints must allow any hard register to be moved
6563: to any other hard register (provided that @code{HARD_REGNO_MODE_OK}
6564: permits mode @var{m} in each of the registers).
6565:
6566: @item @samp{movstrict@var{m}}
1.1.1.8 ! root 6567: Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
1.1 root 6568: with mode @var{m} of a register whose natural mode is wider,
6569: the @samp{movstrict@var{m}} instruction is guaranteed not to alter
6570: any of the register except the part which belongs to mode @var{m}.
6571:
6572: @item @samp{add@var{m}3}
6573: Add operand 2 and operand 1, storing the result in operand 0. All operands
6574: must have mode @var{m}. This can be used even on two-address machines, by
6575: means of constraints requiring operands 1 and 0 to be the same location.
6576:
6577: @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}
6578: Similar, for other arithmetic operations.
6579:
6580: There are special considerations for register classes for logical-and
6581: instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}.
6582: They apply not only to the patterns with these standard names, but to
6583: any patterns that will match such an instruction. @xref{Register
6584: Classes}.
6585:
6586: @item @samp{mulhisi3}
6587: Multiply operands 1 and 2, which have mode @code{HImode}, and store
6588: a @code{SImode} product in operand 0.
6589:
6590: @item @samp{mulqihi3}, @samp{mulsidi3}
6591: Similar widening-multiplication instructions of other widths.
6592:
6593: @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
6594: Similar widening-multiplication instructions that do unsigned
6595: multiplication.
6596:
6597: @item @samp{divmod@var{m}4}
6598: Signed division that produces both a quotient and a remainder.
6599: Operand 1 is divided by operand 2 to produce a quotient stored
6600: in operand 0 and a remainder stored in operand 3.
6601:
6602: @item @samp{udivmod@var{m}4}
6603: Similar, but does unsigned division.
6604:
6605: @item @samp{divmod@var{m}@var{n}4}
6606: Like @samp{divmod@var{m}4} except that only the dividend has mode
6607: @var{m}; the divisor, quotient and remainder have mode @var{n}.
6608: For example, the Vax has a @samp{divmoddisi4} instruction
6609: (but it is omitted from the machine description, because it
6610: is so slow that it is faster to compute remainders by the
6611: circumlocution that the compiler will use if this instruction is
6612: not available).
6613:
6614: @item @samp{ashl@var{m}3}
6615: Arithmetic-shift operand 1 left by a number of bits specified by
6616: operand 2, and store the result in operand 0. Operand 2 has
6617: mode @code{SImode}, not mode @var{m}.
6618:
6619: @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}
6620: Other shift and rotate instructions.
6621:
6622: Logical and arithmetic left shift are the same. Machines that do not
6623: allow negative shift counts often have only one instruction for
6624: shifting left. On such machines, you should define a pattern named
6625: @samp{ashl@var{m}3} and leave @samp{lshl@var{m}3} undefined.
6626:
6627: There are special considerations for register classes for shift
6628: instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}.
6629: They apply not only to the patterns with these standard names, but to
6630: any patterns that will match such an instruction. @xref{Register
6631: Classes}.
6632:
6633: @item @samp{neg@var{m}2}
6634: Negate operand 1 and store the result in operand 0.
6635:
6636: @item @samp{abs@var{m}2}
6637: Store the absolute value of operand 1 into operand 0.
6638:
6639: @item @samp{sqrt@var{m}2}
6640: Store the square root of operand 1 into operand 0.
6641:
6642: @item @samp{ffs@var{m}2}
6643: Store into operand 0 one plus the index of the least significant 1-bit
6644: of operand 1. If operand 1 is zero, store zero. @var{m} is the mode
6645: of operand 0; operand 1's mode is specified by the instruction
6646: pattern, and the compiler will convert the operand to that mode before
6647: generating the instruction.
6648:
6649: @item @samp{one_cmpl@var{m}2}
6650: Store the bitwise-complement of operand 1 into operand 0.
6651:
6652: @item @samp{cmp@var{m}}
6653: Compare operand 0 and operand 1, and set the condition codes.
6654: The RTL pattern should look like this:
6655:
6656: @example
1.1.1.6 root 6657: (set (cc0) (compare (match_operand:@var{m} 0 @dots{})
6658: (match_operand:@var{m} 1 @dots{})))
1.1 root 6659: @end example
6660:
6661: Each such definition in the machine description, for integer mode
6662: @var{m}, must have a corresponding @samp{tst@var{m}} pattern, because
6663: optimization can simplify the compare into a test when operand 1 is
6664: zero.
6665:
6666: @item @samp{tst@var{m}}
6667: Compare operand 0 against zero, and set the condition codes.
6668: The RTL pattern should look like this:
6669:
6670: @example
6671: (set (cc0) (match_operand:@var{m} 0 @dots{}))
6672: @end example
6673:
6674: @item @samp{movstr@var{m}}
6675: Block move instruction. The addresses of the destination and source
6676: strings are the first two operands, and both are in mode @code{Pmode}.
6677: The number of bytes to move is the third operand, in mode @var{m}.
1.1.1.5 root 6678: The fourth operand is the known shared alignment of the source and
6679: destination, in the form of a @code{const_int} rtx.
1.1 root 6680:
6681: @item @samp{cmpstr@var{m}}
6682: Block compare instruction, with operands like @samp{movstr@var{m}}
6683: except that the two memory blocks are compared byte by byte
6684: in lexicographic order. The effect of the instruction is to set
6685: the condition codes.
6686:
6687: @item @samp{float@var{m}@var{n}2}
6688: Convert operand 1 (valid for fixed point mode @var{m}) to floating
6689: point mode @var{n} and store in operand 0 (which has mode @var{n}).
6690:
6691: @item @samp{fix@var{m}@var{n}2}
6692: Convert operand 1 (valid for floating point mode @var{m}) to fixed
6693: point mode @var{n} as a signed number and store in operand 0 (which
6694: has mode @var{n}). This instruction's result is defined only when
6695: the value of operand 1 is an integer.
6696:
6697: @item @samp{fixuns@var{m}@var{n}2}
6698: Convert operand 1 (valid for floating point mode @var{m}) to fixed
6699: point mode @var{n} as an unsigned number and store in operand 0 (which
6700: has mode @var{n}). This instruction's result is defined only when the
6701: value of operand 1 is an integer.
6702:
6703: @item @samp{ftrunc@var{m}2}
6704: Convert operand 1 (valid for floating point mode @var{m}) to an
6705: integer value, still represented in floating point mode @var{m}, and
6706: store it in operand 0 (valid for floating point mode @var{m}).
6707:
6708: @item @samp{fix_trunc@var{m}@var{n}2}
6709: Like @samp{fix@var{m}@var{n}2} but works for any floating point value
6710: of mode @var{m} by converting the value to an integer.
6711:
6712: @item @samp{fixuns_trunc@var{m}@var{n}2}
6713: Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
6714: value of mode @var{m} by converting the value to an integer.
6715:
6716: @item @samp{trunc@var{m}@var{n}}
6717: Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
6718: store in operand 0 (which has mode @var{n}). Both modes must be fixed
6719: point or both floating point.
6720:
6721: @item @samp{extend@var{m}@var{n}}
6722: Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
6723: store in operand 0 (which has mode @var{n}). Both modes must be fixed
6724: point or both floating point.
6725:
6726: @item @samp{zero_extend@var{m}@var{n}}
6727: Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
6728: store in operand 0 (which has mode @var{n}). Both modes must be fixed
6729: point.
6730:
6731: @item @samp{extv}
6732: Extract a bit-field from operand 1 (a register or memory operand),
6733: where operand 2 specifies the width in bits and operand 3 the starting
6734: bit, and store it in operand 0. Operand 0 must have @code{Simode}.
6735: Operand 1 may have mode @code{QImode} or @code{SImode}; often
6736: @code{SImode} is allowed only for registers. Operands 2 and 3 must be
6737: valid for @code{SImode}.
6738:
6739: The RTL generation pass generates this instruction only with constants
6740: for operands 2 and 3.
6741:
6742: The bit-field value is sign-extended to a full word integer
6743: before it is stored in operand 0.
6744:
6745: @item @samp{extzv}
6746: Like @samp{extv} except that the bit-field value is zero-extended.
6747:
6748: @item @samp{insv}
6749: Store operand 3 (which must be valid for @code{SImode}) into a
6750: bit-field in operand 0, where operand 1 specifies the width in bits
6751: and operand 2 the starting bit. Operand 0 may have mode @code{QImode}
6752: or @code{SImode}; often @code{SImode} is allowed only for registers.
6753: Operands 1 and 2 must be valid for @code{SImode}.
6754:
6755: The RTL generation pass generates this instruction only with constants
6756: for operands 1 and 2.
6757:
6758: @item @samp{s@var{cond}}
6759: Store zero or nonzero in the operand according to the condition codes.
6760: Value stored is nonzero iff the condition @var{cond} is true.
6761: @var{cond} is the name of a comparison operation expression code, such
1.1.1.8 ! root 6762: as @code{eq}, @code{lt} or @code{leu}.
1.1 root 6763:
6764: You specify the mode that the operand must have when you write the
6765: @code{match_operand} expression. The compiler automatically sees
6766: which mode you have used and supplies an operand of that mode.
6767:
1.1.1.8 ! root 6768: The value stored for a true condition must have 1 as its low bit, or
! 6769: else must be negative. Otherwise the instruction is not suitable and
! 6770: must be omitted from the machine description. You must tell the
! 6771: compiler exactly which value is stored by defining the macro
! 6772: @code{STORE_FLAG_VALUE}.
1.1 root 6773:
6774: @item @samp{b@var{cond}}
1.1.1.8 ! root 6775: Conditional branch instruction. Operand 0 is a @code{label_ref}
1.1 root 6776: that refers to the label to jump to. Jump if the condition codes
6777: meet condition @var{cond}.
6778:
6779: @item @samp{call}
6780: Subroutine call instruction returning no value. Operand 0 is the
6781: function to call; operand 1 is the number of bytes of arguments pushed
1.1.1.8 ! root 6782: (in mode @code{SImode}, except it is normally a @code{const_int});
1.1 root 6783: operand 2 is the number of registers used as operands.
6784:
6785: On most machines, operand 2 is not actually stored into the RTL
6786: pattern. It is supplied for the sake of some RISC machines which need
6787: to put this information into the assembler code; they can put it in
6788: the RTL instead of operand 1.
6789:
1.1.1.8 ! root 6790: Operand 0 should be a @code{mem} RTX whose address is the address of
1.1 root 6791: the function.
6792:
6793: @item @samp{call_value}
6794: Subroutine call instruction returning a value. Operand 0 is the hard
6795: register in which the value is returned. There are three more
6796: operands, the same as the three operands of the @samp{call}
6797: instruction (but with numbers increased by one).
6798:
6799: Subroutines that return @code{BLKmode} objects use the @samp{call}
6800: insn.
6801:
6802: @item @samp{return}
6803: Subroutine return instruction. This instruction pattern name should be
6804: defined only if a single instruction can do all the work of returning
6805: from a function.
6806:
1.1.1.8 ! root 6807: @item @samp{nop}
! 6808: No-op instruction. This instruction pattern name should always be defined
! 6809: to output a no-op in assembler code. @code{(const_int 0)} will do as an
! 6810: RTL pattern.
! 6811:
1.1 root 6812: @item @samp{casesi}
6813: Instruction to jump through a dispatch table, including bounds checking.
6814: This instruction takes five operands:
6815:
6816: @enumerate
6817: @item
6818: The index to dispatch on, which has mode @code{SImode}.
6819:
6820: @item
6821: The lower bound for indices in the table, an integer constant.
6822:
6823: @item
1.1.1.6 root 6824: The total range of indices in the table---the largest index
6825: minus the smallest one (both inclusive).
1.1 root 6826:
6827: @item
6828: A label to jump to if the index has a value outside the bounds.
6829: (If the machine-description macro @code{CASE_DROPS_THROUGH} is defined,
6830: then an out-of-bounds index drops through to the code following
6831: the jump table instead of jumping to this label. In that case,
6832: this label is not actually used by the @samp{casesi} instruction,
6833: but it is always provided as an operand.)
6834:
6835: @item
6836: A label that precedes the table itself.
6837: @end enumerate
6838:
1.1.1.8 ! root 6839: The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a
! 6840: @code{jump_insn}. The number of elements in the table is one plus the
1.1 root 6841: difference between the upper bound and the lower bound.
6842:
6843: @item @samp{tablejump}
6844: Instruction to jump to a variable address. This is a low-level
6845: capability which can be used to implement a dispatch table when there
6846: is no @samp{casesi} pattern.
6847:
6848: This pattern requires two operands: the address or offset, and a label
6849: which should immediately precede the jump table. If the macro
6850: @code{CASE_VECTOR_PC_RELATIVE} is defined then the first operand is an
6851: absolute address to jump to; otherwise, it is an offset which counts
6852: from the address of the table.
6853:
6854: The @samp{tablejump} insn is always the last insn before the jump
6855: table it uses. Its assembler code normally has no need to use the
6856: second operand, but you should incorporate it in the RTL pattern so
6857: that the jump optimizer will not delete the table as unreachable code.
6858: @end table
6859:
6860: @node Pattern Ordering, Dependent Patterns, Standard Names, Machine Desc
6861: @section When the Order of Patterns Matters
6862:
6863: Sometimes an insn can match more than one instruction pattern. Then the
6864: pattern that appears first in the machine description is the one used.
6865: Therefore, more specific patterns (patterns that will match fewer things)
6866: and faster instructions (those that will produce better code when they
6867: do match) should usually go first in the description.
6868:
6869: In some cases the effect of ordering the patterns can be used to hide
6870: a pattern when it is not valid. For example, the 68000 has an
6871: instruction for converting a fullword to floating point and another
6872: for converting a byte to floating point. An instruction converting
6873: an integer to floating point could match either one. We put the
6874: pattern to convert the fullword first to make sure that one will
6875: be used rather than the other. (Otherwise a large integer might
6876: be generated as a single-byte immediate quantity, which would not work.)
6877: Instead of using this pattern ordering it would be possible to make the
6878: pattern for convert-a-byte smart enough to deal properly with any
6879: constant value.
6880:
6881: @node Dependent Patterns, Jump Patterns, Pattern Ordering, Machine Desc
6882: @section Interdependence of Patterns
6883:
6884: Every machine description must have a named pattern for each of the
6885: conditional branch names @samp{b@var{cond}}. The recognition template
6886: must always have the form
6887:
6888: @example
6889: (set (pc)
6890: (if_then_else (@var{cond} (cc0) (const_int 0))
6891: (label_ref (match_operand 0 "" ""))
6892: (pc)))
6893: @end example
6894:
6895: @noindent
6896: In addition, every machine description must have an anonymous pattern
6897: for each of the possible reverse-conditional branches. These patterns
6898: look like
6899:
6900: @example
6901: (set (pc)
6902: (if_then_else (@var{cond} (cc0) (const_int 0))
6903: (pc)
6904: (label_ref (match_operand 0 "" ""))))
6905: @end example
6906:
6907: @noindent
6908: They are necessary because jump optimization can turn direct-conditional
6909: branches into reverse-conditional branches.
6910:
6911: The compiler does more with RTL than just create it from patterns
6912: and recognize the patterns: it can perform arithmetic expression codes
6913: when constant values for their operands can be determined. As a result,
6914: sometimes having one pattern can require other patterns. For example, the
6915: Vax has no `and' instruction, but it has `and not' instructions. Here
6916: is the definition of one of them:
6917:
6918: @example
6919: (define_insn "andcbsi2"
6920: [(set (match_operand:SI 0 "general_operand" "")
6921: (and:SI (match_dup 0)
6922: (not:SI (match_operand:SI
6923: 1 "general_operand" ""))))]
6924: ""
6925: "bicl2 %1,%0")
6926: @end example
6927:
6928: @noindent
6929: If operand 1 is an explicit integer constant, an instruction constructed
6930: using that pattern can be simplified into an `and' like this:
6931:
6932: @example
6933: (set (reg:SI 41)
6934: (and:SI (reg:SI 41)
6935: (const_int 0xffff7fff)))
6936: @end example
6937:
6938: @noindent
6939: (where the integer constant is the one's complement of what
6940: appeared in the original instruction).
6941:
6942: To avoid a fatal error, the compiler must have a pattern that recognizes
6943: such an instruction. Here is what is used:
6944:
6945: @example
6946: (define_insn ""
6947: [(set (match_operand:SI 0 "general_operand" "")
6948: (and:SI (match_dup 0)
6949: (match_operand:SI 1 "general_operand" "")))]
6950: "GET_CODE (operands[1]) == CONST_INT"
6951: "*
6952: @{ operands[1]
6953: = gen_rtx (CONST_INT, VOIDmode, ~INTVAL (operands[1]));
6954: return \"bicl2 %1,%0\";
6955: @}")
6956: @end example
6957:
6958: @noindent
6959: Whereas a pattern to match a general `and' instruction is impossible to
6960: support on the Vax, this pattern is possible because it matches only a
6961: constant second argument: a special case that can be output as an `and not'
6962: instruction.
6963:
6964: A ``compare'' instruction whose RTL looks like this:
6965:
6966: @example
1.1.1.6 root 6967: (set (cc0) (compare @var{operand} (const_int 0)))
1.1 root 6968: @end example
6969:
6970: @noindent
6971: may be simplified by optimization into a ``test'' like this:
6972:
6973: @example
6974: (set (cc0) @var{operand})
6975: @end example
6976:
6977: @noindent
6978: So in the machine description, each ``compare'' pattern for an integer
6979: mode must have a corresponding ``test'' pattern that will match the
6980: result of such simplification.
6981:
6982: In some cases machines support instructions identical except for the
6983: machine mode of one or more operands. For example, there may be
6984: ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
6985: patterns are
6986:
6987: @example
6988: (set (match_operand:SI 0 @dots{})
6989: (extend:SI (match_operand:HI 1 @dots{})))
6990:
6991: (set (match_operand:SI 0 @dots{})
6992: (extend:SI (match_operand:QI 1 @dots{})))
6993: @end example
6994:
6995: @noindent
6996: Constant integers do not specify a machine mode, so an instruction to
6997: extend a constant value could match either pattern. The pattern it
6998: actually will match is the one that appears first in the file. For correct
6999: results, this must be the one for the widest possible mode (@code{HImode},
7000: here). If the pattern matches the @code{QImode} instruction, the results
7001: will be incorrect if the constant value does not actually fit that mode.
7002:
7003: Such instructions to extend constants are rarely generated because they are
7004: optimized away, but they do occasionally happen in nonoptimized
7005: compilations.
7006:
7007: When an instruction has the constraint letter @samp{o}, the reload
1.1.1.8 ! root 7008: pass may generate instructions which copy a nonoffsettable address into
1.1 root 7009: an index register. The idea is that the register can be used as a
1.1.1.8 ! root 7010: replacement offsettable address. In order for these generated
1.1 root 7011: instructions to work, there must be patterns to copy any kind of valid
7012: address into a register.
7013:
7014: Most older machine designs have ``load address'' instructions which do
7015: just what is needed here. Some RISC machines do not advertise such
7016: instructions, but the possible addresses on these machines are very
7017: limited, so it is easy to fake them.
7018:
7019: Auto-increment and auto-decrement addresses are an exception; there
7020: need not be an instruction that can copy such an address into a
7021: register, because reload handles these cases in a different manner.
7022:
7023: @node Jump Patterns, Peephole Definitions, Dependent Patterns, Machine Desc
7024: @section Defining Jump Instruction Patterns
7025:
7026: GNU CC assumes that the machine has a condition code. A comparison insn
7027: sets the condition code, recording the results of both signed and unsigned
7028: comparison of the given operands. A separate branch insn tests the
7029: condition code and branches or not according its value. The branch insns
7030: come in distinct signed and unsigned flavors. Many common machines, such
7031: as the Vax, the 68000 and the 32000, work this way.
7032:
7033: Some machines have distinct signed and unsigned compare instructions, and
7034: only one set of conditional branch instructions. The easiest way to handle
7035: these machines is to treat them just like the others until the final stage
7036: where assembly code is written. At this time, when outputting code for the
7037: compare instruction, peek ahead at the following branch using
7038: @code{NEXT_INSN (insn)}. (The variable @code{insn} refers to the insn
7039: being output, in the output-writing code in an instruction pattern.) If
7040: the RTL says that is an unsigned branch, output an unsigned compare;
7041: otherwise output a signed compare. When the branch itself is output, you
7042: can treat signed and unsigned branches identically.
7043:
7044: The reason you can do this is that GNU CC always generates a pair of
7045: consecutive RTL insns, one to set the condition code and one to test it,
7046: and keeps the pair inviolate until the end.
7047:
7048: To go with this technique, you must define the machine-description macro
7049: @code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no
7050: compare instruction is superfluous.
7051:
7052: Some machines have compare-and-branch instructions and no condition code.
7053: A similar technique works for them. When it is time to ``output'' a
7054: compare instruction, record its operands in two static variables. When
7055: outputting the branch-on-condition-code instruction that follows, actually
7056: output a compare-and-branch instruction that uses the remembered operands.
7057:
7058: It also works to define patterns for compare-and-branch instructions.
7059: In optimizing compilation, the pair of compare and branch instructions
1.1.1.5 root 7060: will be combined according to these patterns. But this does not happen
1.1 root 7061: if optimization is not requested. So you must use one of the solutions
7062: above in addition to any special patterns you define.
7063:
7064: @node Peephole Definitions, Expander Definitions, Jump Patterns, Machine Desc
7065: @section Defining Machine-Specific Peephole Optimizers
7066:
7067: In addition to instruction patterns the @file{md} file may contain
7068: definitions of machine-specific peephole optimizations.
7069:
7070: The combiner does not notice certain peephole optimizations when the data
7071: flow in the program does not suggest that it should try them. For example,
7072: sometimes two consecutive insns related in purpose can be combined even
7073: though the second one does not appear to use a register computed in the
7074: first one. A machine-specific peephole optimizer can detect such
7075: opportunities.
7076:
7077: A definition looks like this:
7078:
7079: @example
7080: (define_peephole
7081: [@var{insn-pattern-1}
7082: @var{insn-pattern-2}
7083: @dots{}]
7084: "@var{condition}"
7085: "@var{template}"
7086: "@var{machine-specific info}")
7087: @end example
7088:
7089: @noindent
7090: The last string operand may be omitted if you are not using any
7091: machine-specific information in this machine description. If present,
1.1.1.8 ! root 7092: it must obey the same rules as in a @code{define_insn}.
1.1 root 7093:
7094: In this skeleton, @var{insn-pattern-1} and so on are patterns to match
1.1.1.5 root 7095: consecutive insns. The optimization applies to a sequence of insns when
7096: @var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
7097: the next, and so on.@refill
1.1 root 7098:
1.1.1.8 ! root 7099: Each of the insns matched by a peephole must also match a
! 7100: @code{define_insn}. Peepholes are checked only at the last stage just
! 7101: before code generation, and only optionally. Therefore, any insn which
! 7102: would match a peephole but no @code{define_insn} will cause a crash in code
! 7103: generation in an unoptimized compilation, or at various optimization
! 7104: stages.
1.1 root 7105:
1.1.1.5 root 7106: The operands of the insns are matched with @code{match_operands} and
7107: @code{match_dup}, as usual. What is not usual is that the operand numbers
7108: apply to all the insn patterns in the definition. So, you can check for
7109: identical operands in two insns by using @code{match_operand} in one insn
7110: and @code{match_dup} in the other.
1.1 root 7111:
7112: The operand constraints used in @code{match_operand} patterns do not have
1.1.1.8 ! root 7113: any direct effect on the applicability of the peephole, but they will
! 7114: be validated afterward, so make sure your constraints are general enough
! 7115: to apply whenever the peephole matches. If the peephole matches
! 7116: but the constraints are not satisfied, the compiler will crash.
! 7117:
! 7118: It is safe to omit constraints in all the operands of the peephole; or
! 7119: you can write constraints which serve as a double-check on the criteria
! 7120: previously tested.
1.1 root 7121:
1.1.1.5 root 7122: Once a sequence of insns matches the patterns, the @var{condition} is
7123: checked. This is a C expression which makes the final decision whether to
7124: perform the optimization (we do so if the expression is nonzero). If
1.1 root 7125: @var{condition} is omitted (in other words, the string is empty) then the
1.1.1.5 root 7126: optimization is applied to every sequence of insns that matches the
1.1 root 7127: patterns.
7128:
1.1.1.5 root 7129: The defined peephole optimizations are applied after register allocation
7130: is complete. Therefore, the peephole definition can check which
7131: operands have ended up in which kinds of registers, just by looking at
7132: the operands.
1.1 root 7133:
7134: The way to refer to the operands in @var{condition} is to write
7135: @code{operands[@var{i}]} for operand number @var{i} (as matched by
7136: @code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} to
7137: refer to the last of the insns being matched; use @code{PREV_INSN} to find
1.1.1.8 ! root 7138: the preceding insns (but be careful to skip over any @code{note} insns that
1.1 root 7139: intervene).@refill
7140:
7141: When optimizing computations with intermediate results, you can use
7142: @var{condition} to match only when the intermediate results are not used
7143: elsewhere. Use the C expression @code{dead_or_set_p (@var{insn},
7144: @var{op})}, where @var{insn} is the insn in which you expect the value to
7145: be used for the last time (from the value of @code{insn}, together with use
7146: of @code{PREV_INSN}), and @var{op} is the intermediate value (from
7147: @code{operands[@var{i}]}).@refill
7148:
1.1.1.5 root 7149: Applying the optimization means replacing the sequence of insns with one
7150: new insn. The @var{template} controls ultimate output of assembler code
7151: for this combined insn. It works exactly like the template of a
7152: @code{define_insn}. Operand numbers in this template are the same ones
7153: used in matching the original sequence of insns.
1.1 root 7154:
7155: The result of a defined peephole optimizer does not need to match any of
1.1.1.5 root 7156: the insn patterns in the machine description; it does not even have an
7157: opportunity to match them. The peephole optimizer definition itself serves
7158: as the insn pattern to control how the insn is output.
7159:
7160: Defined peephole optimizers are run as assembler code is being output,
7161: so the insns they produce are never combined or rearranged in any way.
1.1 root 7162:
7163: Here is an example, taken from the 68000 machine description:
7164:
7165: @example
7166: (define_peephole
7167: [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
7168: (set (match_operand:DF 0 "register_operand" "f")
7169: (match_operand:DF 1 "register_operand" "ad"))]
7170: "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
7171: "*
7172: @{
7173: rtx xoperands[2];
7174: xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1);
7175: #ifdef MOTOROLA
7176: output_asm_insn (\"move.l %1,(sp)\", xoperands);
7177: output_asm_insn (\"move.l %1,-(sp)\", operands);
7178: return \"fmove.d (sp)+,%0\";
7179: #else
7180: output_asm_insn (\"movel %1,sp@@\", xoperands);
7181: output_asm_insn (\"movel %1,sp@@-\", operands);
7182: return \"fmoved sp@@+,%0\";
7183: #endif
7184: @}
7185: ")
7186: @end example
7187:
7188: The effect of this optimization is to change
7189:
7190: @example
7191: jbsr _foobar
7192: addql #4,sp
7193: movel d1,sp@@-
7194: movel d0,sp@@-
7195: fmoved sp@@+,fp0
7196: @end example
7197:
7198: @noindent
7199: into
7200:
7201: @example
7202: jbsr _foobar
7203: movel d1,sp@@
7204: movel d0,sp@@-
7205: fmoved sp@@+,fp0
7206: @end example
7207:
1.1.1.5 root 7208: @ignore
7209: If a peephole matches a sequence including one or more jump insns, you must
7210: take account of the flags such as @code{CC_REVERSED} which specify that the
7211: condition codes are represented in an unusual manner. The compiler
7212: automatically alters any ordinary conditional jumps which occur in such
7213: situations, but the compiler cannot alter jumps which have been replaced by
7214: peephole optimizations. So it is up to you to alter the assembler code
7215: that the peephole produces. Supply C code to write the assembler output,
7216: and in this C code check the condition code status flags and change the
7217: assembler code as appropriate.
7218: @end ignore
7219:
1.1.1.8 ! root 7220: @var{insn-pattern-1} and so on look @emph{almost} like the second
! 7221: operand of @code{define_insn}. There is one important difference: the
! 7222: second operand of @code{define_insn} consists of one or more RTX's
! 7223: enclosed in square brackets. Usually, there is only one: then the same
! 7224: action can be written as an element of a @code{define_peephole}. But
! 7225: when there are multiple actions in a @code{define_insn}, they are
! 7226: implicitly enclosed in a @code{parallel}. Then you must explicitly
! 7227: write the @code{parallel}, and the square brackets within it, in the
! 7228: @code{define_peephole}. Thus, if an insn pattern looks like this,
! 7229:
! 7230: @example
! 7231: (define_insn "divmodsi4"
! 7232: [(set (match_operand:SI 0 "general_operand" "=d")
! 7233: (div:SI (match_operand:SI 1 "general_operand" "0")
! 7234: (match_operand:SI 2 "general_operand" "dmsK")))
! 7235: (set (match_operand:SI 3 "general_operand" "=d")
! 7236: (mod:SI (match_dup 1) (match_dup 2)))]
! 7237: "TARGET_68020"
! 7238: "divsl%.l %2,%3:%0")
! 7239: @end example
! 7240:
! 7241: @noindent
! 7242: then the way to mention this insn in a peephole is as follows:
! 7243:
! 7244: @example
! 7245: (define_peephole
! 7246: [@dots{}
! 7247: (parallel
! 7248: [(set (match_operand:SI 0 "general_operand" "=d")
! 7249: (div:SI (match_operand:SI 1 "general_operand" "0")
! 7250: (match_operand:SI 2 "general_operand" "dmsK")))
! 7251: (set (match_operand:SI 3 "general_operand" "=d")
! 7252: (mod:SI (match_dup 1) (match_dup 2)))])
! 7253: @dots{}]
! 7254: @dots{})
! 7255: @end example
! 7256:
1.1 root 7257: @node Expander Definitions,, Peephole Definitions, Machine Desc
7258: @section Defining RTL Sequences for Code Generation
7259:
7260: On some target machines, some standard pattern names for RTL generation
7261: cannot be handled with single insn, but a sequence of RTL insns can
7262: represent them. For these target machines, you can write a
1.1.1.8 ! root 7263: @code{define_expand} to specify how to generate the sequence of RTL.
1.1 root 7264:
1.1.1.8 ! root 7265: A @code{define_expand} is an RTL expression that looks almost like a
! 7266: @code{define_insn}; but, unlike the latter, a @code{define_expand} is used
1.1 root 7267: only for RTL generation and it can produce more than one RTL insn.
7268:
1.1.1.8 ! root 7269: A @code{define_expand} RTX has four operands:
1.1 root 7270:
7271: @itemize @bullet
7272: @item
1.1.1.8 ! root 7273: The name. Each @code{define_expand} must have a name, since the only
1.1 root 7274: use for it is to refer to it by name.
7275:
7276: @item
7277: The RTL template. This is just like the RTL template for a
1.1.1.8 ! root 7278: @code{define_peephole} in that it is a vector of RTL expressions
1.1 root 7279: each being one insn.
7280:
7281: @item
7282: The condition, a string containing a C expression. This expression is
7283: used to express how the availability of this pattern depends on
7284: subclasses of target machine, selected by command-line options when
7285: GNU CC is run. This is just like the condition of a
1.1.1.8 ! root 7286: @code{define_insn} that has a standard name.
1.1 root 7287:
7288: @item
7289: The preparation statements, a string containing zero or more C
7290: statements which are to be executed before RTL code is generated from
7291: the RTL template.
7292:
7293: Usually these statements prepare temporary registers for use as
7294: internal operands in the RTL template, but they can also generate RTL
1.1.1.8 ! root 7295: insns directly by calling routines such as @code{emit_insn}, etc.
1.1 root 7296: Any such insns precede the ones that come from the RTL template.
7297: @end itemize
7298:
1.1.1.8 ! root 7299: Every RTL insn emitted by a @code{define_expand} must match some
! 7300: @code{define_insn} in the machine description. Otherwise, the compiler
! 7301: will crash when trying to generate code for the insn or trying to optimize
! 7302: it.
! 7303:
1.1 root 7304: The RTL template, in addition to controlling generation of RTL insns,
7305: also describes the operands that need to be specified when this pattern
7306: is used. In particular, it gives a predicate for each operand.
7307:
7308: A true operand, which need to be specified in order to generate RTL from
1.1.1.8 ! root 7309: the pattern, should be described with a @code{match_operand} in its first
1.1 root 7310: occurrence in the RTL template. This enters information on the operand's
7311: predicate into the tables that record such things. GNU CC uses the
7312: information to preload the operand into a register if that is required for
7313: valid RTL code. If the operand is referred to more than once, subsequent
1.1.1.8 ! root 7314: references should use @code{match_dup}.
1.1 root 7315:
7316: The RTL template may also refer to internal ``operands'' which are
7317: temporary registers or labels used only within the sequence made by the
1.1.1.8 ! root 7318: @code{define_expand}. Internal operands are substituted into the RTL
! 7319: template with @code{match_dup}, never with @code{match_operand}. The
1.1 root 7320: values of the internal operands are not passed in as arguments by the
7321: compiler when it requests use of this pattern. Instead, they are computed
7322: within the pattern, in the preparation statements. These statements
7323: compute the values and store them into the appropriate elements of
1.1.1.8 ! root 7324: @code{operands} so that @code{match_dup} can find them.
1.1 root 7325:
7326: There are two special macros defined for use in the preparation statements:
7327: @code{DONE} and @code{FAIL}. Use them with a following semicolon,
7328: as a statement.
7329:
7330: @table @code
7331: @item DONE
7332: Use the @code{DONE} macro to end RTL generation for the pattern. The
7333: only RTL insns resulting from the pattern on this occasion will be
7334: those already emitted by explicit calls to @code{emit_insn} within the
7335: preparation statements; the RTL template will not be generated.
7336:
7337: @item FAIL
7338: Make the pattern fail on this occasion. When a pattern fails, it means
7339: that the pattern was not truly available. The calling routines in the
7340: compiler will try other strategies for code generation using other patterns.
7341:
7342: Failure is currently supported only for binary operations (addition,
7343: multiplication, shifting, etc.).
7344:
7345: Do not emit any insns explicitly with @code{emit_insn} before failing.
7346: @end table
7347:
7348: Here is an example, the definition of left-shift for the SPUR chip:
7349:
7350: @example
7351: (define_expand "ashlsi3"
7352: [(set (match_operand:SI 0 "register_operand" "")
7353: (ashift:SI
7354: (match_operand:SI 1 "register_operand" "")
7355: (match_operand:SI 2 "nonmemory_operand" "")))]
7356: ""
7357: "
7358: @{
7359: if (GET_CODE (operands[2]) != CONST_INT
7360: || (unsigned) INTVAL (operands[2]) > 3)
7361: FAIL;
7362: @}")
7363: @end example
7364:
7365: @noindent
1.1.1.8 ! root 7366: This example uses @code{define_expand} so that it can generate an RTL insn
1.1 root 7367: for shifting when the shift-count is in the supported range of 0 to 3 but
7368: fail in other cases where machine insns aren't available. When it fails,
7369: the compiler tries another strategy using different patterns (such as, a
7370: library call).
7371:
7372: If the compiler were able to handle nontrivial condition-strings in
1.1.1.8 ! root 7373: patterns with names, then it would be possible to use a
! 7374: @code{define_insn} in that case. Here is another case (zero-extension
! 7375: on the 68000) which makes more use of the power of @code{define_expand}:
1.1 root 7376:
7377: @example
7378: (define_expand "zero_extendhisi2"
7379: [(set (match_operand:SI 0 "general_operand" "")
7380: (const_int 0))
7381: (set (strict_low_part
7382: (subreg:HI
1.1.1.8 ! root 7383: (match_dup 0)
1.1 root 7384: 0))
7385: (match_operand:HI 1 "general_operand" ""))]
7386: ""
7387: "operands[1] = make_safe_from (operands[1], operands[0]);")
7388: @end example
7389:
7390: @noindent
7391: Here two RTL insns are generated, one to clear the entire output operand
7392: and the other to copy the input operand into its low half. This sequence
7393: is incorrect if the input operand refers to [the old value of] the output
7394: operand, so the preparation statement makes sure this isn't so. The
7395: function @code{make_safe_from} copies the @code{operands[1]} into a
7396: temporary register if it refers to @code{operands[0]}. It does this
7397: by emitting another RTL insn.
7398:
7399: Finally, a third example shows the use of an internal operand.
1.1.1.8 ! root 7400: Zero-extension on the SPUR chip is done by @code{and}-ing the result
1.1 root 7401: against a halfword mask. But this mask cannot be represented by a
1.1.1.8 ! root 7402: @code{const_int} because the constant value is too large to be legitimate
1.1 root 7403: on this machine. So it must be copied into a register with
1.1.1.8 ! root 7404: @code{force_reg} and then the register used in the @code{and}.
1.1 root 7405:
7406: @example
7407: (define_expand "zero_extendhisi2"
7408: [(set (match_operand:SI 0 "register_operand" "")
7409: (and:SI (subreg:SI
7410: (match_operand:HI 1 "register_operand" "")
7411: 0)
7412: (match_dup 2)))]
7413: ""
7414: "operands[2]
7415: = force_reg (SImode, gen_rtx (CONST_INT,
7416: VOIDmode, 65535)); ")
7417: @end example
7418:
1.1.1.8 ! root 7419: @strong{Note:} If the @code{define_expand} is used to serve a standard
! 7420: binary or unary arithmetic operation, then the last insn it generates
! 7421: must not be a @code{code_label}, @code{barrier} or @code{note}. It must
! 7422: be an @code{insn}, @code{jump_insn} or @code{call_insn}.
! 7423:
1.1 root 7424: @node Machine Macros, Config, Machine Desc, Top
7425: @chapter Machine Description Macros
7426:
7427: The other half of the machine description is a C header file conventionally
7428: given the name @file{tm-@var{machine}.h}. The file @file{tm.h} should be a
7429: link to it. The header file @file{config.h} includes @file{tm.h} and most
7430: compiler source files include @file{config.h}.
7431:
7432: @menu
7433: * Run-time Target:: Defining -m options like -m68000 and -m68020.
7434: * Storage Layout:: Defining sizes and alignments of data types.
7435: * Registers:: Naming and describing the hardware registers.
7436: * Register Classes:: Defining the classes of hardware registers.
7437: * Stack Layout:: Defining which way the stack grows and by how much.
7438: * Library Names:: Specifying names of subroutines to call automatically.
7439: * Addressing Modes:: Defining addressing modes valid for memory operands.
1.1.1.8 ! root 7440: * Delayed Branch:: Do branches execute the following instruction?
1.1 root 7441: * Condition Code:: Defining how insns update the condition code.
7442: * Assembler Format:: Defining how to write insns and pseudo-ops to output.
1.1.1.5 root 7443: * Cross-compilation:: Handling floating point for cross-compilers.
1.1 root 7444: * Misc:: Everything else.
7445: @end menu
7446:
7447: @node Run-time Target, Storage Layout, Machine Macros, Machine Macros
7448: @section Run-time Target Specification
7449:
7450: @table @code
7451: @item CPP_PREDEFINES
7452: Define this to be a string constant containing @samp{-D} options to
7453: define the predefined macros that identify this machine and system.
7454: These macros will be predefined unless the @samp{-ansi} option is
7455: specified.
7456:
1.1.1.4 root 7457: In addition, a parallel set of macros are predefined, whose names are
7458: made by appending @samp{__} at the beginning and at the end. These
7459: @samp{__} macros are permitted by the ANSI standard, so they are
7460: predefined regardless of whether @samp{-ansi} is specified.
7461:
7462: For example, on the Sun, one can use the following value:
1.1 root 7463:
7464: @example
7465: "-Dmc68000 -Dsun -Dunix"
7466: @end example
7467:
1.1.1.8 ! root 7468: The result is to define the macros @code{__mc68000__}, @code{__sun__}
! 7469: and @code{__unix__} unconditionally, and the macros @code{mc68000},
! 7470: @code{sun} and @code{unix} provided @samp{-ansi} is not specified.
1.1.1.4 root 7471:
1.1 root 7472: @item CPP_SPEC
7473: A C string constant that tells the GNU CC driver program options to
7474: pass to CPP. It can also specify how to translate options you
7475: give to GNU CC into options for GNU CC to pass to the CPP.
7476:
7477: Do not define this macro if it does not need to do anything.
7478:
7479: @item CC1_SPEC
7480: A C string constant that tells the GNU CC driver program options to
7481: pass to CC1. It can also specify how to translate options you
7482: give to GNU CC into options for GNU CC to pass to the CC1.
7483:
7484: Do not define this macro if it does not need to do anything.
7485:
7486: @item extern int target_flags;
7487: This declaration should be present.
7488:
7489: @item TARGET_@dots{}
7490: This series of macros is to allow compiler command arguments to
7491: enable or disable the use of optional features of the target machine.
7492: For example, one machine description serves both the 68000 and
7493: the 68020; a command argument tells the compiler whether it should
7494: use 68020-only instructions or not. This command argument works
7495: by means of a macro @code{TARGET_68020} that tests a bit in
7496: @code{target_flags}.
7497:
7498: Define a macro @code{TARGET_@var{featurename}} for each such option.
7499: Its definition should test a bit in @code{target_flags}; for example:
7500:
7501: @example
7502: #define TARGET_68020 (target_flags & 1)
7503: @end example
7504:
7505: One place where these macros are used is in the condition-expressions
7506: of instruction patterns. Note how @code{TARGET_68020} appears
7507: frequently in the 68000 machine description file, @file{m68k.md}.
7508: Another place they are used is in the definitions of the other
7509: macros in the @file{tm-@var{machine}.h} file.
7510:
7511: @item TARGET_SWITCHES
7512: This macro defines names of command options to set and clear
7513: bits in @code{target_flags}. Its definition is an initializer
7514: with a subgrouping for each command option.
7515:
7516: Each subgrouping contains a string constant, that defines the option
7517: name, and a number, which contains the bits to set in
7518: @code{target_flags}. A negative number says to clear bits instead;
7519: the negative of the number is which bits to clear. The actual option
7520: name is made by appending @samp{-m} to the specified name.
7521:
7522: One of the subgroupings should have a null string. The number in
7523: this grouping is the default value for @code{target_flags}. Any
7524: target options act starting with that value.
7525:
7526: Here is an example which defines @samp{-m68000} and @samp{-m68020}
7527: with opposite meanings, and picks the latter as the default:
7528:
7529: @example
7530: #define TARGET_SWITCHES \
7531: @{ @{ "68020", 1@}, \
7532: @{ "68000", -1@}, \
7533: @{ "", 1@}@}
7534: @end example
7535:
7536: @item OVERRIDE_OPTIONS
7537: Sometimes certain combinations of command options do not make sense on
7538: a particular target machine. You can define a macro
7539: @code{OVERRIDE_OPTIONS} to take account of this. This macro, if
7540: defined, is executed once just after all the command options have been
7541: parsed.
7542: @end table
7543:
7544: @node Storage Layout, Registers, Run-time Target, Machine Macros
7545: @section Storage Layout
7546:
7547: Note that the definitions of the macros in this table which are sizes or
7548: alignments measured in bits do not need to be constant. They can be C
7549: expressions that refer to static variables, such as the @code{target_flags}.
7550: @xref{Run-time Target}.
7551:
7552: @table @code
7553: @item BITS_BIG_ENDIAN
7554: Define this macro if the most significant bit in a byte has the lowest
7555: number. This means that bit-field instructions count from the most
7556: significant bit. If the machine has no bit-field instructions, this
7557: macro is irrelevant.
7558:
1.1.1.8 ! root 7559: This macro does not affect the way structure fields are packed into
! 7560: bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}.
! 7561:
1.1 root 7562: @item BYTES_BIG_ENDIAN
7563: Define this macro if the most significant byte in a word has the
7564: lowest number.
7565:
7566: @item WORDS_BIG_ENDIAN
7567: Define this macro if, in a multiword object, the most significant
7568: word has the lowest number.
7569:
7570: @item BITS_PER_UNIT
7571: Number of bits in an addressable storage unit (byte); normally 8.
7572:
7573: @item BITS_PER_WORD
7574: Number of bits in a word; normally 32.
7575:
7576: @item UNITS_PER_WORD
7577: Number of storage units in a word; normally 4.
7578:
7579: @item POINTER_SIZE
7580: Width of a pointer, in bits.
7581:
7582: @item POINTER_BOUNDARY
7583: Alignment required for pointers stored in memory, in bits.
7584:
7585: @item PARM_BOUNDARY
1.1.1.7 root 7586: Normal alignment required for function parameters on the stack, in
7587: bits. All stack parameters receive least this much alignment
7588: regardless of data type. On most machines, this is the same as the
7589: size of an integer.
7590:
7591: @item MAX_PARM_BOUNDARY
7592: Largest alignment required for any stack parameters, in bits. If the
7593: data type of the parameter calls for more alignment than
7594: @code{PARM_BOUNDARY}, then it is given extra padding up to this limit.
7595:
7596: Don't define this macro if it would be equal to @code{PARM_BOUNDARY};
7597: in other words, if the alignment of a stack parameter should not
7598: depend on its data type (as is the case on most machines).
1.1 root 7599:
7600: @item STACK_BOUNDARY
7601: Define this macro if you wish to preserve a certain alignment for
7602: the stack pointer at all times. The definition is a C expression
7603: for the desired alignment (measured in bits).
7604:
7605: @item FUNCTION_BOUNDARY
7606: Alignment required for a function entry point, in bits.
7607:
7608: @item BIGGEST_ALIGNMENT
7609: Biggest alignment that any data type can require on this machine, in bits.
7610:
1.1.1.8 ! root 7611: @item CONSTANT_ALIGNMENT (@var{code}, @var{typealign})
! 7612: A C expression to compute the alignment for a constant. The argument
! 7613: @var{typealign} is the alignment required for the constant's data type.
! 7614: @var{code} is the tree code of the constant itself.
! 7615:
! 7616: If this macro is not defined, the default is to use @var{typealign}. If
! 7617: you do define this macro, the value must be a multiple of
! 7618: @var{typealign}.
! 7619:
! 7620: The purpose of defining this macro is usually to cause string constants
! 7621: to be word aligned so that @file{dhrystone} can be made to run faster.
! 7622:
1.1 root 7623: @item EMPTY_FIELD_BOUNDARY
7624: Alignment in bits to be given to a structure bit field that follows an
7625: empty field such as @code{int : 0;}.
7626:
7627: @item STRUCTURE_SIZE_BOUNDARY
7628: Number of bits which any structure or union's size must be a multiple of.
7629: Each structure or union's size is rounded up to a multiple of this.
7630:
7631: If you do not define this macro, the default is the same as
7632: @code{BITS_PER_UNIT}.
7633:
7634: @item STRICT_ALIGNMENT
7635: Define this if instructions will fail to work if given data not
7636: on the nominal alignment. If instructions will merely go slower
7637: in that case, do not define this macro.
7638:
7639: @item PCC_BITFIELD_TYPE_MATTERS
7640: Define this if you wish to imitate a certain bizarre behavior pattern
7641: of some instances of PCC: a bit field whose declared type is
7642: @code{int} has the same effect on the size and alignment of a
7643: structure as an actual @code{int} would have.
7644:
7645: Just what effect that is in GNU CC depends on other parameters, but on
7646: most machines it would force the structure's alignment and size to a
7647: multiple of 32 or @code{BIGGEST_ALIGNMENT} bits.
7648:
1.1.1.7 root 7649: @item MAX_FIXED_MODE_SIZE
7650: An integer expression for the largest integer machine mode that should
7651: actually be used. All integer machine modes of this size or smaller
7652: can be used for structures and unions with the appropriate sizes.
7653:
1.1 root 7654: @item CHECK_FLOAT_VALUE (@var{mode}, @var{value})
7655: A C statement to validate the value @var{value} (or type
7656: @code{double}) for mode @var{mode}. This means that you check whether
7657: @var{value} fits within the possible range of values for mode
7658: @var{mode} on this target machine. The mode @var{mode} is always
7659: @code{SFmode} or @code{DFmode}.
7660:
7661: If @var{value} is not valid, you should call @code{error} to print an
7662: error message and then assign some valid value to @var{value}.
7663: Allowing an invalid value to go through the compiler can produce
7664: incorrect assembler code which may even cause Unix assemblers to
7665: crash.
7666:
7667: This macro need not be defined if there is no work for it to do.
7668: @end table
7669:
7670: @node Registers, Register Classes, Storage Layout, Machine Macros
7671: @section Register Usage
7672:
7673: @table @code
7674: @item FIRST_PSEUDO_REGISTER
7675: Number of hardware registers known to the compiler. They receive
7676: numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
7677: pseudo register's number really is assigned the number
7678: @code{FIRST_PSEUDO_REGISTER}.
7679:
7680: @item FIXED_REGISTERS
7681: An initializer that says which registers are used for fixed purposes
7682: all throughout the compiled code and are therefore not available for
7683: general allocation. These would include the stack pointer, the frame
7684: pointer (except on machines where that can be used as a general
7685: register when no frame pointer is needed), the program counter on
7686: machines where that is considered one of the addressable registers,
7687: and any other numbered register with a standard use.
7688:
7689: This information is expressed as a sequence of numbers, separated by
7690: commas and surrounded by braces. The @var{n}th number is 1 if
7691: register @var{n} is fixed, 0 otherwise.
7692:
7693: The table initialized from this macro, and the table initialized by
7694: the following one, may be overridden at run time either automatically,
7695: by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
7696: the user with the command options @samp{-ffixed-@var{reg}},
7697: @samp{-fcall-used-@var{reg}} and @samp{-fcall-saved-@var{reg}}.
7698:
7699: @item CALL_USED_REGISTERS
7700: Like @code{FIXED_REGISTERS} but has 1 for each register that is
7701: clobbered (in general) by function calls as well as for fixed
7702: registers. This macro therefore identifies the registers that are not
7703: available for general allocation of values that must live across
7704: function calls.
7705:
7706: If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
7707: automatically saves it on function entry and restores it on function
7708: exit, if the register is used within the function.
7709:
1.1.1.6 root 7710: @item DEFAULT_CALLER_SAVES
1.1.1.8 ! root 7711: Define this macro if function calls on the target machine do not preserve
1.1.1.6 root 7712: any registers; in other words, if @code{CALL_USED_REGISTERS} has 1
7713: for all registers. This macro enables @samp{-fcaller-saves} by default.
7714: Eventually that option will be enabled by default on all machines and both
7715: the option and this macro will be eliminated.
7716:
1.1 root 7717: @item CONDITIONAL_REGISTER_USAGE
7718: Zero or more C statements that may conditionally modify two variables
7719: @code{fixed_regs} and @code{call_used_regs} (both of type @code{char
7720: []}) after they have been initialized from the two preceding macros.
7721:
7722: This is necessary in case the fixed or call-clobbered registers depend
7723: on target flags.
7724:
7725: You need not define this macro if it has no work to do.
7726:
7727: If the usage of an entire class of registers depends on the target
1.1.1.5 root 7728: flags, you may indicate this to GCC by using this macro to modify
1.1 root 7729: @code{fixed_regs} and @code{call_used_regs} to 1 for each of the
1.1.1.5 root 7730: registers in the classes which should not be used by GCC. Also define
1.1 root 7731: the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it
7732: is called with a letter for a class that shouldn't be used.
7733:
7734: (However, if this class is not included in @code{GENERAL_REGS} and all
7735: of the insn patterns whose constraints permit this class are
7736: controlled by target switches, then GCC will automatically avoid using
7737: these registers when the target switches are opposed to them.)
7738:
7739: @item OVERLAPPING_REGNO_P (@var{regno})
1.1.1.5 root 7740: If defined, this is a C expression whose value is nonzero if hard
7741: register number @var{regno} is an overlapping register. This means a
7742: hard register which overlaps a hard register with a different number.
7743: (Such overlap is undesirable, but occasionally it allows a machine to
7744: be supported which otherwise could not be.) This macro must return
7745: nonzero for @emph{all} the registers which overlap each other. GNU CC
7746: can use an overlapping register only in certain limited ways. It can
7747: be used for allocation within a basic block, and may be spilled for
7748: reloading; that is all.
1.1 root 7749:
7750: If this macro is not defined, it means that none of the hard registers
7751: overlap each other. This is the usual situation.
7752:
7753: @item INSN_CLOBBERS_REGNO_P (@var{insn}, @var{regno})
7754: If defined, this is a C expression whose value should be nonzero if
7755: the insn @var{insn} has the effect of mysteriously clobbering the
7756: contents of hard register number @var{regno}. By ``mysterious'' we
7757: mean that the insn's RTL expression doesn't describe such an effect.
7758:
7759: If this macro is not defined, it means that no insn clobbers registers
7760: mysteriously. This is the usual situation; all else being equal,
7761: it is best for the RTL expression to show all the activity.
7762:
7763: @item PRESERVE_DEATH_INFO_REGNO_P (@var{regno})
7764: If defined, this is a C expression whose value is nonzero if accurate
7765: @code{REG_DEAD} notes are needed for hard register number @var{regno}
7766: at the time of outputting the assembler code. When this is so, a few
7767: optimizations that take place after register allocation and could
7768: invalidate the death notes are not done when this register is
7769: involved.
7770:
1.1.1.8 ! root 7771: You would arrange to preserve death info for a register when some of the
! 7772: code in the machine description which is executed to write the assembler
! 7773: code looks at the death notes. This is necessary only when the actual
! 7774: hardware feature which GNU CC thinks of as a register is not actually a
! 7775: register of the usual sort. (It might, for example, be a hardware
! 7776: stack.)
1.1 root 7777:
7778: If this macro is not defined, it means that no death notes need to be
7779: preserved. This is the usual situation.
7780:
7781: @item HARD_REGNO_REGS (@var{regno}, @var{mode})
7782: A C expression for the number of consecutive hard registers, starting
7783: at register number @var{regno}, required to hold a value of mode
7784: @var{mode}.
7785:
7786: On a machine where all registers are exactly one word, a suitable
7787: definition of this macro is
7788:
7789: @example
7790: #define HARD_REGNO_NREGS(REGNO, MODE) \
7791: ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \
7792: / UNITS_PER_WORD))
7793: @end example
7794:
7795: @item HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
7796: A C expression that is nonzero if it is permissible to store a value
7797: of mode @var{mode} in hard register number @var{regno} (or in several
7798: registers starting with that one). For a machine where all registers
7799: are equivalent, a suitable definition is
7800:
7801: @example
7802: #define HARD_REGNO_MODE_OK(REGNO, MODE) 1
7803: @end example
7804:
1.1.1.8 ! root 7805: It is not necessary for this macro to check for the numbers of fixed
! 7806: registers, because the allocation mechanism considers them to be always
! 7807: occupied.
! 7808:
! 7809: On some machines, double-precision values must be kept in even/odd
! 7810: register pairs. The way to implement that is to define this macro
! 7811: to reject odd register numbers for such modes.
! 7812:
! 7813: GNU CC assumes that it can always move values between registers and
! 7814: (suitably addressed) memory locations. If it is impossible to move a
! 7815: value of a certain mode between memory and certain registers, then
! 7816: @code{HARD_REGNO_MODE_OK} must not allow this mode in those registers.
1.1 root 7817:
7818: Many machines have special registers for floating point arithmetic.
7819: Often people assume that floating point machine modes are allowed only
7820: in floating point registers. This is not true. Any registers that
7821: can hold integers can safely @emph{hold} a floating point machine
7822: mode, whether or not floating arithmetic can be done on it in those
7823: registers.
7824:
1.1.1.8 ! root 7825: The true significance of special floating registers is rather that
1.1 root 7826: non-floating-point machine modes @emph{may not} go in those registers.
7827: This is true if the floating registers normalize any value stored in
7828: them, because storing a non-floating value there would garble it. If
7829: the floating registers do not automatically normalize, if you can
7830: store any bit pattern in one and retrieve it unchanged without a trap,
7831: then any machine mode may go in a floating register and this macro
7832: should say so.
7833:
7834: Sometimes there are floating registers that are especially slow to
7835: access, so that it is better to store a value in a stack frame than in
7836: such a register if floating point arithmetic is not being done. As long
7837: as the floating registers are not in class @code{GENERAL_REGS}, they
7838: will not be used unless some insn's constraint asks for one.
7839:
7840: It is obligatory to support floating point `move' instructions into
7841: and out of any registers that can hold fixed point values, because
1.1.1.8 ! root 7842: unions and structures (which have modes @code{SImode} or
! 7843: @code{DImode}) can be in those registers and they may have floating
1.1 root 7844: point members.
7845:
7846: There may also be a need to support fixed point `move' instructions in
7847: and out of floating point registers. Unfortunately, I have forgotten
7848: why this was so, and I don't know whether it is still true. If
7849: @code{HARD_REGNO_MODE_OK} rejects fixed point values in floating point
7850: registers, then the constraints of the fixed point `move' instructions
7851: must be designed to avoid ever trying to reload into a floating point
7852: register.
7853:
7854: @item MODES_TIEABLE_P (@var{mode1}, @var{mode2})
7855: A C expression that is nonzero if it is desirable to choose register
7856: allocation so as to avoid move instructions between a value of mode
7857: @var{mode1} and a value of mode @var{mode2}.
7858:
7859: If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
7860: @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different
7861: for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1},
7862: @var{mode2})} must be zero.
7863:
7864: @item PC_REGNUM
7865: If the program counter has a register number, define this as that
7866: register number. Otherwise, do not define it.
7867:
7868: @item STACK_POINTER_REGNUM
7869: The register number of the stack pointer register, which must also be
7870: a fixed register according to @code{FIXED_REGISTERS}. On many
7871: machines, the hardware determines which register this is.
7872:
7873: @item FRAME_POINTER_REGNUM
7874: The register number of the frame pointer register, which is used to
7875: access automatic variables in the stack frame. On some machines, the
7876: hardware determines which register this is. On other machines, you
7877: can choose any register you wish for this purpose.
7878:
7879: @item FRAME_POINTER_REQUIRED
7880: A C expression which is nonzero if a function must have and use a
7881: frame pointer. This expression is evaluated in the reload pass, in
7882: the function @code{reload}, and it can in principle examine the
7883: current function and decide according to the facts, but on most
7884: machines the constant 0 or the constant 1 suffices. Use 0 when the
7885: machine allows code to be generated with no frame pointer, and doing
7886: so saves some time or space. Use 1 when there is no possible
7887: advantage to avoiding a frame pointer.
7888:
1.1.1.5 root 7889: In certain cases, the compiler does not know how to produce valid code
7890: without a frame pointer. The compiler recognizes those cases and
7891: automatically gives the function a frame pointer regardless of what
1.1 root 7892: @code{FRAME_POINTER_REQUIRED} says. You don't need to worry about
7893: them.@refill
7894:
7895: In a function that does not require a frame pointer, the frame pointer
7896: register can be allocated for ordinary usage, unless you mark it as a
7897: fixed register. See @code{FIXED_REGISTERS} for more information.
7898:
7899: @item ARG_POINTER_REGNUM
7900: The register number of the arg pointer register, which is used to
7901: access the function's argument list. On some machines, this is the
7902: same as the frame pointer register. On some machines, the hardware
7903: determines which register this is. On other machines, you can choose
7904: any register you wish for this purpose. If this is not the same
7905: register as the frame pointer register, then you must mark it as a
7906: fixed register according to @code{FIXED_REGISTERS}.
7907:
7908: @item STATIC_CHAIN_REGNUM
7909: The register number used for passing a function's static chain
7910: pointer. This is needed for languages such as Pascal and Algol where
7911: functions defined within other functions can access the local
7912: variables of the outer functions; it is not currently used because C
7913: does not provide this feature, but you must define the macro.
7914:
7915: The static chain register need not be a fixed register.
7916:
7917: @item STRUCT_VALUE_REGNUM
7918: When a function's value's mode is @code{BLKmode}, the value is not
7919: returned according to @code{FUNCTION_VALUE}. Instead, the caller
7920: passes the address of a block of memory in which the value should be
7921: stored.
7922:
7923: If this value is passed in a register, then @code{STRUCT_VALUE_REGNUM}
7924: should be the number of that register.
7925:
7926: @item STRUCT_VALUE
7927: If the structure value address is not passed in a register, define
7928: @code{STRUCT_VALUE} as an expression returning an RTX for the place
1.1.1.8 ! root 7929: where the address is passed. If it returns a @code{mem} RTX, the
1.1 root 7930: address is passed as an ``invisible'' first argument.
7931:
7932: @item STRUCT_VALUE_INCOMING_REGNUM
7933: On some architectures the place where the structure value address
7934: is found by the called function is not the same place that the
7935: caller put it. This can be due to register windows, or it could
7936: be because the function prologue moves it to a different place.
7937:
7938: If the incoming location of the structure value address is in a
7939: register, define this macro as the register number.
7940:
7941: @item STRUCT_VALUE_INCOMING
7942: If the incoming location is not a register, define
7943: @code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the
7944: called function should find the value. If it should find the value on
1.1.1.8 ! root 7945: the stack, define this to create a @code{mem} which refers to the
! 7946: frame pointer. If the value is a @code{mem}, the compiler assumes it
1.1 root 7947: is for an invisible first argument, and leaves space for it when
7948: finding the first real argument.
7949:
7950: @item REG_ALLOC_ORDER
7951: If defined, an initializer for a vector of integers, containing the
7952: numbers of hard registers in the order in which the GNU CC should
7953: prefer to use them (from most preferred to least).
7954:
7955: If this macro is not defined, registers are used lowest numbered first
7956: (all else being equal).
7957:
7958: One use of this macro is on the 360, where the highest numbered
7959: registers must always be saved and the save-multiple-registers
7960: instruction supports only sequences of consecutive registers. This
7961: macro is defined to cause the highest numbered allocatable registers
7962: to be used first.
7963: @end table
7964:
7965: @node Register Classes, Stack Layout, Registers, Machine Macros
7966: @section Register Classes
7967:
7968: On many machines, the numbered registers are not all equivalent.
7969: For example, certain registers may not be allowed for indexed addressing;
7970: certain registers may not be allowed in some instructions. These machine
7971: restrictions are described to the compiler using @dfn{register classes}.
7972:
7973: You define a number of register classes, giving each one a name and saying
7974: which of the registers belong to it. Then you can specify register classes
7975: that are allowed as operands to particular instruction patterns.
7976:
7977: In general, each register will belong to several classes. In fact, one
7978: class must be named @code{ALL_REGS} and contain all the registers. Another
7979: class must be named @code{NO_REGS} and contain no registers. Often the
7980: union of two classes will be another class; however, this is not required.
7981:
7982: One of the classes must be named @code{GENERAL_REGS}. There is nothing
7983: terribly special about the name, but the operand constraint letters
7984: @samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is
7985: the same as @code{ALL_REGS}, just define it as a macro which expands
7986: to @code{ALL_REGS}.
7987:
7988: The way classes other than @code{GENERAL_REGS} are specified in operand
7989: constraints is through machine-dependent operand constraint letters.
7990: You can define such letters to correspond to various classes, then use
7991: them in operand constraints.
7992:
7993: You should define a class for the union of two classes whenever some
7994: instruction allows both classes. For example, if an instruction allows
7995: either a floating-point (coprocessor) register or a general register for a
7996: certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
7997: which includes both of them. Otherwise you will get suboptimal code.
7998:
7999: You must also specify certain redundant information about the register
8000: classes: for each class, which classes contain it and which ones are
8001: contained in it; for each pair of classes, the largest class contained
8002: in their union.
8003:
1.1.1.8 ! root 8004: When a value occupying several consecutive registers is expected in a
! 8005: certain class, all the registers used must belong to that class.
! 8006: Therefore, register classes cannot be used to enforce a requirement for
! 8007: a register pair to start with an even-numbered register. The way to
! 8008: specify this requirement is with @code{HARD_REGNO_MODE_OK}.
! 8009:
1.1 root 8010: Register classes used for input-operands of bitwise-and or shift
8011: instructions have a special requirement: each such class must have, for
8012: each fixed-point machine mode, a subclass whose registers can transfer that
8013: mode to or from memory. For example, on some machines, the operations for
8014: single-byte values (@code{QImode}) are limited to certain registers. When
8015: this is so, each register class that is used in a bitwise-and or shift
8016: instruction must have a subclass consisting of registers from which
8017: single-byte values can be loaded or stored. This is so that
8018: @code{PREFERRED_RELOAD_CLASS} can always have a possible value to return.
8019:
8020: @table @code
8021: @item enum reg_class
8022: An enumeral type that must be defined with all the register class names
8023: as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS}
8024: must be the last register class, followed by one more enumeral value,
8025: @code{LIM_REG_CLASSES}, which is not a register class but rather
8026: tells how many classes there are.
8027:
8028: Each register class has a number, which is the value of casting
8029: the class name to type @code{int}. The number serves as an index
8030: in many of the tables described below.
8031:
8032: @item N_REG_CLASSES
8033: The number of distinct register classes, defined as follows:
8034:
8035: @example
8036: #define N_REG_CLASSES (int) LIM_REG_CLASSES
8037: @end example
8038:
8039: @item REG_CLASS_NAMES
8040: An initializer containing the names of the register classes as C string
8041: constants. These names are used in writing some of the debugging dumps.
8042:
8043: @item REG_CLASS_CONTENTS
8044: An initializer containing the contents of the register classes, as integers
8045: which are bit masks. The @var{n}th integer specifies the contents of class
8046: @var{n}. The way the integer @var{mask} is interpreted is that
8047: register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
8048:
8049: When the machine has more than 32 registers, an integer does not suffice.
8050: Then the integers are replaced by sub-initializers, braced groupings containing
8051: several integers. Each sub-initializer must be suitable as an initializer
8052: for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
8053:
8054: @item REGNO_REG_CLASS (@var{regno})
8055: A C expression whose value is a register class containing hard register
8056: @var{regno}. In general there is more that one such class; choose a class
8057: which is @dfn{minimal}, meaning that no smaller class also contains the
8058: register.
8059:
8060: @item BASE_REG_CLASS
8061: A macro whose definition is the name of the class to which a valid
8062: base register must belong. A base register is one used in an address
8063: which is the register value plus a displacement.
8064:
8065: @item INDEX_REG_CLASS
8066: A macro whose definition is the name of the class to which a valid
8067: index register must belong. An index register is one used in an
8068: address where its value is either multiplied by a scale factor or
8069: added to another register (as well as added to a displacement).
8070:
8071: @item REG_CLASS_FROM_LETTER (@var{char})
8072: A C expression which defines the machine-dependent operand constraint
8073: letters for register classes. If @var{char} is such a letter, the
8074: value should be the register class corresponding to it. Otherwise,
8075: the value should be @code{NO_REGS}.
8076:
8077: @item REGNO_OK_FOR_BASE_P (@var{num})
8078: A C expression which is nonzero if register number @var{num} is
8079: suitable for use as a base register in operand addresses. It may be
8080: either a suitable hard register or a pseudo register that has been
8081: allocated such a hard register.
8082:
8083: @item REGNO_OK_FOR_INDEX_P (@var{num})
8084: A C expression which is nonzero if register number @var{num} is
8085: suitable for use as an index register in operand addresses. It may be
8086: either a suitable hard register or a pseudo register that has been
8087: allocated such a hard register.
8088:
8089: The difference between an index register and a base register is that
8090: the index register may be scaled. If an address involves the sum of
8091: two registers, neither one of them scaled, then either one may be
8092: labeled the ``base'' and the other the ``index''; but whichever
8093: labeling is used must fit the machine's constraints of which registers
8094: may serve in each capacity. The compiler will try both labelings,
8095: looking for one that is valid, and will reload one or both registers
8096: only if neither labeling works.
8097:
8098: @item PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
8099: A C expression that places additional restrictions on the register class
8100: to use when it is necessary to copy value @var{x} into a register in class
8101: @var{class}. The value is a register class; perhaps @var{class}, or perhaps
8102: another, smaller class. On many machines, the definition
8103:
8104: @example
8105: #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
8106: @end example
8107:
8108: @noindent
8109: is safe.
8110:
8111: Sometimes returning a more restrictive class makes better code. For
8112: example, on the 68000, when @var{x} is an integer constant that is in range
8113: for a @samp{moveq} instruction, the value of this macro is always
8114: @code{DATA_REGS} as long as @var{class} includes the data registers.
8115: Requiring a data register guarantees that a @samp{moveq} will be used.
8116:
1.1.1.8 ! root 8117: If @var{x} is a @code{const_double}, by returning @code{NO_REGS}
1.1 root 8118: you can force @var{x} into a memory constant. This is useful on
8119: certain machines where immediate floating values cannot be loaded into
8120: certain kinds of registers.
8121:
8122: In a shift instruction or a bitwise-and instruction, the mode of @var{x},
8123: the value being reloaded, may not be the same as the mode of the
8124: instruction's operand. (They will both be fixed-point modes, however.) In
8125: such a case, @var{class} may not be a safe value to return. @var{class} is
8126: certainly valid for the instruction, but it may not be valid for reloading
8127: @var{x}. This problem can occur on machines such as the 68000 and 80386
8128: where some registers can handle full-word values but cannot handle
8129: single-byte values.
8130:
8131: On such machines, this macro must examine the mode of @var{x} and return a
8132: subclass of @var{class} which can handle loads and stores of that mode. On
8133: the 68000, where address registers cannot handle @code{QImode}, if @var{x}
8134: has @code{QImode} then you must return @code{DATA_REGS}. If @var{class} is
8135: @code{ADDR_REGS}, then there is no correct value to return; but the shift
8136: and bitwise-and instructions don't use @code{ADDR_REGS}, so this fatal case
8137: never arises.
8138:
8139: @item CLASS_MAX_NREGS (@var{class}, @var{mode})
8140: A C expression for the maximum number of consecutive registers
8141: of class @var{class} needed to hold a value of mode @var{mode}.
8142:
8143: This is closely related to the macro @code{HARD_REGNO_NREGS}.
8144: In fact, the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
8145: should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, @var{mode})}
8146: for all @var{regno} values in the class @var{class}.
8147:
8148: This macro helps control the handling of multiple-word values
8149: in the reload pass.
8150: @end table
8151:
8152: Two other special macros describe which constants fit which constraint
8153: letters.
8154:
8155: @table @code
8156: @item CONST_OK_FOR_LETTER_P (@var{value}, @var{c})
8157: A C expression that defines the machine-dependent operand constraint letters
8158: that specify particular ranges of integer values. If @var{c} is one
8159: of those letters, the expression should check that @var{value}, an integer,
8160: is in the appropriate range and return 1 if so, 0 otherwise. If @var{c} is
8161: not one of those letters, the value should be 0 regardless of @var{value}.
8162:
8163: @item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c})
8164: A C expression that defines the machine-dependent operand constraint
8165: letters that specify particular ranges of floating values. If @var{c} is
8166: one of those letters, the expression should check that @var{value}, an RTX
1.1.1.8 ! root 8167: of code @code{const_double}, is in the appropriate range and return 1 if
1.1 root 8168: so, 0 otherwise. If @var{c} is not one of those letters, the value should
8169: be 0 regardless of @var{value}.
8170: @end table
8171:
8172: @node Stack Layout, Library Names, Register Classes, Machine Macros
8173: @section Describing Stack Layout
8174:
8175: @table @code
8176: @item STACK_GROWS_DOWNWARD
8177: Define this macro if pushing a word onto the stack moves the stack
8178: pointer to a smaller address.
8179:
8180: When we say, ``define this macro if @dots{},'' it means that the
8181: compiler checks this macro only with @code{#ifdef} so the precise
8182: definition used does not matter.
8183:
8184: @item FRAME_GROWS_DOWNWARD
8185: Define this macro if the addresses of local variable slots are at negative
8186: offsets from the frame pointer.
8187:
8188: @item STARTING_FRAME_OFFSET
8189: Offset from the frame pointer to the first local variable slot to be allocated.
8190:
8191: If @code{FRAME_GROWS_DOWNWARD}, the next slot's offset is found by
8192: subtracting the length of the first slot from @code{STARTING_FRAME_OFFSET}.
8193: Otherwise, it is found by adding the length of the first slot to
8194: the value @code{STARTING_FRAME_OFFSET}.
8195:
8196: @item PUSH_ROUNDING (@var{npushed})
8197: A C expression that is the number of bytes actually pushed onto the
8198: stack when an instruction attempts to push @var{npushed} bytes.
8199:
8200: If the target machine does not have a push instruction, do not define
8201: this macro. That directs GNU CC to use an alternate strategy: to
8202: allocate the entire argument block and then store the arguments into
8203: it.
8204:
8205: On some machines, the definition
8206:
8207: @example
8208: #define PUSH_ROUNDING(BYTES) (BYTES)
8209: @end example
8210:
8211: @noindent
8212: will suffice. But on other machines, instructions that appear
8213: to push one byte actually push two bytes in an attempt to maintain
8214: alignment. Then the definition should be
8215:
8216: @example
8217: #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
8218: @end example
8219:
8220: @item FIRST_PARM_OFFSET (@var{fundecl})
8221: Offset from the argument pointer register to the first argument's
8222: address. On some machines it may depend on the data type of the
8223: function. (In the next version of GNU CC, the argument will be
8224: changed to the function data type rather than its declaration.)
8225:
8226: @item FIRST_PARM_CALLER_OFFSET (@var{fundecl})
8227: Define this macro on machines where register parameters have shadow
8228: locations on the stack, at addresses below the nominal parameter.
8229: This matters because certain arguments cannot be passed on the stack.
8230: On these machines, such arguments must be stored into the shadow
8231: locations.
8232:
8233: This macro should expand into a C expression whose value is the offset
8234: of the first parameter's shadow location from the nominal stack
8235: pointer value. (That value is itself computed by adding the value of
8236: @code{STACK_POINTER_OFFSET} to the stack pointer register.)
8237:
1.1.1.6 root 8238: @item STACK_ARGS_ADJUST (@var{size})
8239: Define this macro if the machine requires padding on the stack for
8240: certain function calls. This is padding on a per-function-call basis,
8241: not padding for individual arguments.
8242:
1.1.1.7 root 8243: The argument @var{size} will be a C variable of type @code{struct
8244: arg_data} which contains two fields, an integer named @code{constant}
8245: and an RTX named @code{var}. These together represent a size measured
8246: in bytes which is the sum of the integer and the RTX. Most of the
8247: time @code{var} is 0, which means that the size is simply the integer.
8248:
8249: The definition should be a C statement or compound statement
8250: which alters the variable supplied in whatever way you wish.
8251:
8252: Note that the value you leave in the variable @code{size} will
8253: ultimately be rounded up to a multiple of @code{STACK_BOUNDARY} bits.
8254:
8255: This macro is not fully implemented for machines which have push
8256: instructions (i.e., on which @code{PUSH_ROUNDING} is defined).
1.1.1.6 root 8257:
1.1 root 8258: @item RETURN_POPS_ARGS (@var{funtype})
8259: A C expression that should be 1 if a function pops its own arguments
8260: on returning, or 0 if the function pops no arguments and the caller
8261: must therefore pop them all after the function returns.
8262:
8263: @var{funtype} is a C variable whose value is a tree node that
8264: describes the function in question. Normally it is a node of type
8265: @code{FUNCTION_TYPE} that describes the data type of the function.
8266: From this it is possible to obtain the data types of the value and
8267: arguments (if known).
8268:
8269: When a call to a library function is being considered, @var{funtype}
8270: will contain an identifier node for the library function. Thus, if
8271: you need to distinguish among various library functions, you can do so
8272: by their names. Note that ``library function'' in this context means
8273: a function used to perform arithmetic, whose name is known specially
8274: in the compiler and was not mentioned in the C code being compiled.
8275:
8276: On the Vax, all functions always pop their arguments, so the
8277: definition of this macro is 1. On the 68000, using the standard
8278: calling convention, no functions pop their arguments, so the value of
8279: the macro is always 0 in this case. But an alternative calling
8280: convention is available in which functions that take a fixed number of
8281: arguments pop them but other functions (such as @code{printf}) pop
8282: nothing (the caller pops all). When this convention is in use,
8283: @var{funtype} is examined to determine whether a function takes a
8284: fixed number of arguments.
8285:
8286: @item FUNCTION_VALUE (@var{valtype}, @var{func})
8287: A C expression to create an RTX representing the place where a
8288: function returns a value of data type @var{valtype}. @var{valtype} is
8289: a tree node representing a data type. Write @code{TYPE_MODE
8290: (@var{valtype})} to get the machine mode used to represent that type.
8291: On many machines, only the mode is relevant. (Actually, on most
8292: machines, scalar values are returned in the same place regardless of
8293: mode).@refill
8294:
8295: If the precise function being called is known, @var{func} is a tree
8296: node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
8297: pointer. This makes it possible to use a different value-returning
8298: convention for specific functions when all their calls are
8299: known.@refill
8300:
8301: @item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func})
8302: Define this macro if the target machine has ``register windows''
8303: so that the register in which a function returns its value is not
8304: the same as the one in which the caller sees the value.
8305:
8306: For such machines, @code{FUNCTION_VALUE} computes the register in
8307: which the caller will see the value, and
8308: @code{FUNCTION_OUTGOING_VALUE} should be defined in a similar fashion
8309: to tell the function where to put the value.@refill
8310:
8311: If @code{FUNCTION_OUTGOING_VALUE} is not defined,
8312: @code{FUNCTION_VALUE} serves both purposes.@refill
8313:
1.1.1.7 root 8314: @item RETURN_IN_MEMORY (@var{type})
8315: A C expression which can inhibit the returning of certain function
8316: values in registers, based on the type of value. A nonzero value says
8317: to return the function value in memory, just as large structures are
8318: always returned. Here @var{type} will be a C expression of type
8319: @code{tree}, representing the data type of the value.
8320:
8321: Note that values of mode @code{BLKmode} are returned in memory
8322: regardless of this macro. Also, the option @samp{-fpcc-struct-return}
8323: takes effect regardless of this macro. On most systems, it is
8324: possible to leave the macro undefined; this causes a default
8325: definition to be used, whose value is the constant 0.
8326:
1.1 root 8327: @item LIBCALL_VALUE (@var{mode})
8328: A C expression to create an RTX representing the place where a library
8329: function returns a value of mode @var{mode}. If the precise function
8330: being called is known, @var{func} is a tree node
8331: (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
8332: pointer. This makes it possible to use a different value-returning
8333: convention for specific functions when all their calls are
8334: known.@refill
8335:
8336: Note that ``library function'' in this context means a compiler
8337: support routine, used to perform arithmetic, whose name is known
8338: specially by the compiler and was not mentioned in the C code being
8339: compiled.
8340:
8341: @item FUNCTION_VALUE_REGNO_P (@var{regno})
8342: A C expression that is nonzero if @var{regno} is the number of a hard
8343: register in which the values of called function may come back.
8344:
8345: A register whose use for returning values is limited to serving as the
8346: second of a pair (for a value of type @code{double}, say) need not be
8347: recognized by this macro. So for most machines, this definition
8348: suffices:
8349:
8350: @example
8351: #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
8352: @end example
8353:
8354: If the machine has register windows, so that the caller and the called
8355: function use different registers for the return value, this macro
8356: should recognize only the caller's register numbers.
8357:
8358: @item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
8359: A C expression that controls whether a function argument is passed
8360: in a register, and which register.
8361:
8362: The arguments are @var{cum}, which summarizes all the previous
8363: arguments; @var{mode}, the machine mode of the argument; @var{type},
8364: the data type of the argument as a tree node or 0 if that is not known
8365: (which happens for C support library functions); and @var{named},
8366: which is 1 for an ordinary argument and 0 for nameless arguments that
1.1.1.8 ! root 8367: correspond to @samp{@dots{}} in the called function's prototype.
1.1 root 8368:
1.1.1.8 ! root 8369: The value of the expression should either be a @code{reg} RTX for the
1.1 root 8370: hard register in which to pass the argument, or zero to pass the
8371: argument on the stack.
8372:
8373: For the Vax and 68000, where normally all arguments are pushed, zero
8374: suffices as a definition.
8375:
1.1.1.8 ! root 8376: The usual way to make the ANSI library @file{stdarg.h} work on a machine
! 8377: where some arguments are usually passed in registers, is to cause
! 8378: nameless arguments to be passed on the stack instead. This is done
! 8379: by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0.
! 8380:
1.1 root 8381: @item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
8382: Define this macro if the target machine has ``register windows'', so
8383: that the register in which a function sees an arguments is not
8384: necessarily the same as the one in which the caller passed the
8385: argument.
8386:
8387: For such machines, @code{FUNCTION_ARG} computes the register in which
8388: the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should
8389: be defined in a similar fashion to tell the function being called
8390: where the arguments will arrive.
8391:
8392: If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG}
8393: serves both purposes.@refill
8394:
8395: @item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named})
8396: A C expression for the number of words, at the beginning of an
8397: argument, must be put in registers. The value must be zero for
8398: arguments that are passed entirely in registers or that are entirely
8399: pushed on the stack.
8400:
8401: On some machines, certain arguments must be passed partially in
8402: registers and partially in memory. On these machines, typically the
8403: first @var{n} words of arguments are passed in registers, and the rest
8404: on the stack. If a multi-word argument (a @code{double} or a
8405: structure) crosses that boundary, its first few words must be passed
8406: in registers and the rest must be pushed. This macro tells the
8407: compiler when this occurs, and how many of the words should go in
8408: registers.
8409:
8410: @code{FUNCTION_ARG} for these arguments should return the first
8411: register to be used by the caller for this argument; likewise
8412: @code{FUNCTION_INCOMING_ARG}, for the called function.
8413:
8414: @item CUMULATIVE_ARGS
8415: A C type for declaring a variable that is used as the first argument
8416: of @code{FUNCTION_ARG} and other related values. For some target
8417: machines, the type @code{int} suffices and can hold the number of
8418: bytes of argument so far.
8419:
8420: @item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype})
8421: A C statement (sans semicolon) for initializing the variable @var{cum}
8422: for the state at the beginning of the argument list. The variable has
8423: type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node
8424: for the data type of the function which will receive the args, or 0
8425: if the args are to a compiler support library function.
8426:
8427: @item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named})
1.1.1.7 root 8428: A C statement (sans semicolon) to update the summarizer variable
8429: @var{cum} to advance past an argument in the argument list. The
8430: values @var{mode}, @var{type} and @var{named} describe that argument.
8431: Once this is done, the variable @var{cum} is suitable for analyzing
8432: the @emph{following} argument with @code{FUNCTION_ARG}, etc.@refill
1.1 root 8433:
8434: @item FUNCTION_ARG_REGNO_P (@var{regno})
8435: A C expression that is nonzero if @var{regno} is the number of a hard
8436: register in which function arguments are sometimes passed. This does
8437: @emph{not} include implicit arguments such as the static chain and
8438: the structure-value address. On many machines, no registers can be
8439: used for this purpose since all function arguments are pushed on the
8440: stack.
8441:
8442: @item FUNCTION_ARG_PADDING (@var{mode}, @var{size})
8443: If defined, a C expression which determines whether, and in which direction,
8444: to pad out an argument with extra space. The value should be of type
8445: @code{enum direction}: either @code{upward} to pad above the argument,
8446: @code{downward} to pad below, or @code{none} to inhibit padding.
8447:
8448: The argument @var{size} is an RTX which describes the size of the
8449: argument, in bytes. It should be used only if @var{mode} is
8450: @code{BLKmode}. Otherwise, @var{size} is 0.
8451:
8452: This macro does not control the @emph{amount} of padding; that is
8453: always just enough to reach the next multiple of @code{PARM_BOUNDARY}.
8454:
8455: This macro has a default definition which is right for most systems.
8456: For little-endian machines, the default is to pad upward. For
8457: big-endian machines, the default is to pad downward for an argument of
8458: constant size shorter than an @code{int}, and upward otherwise.
8459:
8460: @item FUNCTION_PROLOGUE (@var{file}, @var{size})
8461: A C compound statement that outputs the assembler code for entry to a
8462: function. The prologue is responsible for setting up the stack frame,
8463: initializing the frame pointer register, saving registers that must be
8464: saved, and allocating @var{size} additional bytes of storage for the
8465: local variables. @var{size} is an integer. @var{file} is a stdio
8466: stream to which the assembler code should be output.
8467:
8468: The label for the beginning of the function need not be output by this
8469: macro. That has already been done when the macro is run.
8470:
8471: To determine which registers to save, the macro can refer to the array
8472: @code{regs_ever_live}: element @var{r} is nonzero if hard register
8473: @var{r} is used anywhere within the function. This implies the
8474: function prologue should save register @var{r}, but not if it is one
8475: of the call-used registers.
8476:
8477: On machines where functions may or may not have frame-pointers, the
8478: function entry code must vary accordingly; it must set up the frame
8479: pointer if one is wanted, and not otherwise. To determine whether a
8480: frame pointer is in wanted, the macro can refer to the variable
8481: @code{frame_pointer_needed}. The variable's value will be 1 at run
8482: time in a function that needs a frame pointer.
8483:
1.1.1.8 ! root 8484: On machines where arguments may be passed in registers, and not have
! 8485: stack space allocated, this macro must examine the variable
! 8486: @code{current_function_pretend_args_size}, and allocate that many bytes
! 8487: of uninitialized space on the stack just underneath the first argument
! 8488: arriving on the stack. (This may not be at the very end of the stack,
! 8489: if the calling sequence has pushed anything else since pushing the stack
! 8490: arguments. But usually, on such machines, nothing else has been pushed
! 8491: yet, because the function prologue itself does all the pushing.)
! 8492:
! 8493: This ``pretend argument'' space is allocated in functions that use the
! 8494: ANSI library @file{stdarg.h} to accept anonymous arguments of
! 8495: unspecified types; the last named argument is copied into the space, so
! 8496: that the anonymous arguments follow it consecutively.
! 8497:
1.1 root 8498: @item FUNCTION_PROFILER (@var{file}, @var{labelno})
8499: A C statement or compound statement to output to @var{file} some
8500: assembler code to call the profiling subroutine @code{mcount}.
8501: Before calling, the assembler code must load the address of a
8502: counter variable into a register where @code{mcount} expects to
8503: find the address. The name of this variable is @samp{LP} followed
8504: by the number @var{labelno}, so you would generate the name using
8505: @samp{LP%d} in a @code{fprintf}.
8506:
8507: The details of how the address should be passed to @code{mcount} are
8508: determined by your operating system environment, not by GNU CC. To
8509: figure them out, compile a small program for profiling using the
8510: system's installed C compiler and look at the assembler code that
8511: results.
8512:
1.1.1.6 root 8513: @item FUNCTION_BLOCK_PROFILER (@var{file}, @var{labelno})
8514: A C statement or compound statement to output to @var{file} some
8515: assembler code to initialize basic-block profiling for the current
8516: object module. This code should call the subroutine
8517: @code{__bb_init_func} once per object module, passing it as its sole
8518: argument the address of a block allocated in the object module.
8519:
8520: The name of the block is a local symbol made with this statement:
8521:
8522: @example
8523: ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 0);
8524: @end example
8525:
8526: Of course, since you are writing the definition of
8527: @code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you
8528: can take a short cut in the definition of this macro and use the name
8529: that you know will result.
8530:
8531: The first word of this block is a flag which will be nonzero if the
8532: object module has already been initialized. So test this word first,
8533: and do not call @code{__bb_init_func} if the flag is nonzero.
8534:
8535: @item BLOCK_PROFILER (@var{file}, @var{blockno})
8536: A C statement or compound statement to increment the count associated
8537: with the basic block number @var{blockno}. Basic blocks are numbered
8538: separately from zero within each compilation. The count associated
8539: with block number @var{blockno} is at index @var{blockno} in a vector
8540: of words; the name of this array is a local symbol made with this
8541: statement:
8542:
8543: @example
8544: ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 2);
8545: @end example
8546:
8547: Of course, since you are writing the definition of
8548: @code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you
8549: can take a short cut in the definition of this macro and use the name
8550: that you know will result.
8551:
1.1 root 8552: @item EXIT_IGNORES_STACK
8553: Define this macro as a C expression that is nonzero if the return
8554: instruction or the function epilogue ignores the value of the stack
8555: pointer; in other words, if it is safe to delete an instruction to
8556: adjust the stack pointer before a return from the function.
8557:
1.1.1.8 ! root 8558: Note that this macro's value is relevant only for functions for which
! 8559: frame pointers are maintained. It is never safe to delete a final
! 8560: stack adjustment in a function that has no frame pointer, and the
! 8561: compiler knows this regardless of @code{EXIT_IGNORES_STACK}.
1.1 root 8562:
8563: @item FUNCTION_EPILOGUE (@var{file}, @var{size})
8564: A C compound statement that outputs the assembler code for exit from a
8565: function. The epilogue is responsible for restoring the saved
8566: registers and stack pointer to their values when the function was
8567: called, and returning control to the caller. This macro takes the
8568: same arguments as the macro @code{FUNCTION_PROLOGUE}, and the
8569: registers to restore are determined from @code{regs_ever_live} and
8570: @code{CALL_USED_REGISTERS} in the same way.
8571:
8572: On some machines, there is a single instruction that does all the work
8573: of returning from the function. On these machines, give that
8574: instruction the name @samp{return} and do not define the macro
8575: @code{FUNCTION_EPILOGUE} at all.
8576:
8577: Do not define a pattern named @samp{return} if you want the
8578: @code{FUNCTION_EPILOGUE} to be used. If you want the target switches
8579: to control whether return instructions or epilogues are used, define a
8580: @samp{return} pattern with a validity condition that tests the target
8581: switches appropriately. If the @samp{return} pattern's validity
8582: condition is false, epilogues will be used.
8583:
8584: On machines where functions may or may not have frame-pointers, the
8585: function exit code must vary accordingly. Sometimes the code for
8586: these two cases is completely different. To determine whether a frame
8587: pointer is in wanted, the macro can refer to the variable
8588: @code{frame_pointer_needed}. The variable's value will be 1 at run
8589: time in a function that needs a frame pointer.
8590:
8591: On some machines, some functions pop their arguments on exit while
8592: others leave that for the caller to do. For example, the 68020 when
8593: given @samp{-mrtd} pops arguments in functions that take a fixed
8594: number of arguments.
8595:
8596: Your definition of the macro @code{RETURN_POPS_ARGS} decides which
8597: functions pop their own arguments. @code{FUNCTION_EPILOGUE} needs to
8598: know what was decided. The variable @code{current_function_pops_args}
8599: is nonzero if the function should pop its own arguments. If so, use
8600: the variable @code{current_function_args_size} as the number of bytes
8601: to pop.
8602:
8603: @item FIX_FRAME_POINTER_ADDRESS (@var{addr}, @var{depth})
8604: A C compound statement to alter a memory address that uses the frame
8605: pointer register so that it uses the stack pointer register instead.
8606: This must be done in the instructions that load parameter values into
8607: registers, when the reload pass determines that a frame pointer is not
8608: necessary for the function. @var{addr} will be a C variable name, and
8609: the updated address should be stored in that variable. @var{depth}
8610: will be the current depth of stack temporaries (number of bytes of
8611: arguments currently pushed). The change in offset between a
8612: frame-pointer-relative address and a stack-pointer-relative address
8613: must include @var{depth}.
8614:
8615: Even if your machine description specifies there will always be a
8616: frame pointer in the frame pointer register, you must still define
8617: @code{FIX_FRAME_POINTER_ADDRESS}, but the definition will never be
8618: executed at run time, so it may be empty.
1.1.1.8 ! root 8619:
! 8620: @item LONGJMP_RESTORE_FROM_STACK
! 8621: Define this macro if the @code{longjmp} function restores registers
! 8622: from the stack frames, rather than from those saved specifically by
! 8623: @code{setjmp}. Certain quantities must not be kept in registers
! 8624: across a call to @code{setjmp} on such machines.
1.1 root 8625: @end table
8626:
8627: @node Library Names, Addressing Modes, Stack Layout, Machine Macros
8628: @section Library Subroutine Names
8629:
8630: @table @code
1.1.1.5 root 8631: @item MULSI3_LIBCALL
8632: A C string constant giving the name of the function to call for
8633: multiplication of one signed full-word by another. If you do not
8634: define this macro, the default name is used, which is @code{__mulsi3},
8635: a function defined in @file{gnulib}.
8636:
8637: @item UMULSI3_LIBCALL
8638: A C string constant giving the name of the function to call for
8639: multiplication of one unsigned full-word by another. If you do not
8640: define this macro, the default name is used, which is
8641: @code{__umulsi3}, a function defined in @file{gnulib}.
8642:
8643: @item DIVSI3_LIBCALL
8644: A C string constant giving the name of the function to call for
8645: division of one signed full-word by another. If you do not define
8646: this macro, the default name is used, which is @code{__divsi3}, a
8647: function defined in @file{gnulib}.
8648:
1.1 root 8649: @item UDIVSI3_LIBCALL
8650: A C string constant giving the name of the function to call for
1.1.1.5 root 8651: division of one unsigned full-word by another. If you do not define
8652: this macro, the default name is used, which is @code{__udivsi3}, a
8653: function defined in @file{gnulib}.
8654:
8655: @item MODSI3_LIBCALL
8656: A C string constant giving the name of the function to call for the
8657: remainder in division of one signed full-word by another. If you do
8658: not define this macro, the default name is used, which is
8659: @code{__modsi3}, a function defined in @file{gnulib}.
1.1 root 8660:
8661: @item UMODSI3_LIBCALL
8662: A C string constant giving the name of the function to call for the
1.1.1.5 root 8663: remainder in division of one unsigned full-word by another. If you do
8664: not define this macro, the default name is used, which is
8665: @code{__umodsi3}, a function defined in @file{gnulib}.
1.1 root 8666:
8667: @item TARGET_MEM_FUNCTIONS
8668: Define this macro if GNU CC should generate calls to the System V
8669: (and ANSI C) library functions @code{memcpy} and @code{memset}
8670: rather than the BSD functions @code{bcopy} and @code{bzero}.
8671: @end table
8672:
1.1.1.8 ! root 8673: @node Addressing Modes, Delayed Branch, Library Names, Machine Macros
1.1 root 8674: @section Addressing Modes
8675:
8676: @table @code
8677: @item HAVE_POST_INCREMENT
8678: Define this macro if the machine supports post-increment addressing.
8679:
8680: @item HAVE_PRE_INCREMENT
8681: @itemx HAVE_POST_DECREMENT
8682: @itemx HAVE_PRE_DECREMENT
8683: Similar for other kinds of addressing.
8684:
8685: @item CONSTANT_ADDRESS_P (@var{x})
8686: A C expression that is 1 if the RTX @var{x} is a constant whose value
8687: is an integer. This includes integers whose values are not explicitly
1.1.1.8 ! root 8688: known, such as @code{symbol_ref} and @code{label_ref} expressions and
! 8689: @code{const} arithmetic expressions.
1.1 root 8690:
8691: On most machines, this can be defined as @code{CONSTANT_P (@var{x})},
8692: but a few machines are more restrictive in which constant addresses
8693: are supported.
8694:
8695: @item MAX_REGS_PER_ADDRESS
8696: A number, the maximum number of registers that can appear in a valid
8697: memory address.
8698:
8699: @item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label})
8700: A C compound statement with a conditional @code{goto @var{label};}
8701: executed if @var{x} (an RTX) is a legitimate memory address on the
8702: target machine for a memory operand of mode @var{mode}.
8703:
8704: It usually pays to define several simpler macros to serve as
8705: subroutines for this one. Otherwise it may be too complicated to
8706: understand.
8707:
8708: This macro must exist in two variants: a strict variant and a
8709: non-strict one. The strict variant is used in the reload pass. It
8710: must be defined so that any pseudo-register that has not been
8711: allocated a hard register is considered a memory reference. In
8712: contexts where some kind of register is required, a pseudo-register
8713: with no hard register must be rejected.
8714:
8715: The non-strict variant is used in other passes. It must be defined to
8716: accept all pseudo-registers in every context where some kind of
8717: register is required.
8718:
8719: Compiler source files that want to use the strict variant of this
8720: macro define the macro @code{REG_OK_STRICT}. You should use an
8721: @code{#ifdef REG_OK_STRICT} conditional to define the strict variant
8722: in that case and the non-strict variant otherwise.
8723:
8724: Typically among the subroutines used to define
8725: @code{GO_IF_LEGITIMATE_ADDRESS} are subroutines to check for
8726: acceptable registers for various purposes (one for base registers, one
8727: for index registers, and so on). Then only these subroutine macros
8728: need have two variants; the higher levels of macros may be the same
8729: whether strict or not.@refill
8730:
1.1.1.8 ! root 8731: Normally, constant addresses which are the sum of a @code{symbol_ref}
! 8732: and an integer are stored inside a @code{const} RTX to mark them as
! 8733: constant. Therefore, there is no need to recognize such sums as
! 8734: legitimate addresses.
! 8735:
! 8736: Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant
! 8737: sums that are not marked with @code{const}. It assumes that a naked
! 8738: @code{plus} indicates indexing. If so, then you @emph{must} reject such
! 8739: naked constant sums as illegitimate addresses, so that none of them will
! 8740: be given to @code{PRINT_OPERAND_ADDRESS}.@refill
! 8741:
1.1 root 8742: @item REG_OK_FOR_BASE_P (@var{x})
1.1.1.5 root 8743: A C expression that is nonzero if @var{x} (assumed to be a @code{reg}
1.1 root 8744: RTX) is valid for use as a base register. For hard registers, it
8745: should always accept those which the hardware permits and reject the
8746: others. Whether the macro accepts or rejects pseudo registers must be
8747: controlled by @code{REG_OK_STRICT} as described above. This usually
8748: requires two variant definitions, of which @code{REG_OK_STRICT}
8749: controls the one actually used.
8750:
8751: @item REG_OK_FOR_INDEX_P (@var{x})
1.1.1.5 root 8752: A C expression that is nonzero if @var{x} (assumed to be a @code{reg}
1.1 root 8753: RTX) is valid for use as an index register.
8754:
8755: The difference between an index register and a base register is that
8756: the index register may be scaled. If an address involves the sum of
8757: two registers, neither one of them scaled, then either one may be
8758: labeled the ``base'' and the other the ``index''; but whichever
8759: labeling is used must fit the machine's constraints of which registers
8760: may serve in each capacity. The compiler will try both labelings,
8761: looking for one that is valid, and will reload one or both registers
8762: only if neither labeling works.
8763:
8764: @item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win})
8765: A C compound statement that attempts to replace @var{x} with a valid
8766: memory address for an operand of mode @var{mode}. @var{win} will be a
8767: C statement label elsewhere in the code; the macro definition may use
8768:
8769: @example
8770: GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win});
8771: @end example
8772:
8773: @noindent
8774: to avoid further processing if the address has become legitimate.
8775:
8776: @var{x} will always be the result of a call to @code{break_out_memory_refs},
8777: and @var{oldx} will be the operand that was given to that function to produce
8778: @var{x}.
8779:
8780: The code generated by this macro should not alter the substructure of
8781: @var{x}. If it transforms @var{x} into a more legitimate form, it
8782: should assign @var{x} (which will always be a C variable) a new value.
8783:
8784: It is not necessary for this macro to come up with a legitimate
8785: address. The compiler has standard ways of doing so in all cases. In
8786: fact, it is safe for this macro to do nothing. But often a
8787: machine-dependent strategy can generate better code.
8788:
8789: @item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label})
8790: A C statement or compound statement with a conditional @code{goto
8791: @var{label};} executed if memory address @var{x} (an RTX) can have
8792: different meanings depending on the machine mode of the memory
8793: reference it is used for.
8794:
8795: Autoincrement and autodecrement addresses typically have mode-dependent
8796: effects because the amount of the increment or decrement is the size
8797: of the operand being addressed. Some machines have other mode-dependent
8798: addresses. Many RISC machines have no mode-dependent addresses.
8799:
8800: You may assume that @var{addr} is a valid address for the machine.
8801:
8802: @item LEGITIMATE_CONSTANT_P (@var{x})
8803: A C expression that is nonzero if @var{x} is a legitimate constant for
8804: an immediate operand on the target machine. You can assume that
1.1.1.8 ! root 8805: either @var{x} is a @code{const_double} or it satisfies
1.1 root 8806: @code{CONSTANT_P}, so you need not check these things. In fact,
8807: @samp{1} is a suitable definition for this macro on machines where any
1.1.1.8 ! root 8808: @code{const_double} is valid and anything @code{CONSTANT_P} is valid.@refill
! 8809: @end table
! 8810:
! 8811: @node Delayed Branch, Condition Code, Addressing Modes, Machine Macros
! 8812: @section Parameters for Delayed Branch Optimization
! 8813:
! 8814: @table @code
! 8815: @item HAVE_DELAYED_BRANCH
! 8816: Define this macro if the target machine has delayed branches, that is,
! 8817: a branch does not take effect immediately, and the actual branch
! 8818: instruction may be followed by one or more instructions that will be
! 8819: issued before the PC is actually changed.
! 8820:
! 8821: If defined, this allows a special scheduling pass to be run after the
! 8822: second jump optimization to attempt to reorder instructions to exploit
! 8823: this. Defining this macro also requires the definition of certain
! 8824: other macros described below.
! 8825:
! 8826: @item DBR_SLOTS_AFTER (@var{insn})
! 8827: This macro must be defined if @code{HAVE_DELAYED_BRANCH} is defined.
! 8828: Its definition should be a C expression returning the number of
! 8829: available delay slots following the instruction(s) output by the
! 8830: pattern for @var{insn}. The definition of ``slot'' is
! 8831: machine-dependent, and may denote instructions, bytes, or whatever.
! 8832:
! 8833: @item DBR_INSN_SLOTS (@var{insn})
! 8834: This macro must be defined if @code{HAVE_DELAYED_BRANCH} is defined.
! 8835: It should be a C expression returning the number of slots (typically
! 8836: the number of machine instructions) consumed by @var{insn}.
! 8837:
! 8838: You may assume that @var{insn} is truly an insn, not a note, label,
! 8839: barrier, dispatch table, @code{use}, or @code{clobber}.
! 8840:
! 8841: @item DBR_INSN_ELIGIBLE_P (@var{insn}, @var{dinsn})
! 8842: A C expression whose value is non-zero if it is legitimate to put
! 8843: @var{insn} in the delay slot following @var{dinsn}.
! 8844:
! 8845: You do not need to take account of data flow considerations in the
! 8846: definition of this macro, because the delayed branch optimizer always
! 8847: does that. This macro is needed only when certain insns may not be
! 8848: placed in certain delay slots for reasons not evident from the RTL
! 8849: expressions themselves. If there are no such problems, you don't need
! 8850: to define this macro.
! 8851:
! 8852: You may assume that @var{insn} is truly an insn, not a note, label,
! 8853: barrier, dispatch table, @code{use}, or @code{clobber}. You may
! 8854: assume that @var{dinsn} is a jump insn with a delay slot.
! 8855:
! 8856: @item DBR_OUTPUT_SEQEND(@var{file})
! 8857: A C statement, to be executed after all slot-filler instructions have
! 8858: been output. If necessary, call @code{dbr_sequence_length} to
! 8859: determine the number of slots filled in a sequence (zero if not
! 8860: currently outputting a sequence), to decide how many no-ops to output,
! 8861: or whatever.
! 8862:
! 8863: Don't define this macro if it has nothing to do, but it is helpful in
! 8864: reading assembly output if the extent of the delay sequence is made
! 8865: explicit (e.g. with white space).
! 8866:
! 8867: Note that output routines for instructions with delay slots must be
! 8868: prepared to deal with not being output as part of a sequence (i.e.
! 8869: when the scheduling pass is not run, or when no slot fillers could be
! 8870: found.) The variable @code{final_sequence} is null when not
! 8871: processing a sequence, otherwise it contains the @code{sequence} rtx
! 8872: being output.
1.1 root 8873: @end table
8874:
1.1.1.8 ! root 8875: @node Condition Code, Misc, Delayed Branch, Machine Macros
! 8876: @section Condition Code Information
! 8877:
! 8878: The file @file{conditions.h} defines a variable @code{cc_status} to
! 8879: describe how the condition code was computed (in case the interpretation of
! 8880: the condition code depends on the instruction that it was set by). This
! 8881: variable contains the RTL expressions on which the condition code is
! 8882: currently based, and several standard flags.
! 8883:
! 8884: Sometimes additional machine-specific flags must be defined in the machine
! 8885: description header file. It can also add additional machine-specific
! 8886: information by defining @code{CC_STATUS_MDEP}.
! 8887:
! 8888: @table @code
! 8889: @item CC_STATUS_MDEP
! 8890: C code for a data type which is used for declaring the @code{mdep}
! 8891: component of @code{cc_status}. It defaults to @code{int}.
! 8892:
! 8893: @item CC_STATUS_MDEP_INIT
! 8894: A C expression for the initial value of the @code{mdep} field. It
! 8895: defaults to 0.
! 8896:
! 8897: @item NOTICE_UPDATE_CC (@var{exp}, @var{insn})
! 8898: A C compound statement to set the components of @code{cc_status}
! 8899: appropriately for an insn @var{insn} whose body is @var{exp}. It is
! 8900: this macro's responsibility to recognize insns that set the condition
! 8901: code as a byproduct of other activity as well as those that explicitly
! 8902: set @code{(cc0)}.
! 8903:
! 8904: If there are insn that do not set the condition code but do alter
! 8905: other machine registers, this macro must check to see whether they
! 8906: invalidate the expressions that the condition code is recorded as
! 8907: reflecting. For example, on the 68000, insns that store in address
! 8908: registers do not set the condition code, which means that usually
! 8909: @code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such
! 8910: insns. But suppose that the previous insn set the condition code
! 8911: based on location @samp{a4@@(102)} and the current insn stores a new
! 8912: value in @samp{a4}. Although the condition code is not changed by
! 8913: this, it will no longer be true that it reflects the contents of
! 8914: @samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter
! 8915: @code{cc_status} in this case to say that nothing is known about the
! 8916: condition code value.
! 8917:
! 8918: The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal
! 8919: with the results of peephole optimization: insns whose patterns are
! 8920: @code{parallel} RTXs containing various @code{reg}, @code{mem} or
! 8921: constants which are just the operands. The RTL structure of these
! 8922: insns is not sufficient to indicate what the insns actually do. What
! 8923: @code{NOTICE_UPDATE_CC} should do when it sees one is just to run
! 8924: @code{CC_STATUS_INIT}.
! 8925: @end table
! 8926:
! 8927: @node Cross-compilation, Misc, Condition Code, Machine Macros
1.1.1.5 root 8928: @section Cross Compilation and Floating-Point Format
8929:
8930: While all modern machines use 2's compliment representation for integers,
8931: there are a variety of representations for floating point numbers. This
8932: means that in a cross-compiler the representation of floating point numbers
8933: in the compiled program may be different from that used in the machine
8934: doing the compilation.
8935:
8936: Because different representation systems may offer different amounts of
8937: range and precision, the cross compiler cannot safely use the host
8938: machine's floating point arithmetic. Therefore, floating point constants
8939: must be represented in the target machine's format. This means that the
8940: cross compiler cannot use @code{atof} to parse a floating point constant;
8941: it must have its own special routine to use instead. Also, constant
8942: folding must emulate the target machine's arithmetic (or must not be done
8943: at all).
8944:
8945: The macros in the following table should be defined only if you are cross
8946: compiling between different floating point formats.
8947:
8948: Otherwise, don't define them. Then default definitions will be set up which
8949: use @code{double} as the data type, @code{==} to test for equality, etc.
8950:
8951: You don't need to worry about how many times you use an operand of any
8952: of these macros. The compiler never uses operands which have side effects.
8953:
8954: @table @code
8955: @item REAL_VALUE_TYPE
8956: A macro for the C data type to be used to hold a floating point value
8957: in the target machine's format. Typically this would be a
8958: @code{struct} containing an array of @code{int}.
8959:
8960: @item REAL_VALUES_EQUAL (@var{x}, @var{y})
8961: A macro for a C expression which compares for equality the two values,
8962: @var{x} and @var{y}, both of type @code{REAL_VALUE_TYPE}.
8963:
8964: @item REAL_VALUES_LESS (@var{x}, @var{y})
8965: A macro for a C expression which tests whether @var{x} is less than
8966: @var{y}, both values being of type @code{REAL_VALUE_TYPE} and
8967: interpreted as floating point numbers in the target machine's
8968: representation.
8969:
8970: @item REAL_VALUE_LDEXP (@var{x}, @var{scale})
8971: A macro for a C expression which performs the standard library
8972: function @code{ldexp}, but using the target machine's floating point
8973: representation. Both @var{x} and the value of the expression have
8974: type @code{REAL_VALUE_TYPE}. The second argument, @var{scale}, is an
8975: integer.
8976:
8977: @item REAL_VALUE_ATOF (@var{string})
8978: A macro for a C expression which converts @var{string}, an expression
8979: of type @code{char *}, into a floating point number in the target
8980: machine's representation. The value has type @code{REAL_VALUE_TYPE}.
8981: @end table
8982:
8983: Define the following additional macros if you want to make floating
8984: point constant folding work while cross compiling. If you don't
8985: define them, cross compilation is still possible, but constant folding
8986: will not happen for floating point values.
8987:
8988: @table @code
8989: @item REAL_ARITHMETIC (@var{output}, @var{code}, @var{x}, @var{y})
8990: A macro for a C statement which calculates an arithmetic operation of
8991: the two floating point values @var{x} and @var{y}, both of type
8992: @code{REAL_VALUE_TYPE} in the target machine's representation, to
8993: produce a result of the same type and representation which is stored
8994: in @var{output} (which will be a variable).
8995:
8996: The operation to be performed is specified by @var{code}, a tree code
8997: which will always be one of the following: @code{PLUS_EXPR},
8998: @code{MINUS_EXPR}, @code{MULT_EXPR}, @code{RDIV_EXPR},
8999: @code{MAX_EXPR}, @code{MIN_EXPR}.@refill
9000:
9001: The expansion of this macro is responsible for checking for overflow.
9002: If overflow happens, the macro expansion should execute the statement
9003: @code{return 0;}, which indicates the inability to perform the
9004: arithmetic operation requested.
9005:
9006: @item REAL_VALUE_NEGATE (@var{x})
9007: A macro for a C expression which returns the negative of the floating
9008: point value @var{x}. Both @var{x} and the value of the expression
9009: have type @code{REAL_VALUE_TYPE} and are in the target machine's
9010: floating point representation.
9011:
9012: There is no way for this macro to report overflow, since overflow
9013: can't happen in the negation operation.
9014:
9015: @item REAL_VALUE_TO_INT (@var{low}, @var{high}, @var{x})
9016: A macro for a C expression which converts a floating point value
9017: @var{x} into a double-precision integer which is then stored into
9018: @var{low} and @var{high}, two variables of type @var{int}.
9019:
9020: @item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high})
9021: A macro for a C expression which converts a double-precision integer
9022: found in @var{low} and @var{high}, two variables of type @var{int},
9023: into a floating point value which is then stored into @var{x}.
9024: @end table
9025:
1.1.1.8 ! root 9026: @node Misc, Assembler Format, Cross-compilation, Machine Macros
1.1 root 9027: @section Miscellaneous Parameters
9028:
9029: @table @code
9030: @item CASE_VECTOR_MODE
9031: An alias for a machine mode name. This is the machine mode that
9032: elements of a jump-table should have.
9033:
9034: @item CASE_VECTOR_PC_RELATIVE
9035: Define this macro if jump-tables should contain relative addresses.
9036:
9037: @item CASE_DROPS_THROUGH
9038: Define this if control falls through a @code{case} insn when the index
9039: value is out of range. This means the specified default-label is
9040: actually ignored by the @code{case} insn proper.
9041:
9042: @item IMPLICIT_FIX_EXPR
9043: An alias for a tree code that should be used by default for conversion
9044: of floating point values to fixed point. Normally,
9045: @code{FIX_ROUND_EXPR} is used.@refill
9046:
9047: @item FIXUNS_TRUNC_LIKE_FIX_TRUNC
9048: Define this macro if the same instructions that convert a floating
9049: point number to a signed fixed point number also convert validly to an
9050: unsigned one.
9051:
9052: @item EASY_DIV_EXPR
9053: An alias for a tree code that is the easiest kind of division to
9054: compile code for in the general case. It may be
9055: @code{TRUNC_DIV_EXPR}, @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or
9056: @code{ROUND_DIV_EXPR}. These four division operators differ in how
9057: they round the result to an integer. @code{EASY_DIV_EXPR} is used
9058: when it is permissible to use any of those kinds of division and the
9059: choice should be made on the basis of efficiency.@refill
9060:
9061: @item DEFAULT_SIGNED_CHAR
9062: An expression whose value is 1 or 0, according to whether the type
9063: @code{char} should be signed or unsigned by default. The user can
9064: always override this default with the options @samp{-fsigned-char}
9065: and @samp{-funsigned-char}.
9066:
9067: @item SCCS_DIRECTIVE
9068: Define this if the preprocessor should ignore @code{#sccs} directives
9069: and print no error message.
9070:
1.1.1.7 root 9071: @item HAVE_VPRINTF
9072: Define this if the library function @code{vprintf} is available on your
9073: system.
1.1 root 9074:
9075: @item MOVE_MAX
9076: The maximum number of bytes that a single instruction can move quickly
9077: from memory to memory.
9078:
9079: @item INT_TYPE_SIZE
9080: A C expression for the size in bits of the type @code{int} on the
1.1.1.8 ! root 9081: target machine. If you don't define this, the default is one word.
! 9082:
! 9083: @item SHORT_TYPE_SIZE
! 9084: A C expression for the size in bits of the type @code{short} on the
! 9085: target machine. If you don't define this, the default is half a word.
! 9086: (If this would be less than one storage unit, it is rounded up to one
! 9087: unit.)
! 9088:
! 9089: @item LONG_TYPE_SIZE
! 9090: A C expression for the size in bits of the type @code{long} on the
! 9091: target machine. If you don't define this, the default is one word.
! 9092:
! 9093: @item LONG_LONG_TYPE_SIZE
! 9094: A C expression for the size in bits of the type @code{long long} on the
! 9095: target machine. If you don't define this, the default is two
! 9096: words.
! 9097:
! 9098: @item CHAR_TYPE_SIZE
! 9099: A C expression for the size in bits of the type @code{char} on the
! 9100: target machine. If you don't define this, the default is one quarter
! 9101: of a word. (If this would be less than one storage unit, it is rounded up
! 9102: to one unit.)
! 9103:
! 9104: @item FLOAT_TYPE_SIZE
! 9105: A C expression for the size in bits of the type @code{float} on the
! 9106: target machine. If you don't define this, the default is one word.
! 9107:
! 9108: @item DOUBLE_TYPE_SIZE
! 9109: A C expression for the size in bits of the type @code{double} on the
! 9110: target machine. If you don't define this, the default is two
! 9111: words.
! 9112:
! 9113: @item LONG_DOUBLE_TYPE_SIZE
! 9114: A C expression for the size in bits of the type @code{long double} on
! 9115: the target machine. If you don't define this, the default is two
! 9116: words.
1.1 root 9117:
9118: @item SLOW_BYTE_ACCESS
9119: Define this macro as a C expression which is nonzero if accessing less
9120: than a word of memory (i.e. a @code{char} or a @code{short}) is slow
9121: (requires more than one instruction).
9122:
9123: @item SLOW_ZERO_EXTEND
9124: Define this macro if zero-extension (of a @code{char} or @code{short}
9125: to an @code{int}) can be done faster if the destination is a register
9126: that is known to be zero.
9127:
9128: If you define this macro, you must have instruction patterns that
9129: recognize RTL structures like this:
9130:
9131: @example
9132: (set (strict-low-part (subreg:QI (reg:SI @dots{}) 0)) @dots{})
9133: @end example
9134:
9135: @noindent
9136: and likewise for @code{HImode}.
9137:
9138: @item SHIFT_COUNT_TRUNCATED
9139: Define this macro if shift instructions ignore all but the lowest few
9140: bits of the shift count. It implies that a sign-extend or zero-extend
9141: instruction for the shift count can be omitted.
9142:
9143: @item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec})
9144: A C expression which is nonzero if on this machine it is safe to
9145: ``convert'' an integer of @var{inprec} bits to one of @var{outprec}
9146: bits (where @var{outprec} is smaller than @var{inprec}) by merely
9147: operating on it as if it had only @var{outprec} bits.
9148:
9149: On many machines, this expression can be 1.
9150:
9151: @item NO_FUNCTION_CSE
9152: Define this macro if it is as good or better to call a constant
9153: function address than to call an address kept in a register.
9154:
9155: @item PROMOTE_PROTOTYPES
9156: Define this macro if an argument declared as @code{char} or
9157: @code{short} in a prototype should actually be passed as an
9158: @code{int}. In addition to avoiding errors in certain cases of
9159: mismatch, it also makes for better code on certain machines.
9160:
9161: @item STORE_FLAG_VALUE
9162: A C expression for the value stored by a store-flag instruction
9163: (@code{s@var{cond}}) when the condition is true. This is usually 1 or
9164: -1; it is required to be an odd number.
9165:
9166: Do not define @code{STORE_FLAG_VALUE} if the machine has no store-flag
9167: instructions.
9168:
9169: @item Pmode
9170: An alias for the machine mode for pointers. Normally the definition
9171: can be
9172:
9173: @example
9174: #define Pmode SImode
9175: @end example
9176:
9177: @item FUNCTION_MODE
9178: An alias for the machine mode used for memory references to functions
1.1.1.8 ! root 9179: being called, in @code{call} RTL expressions. On most machines this
1.1 root 9180: should be @code{QImode}.
9181:
9182: @item INSN_MACHINE_INFO
9183: This macro should expand into a C structure type to use for the
9184: machine-dependent info field specified with the optional last argument
1.1.1.8 ! root 9185: in @code{define_insn} and @code{define_peephole} patterns. For example,
! 9186: it might expand into @code{struct machine_info}; then it would be up
1.1 root 9187: to you to define this structure in the @file{tm.h} file.
9188:
9189: You do not need to define this macro if you do not write the optional
9190: last argument in any of the patterns in the machine description.
9191:
1.1.1.8 ! root 9192: @item DEFAULT_MACHINE_INFO
! 9193: This macro should expand into a C initializer to use to initialize
! 9194: the machine-dependent info for one insn pattern. It is used for patterns
! 9195: that do not specify the machine-dependent info.
! 9196:
! 9197: If you do not define this macro, zero is used.
! 9198:
1.1 root 9199: @item CONST_COSTS (@var{x}, @var{code})
9200: A part of a C @code{switch} statement that describes the relative
9201: costs of constant RTL expressions. It must contain @code{case} labels
1.1.1.8 ! root 9202: for expression codes @code{const_int}, @code{const}, @code{symbol_ref}, @code{label_ref}
! 9203: and @code{const_double}. Each case must ultimately reach a
1.1 root 9204: @code{return} statement to return the relative cost of the use of that
9205: kind of constant value in an expression. The cost may depend on the
9206: precise value of the constant, which is available for examination in
9207: @var{x}.
9208:
9209: @var{code} is the expression code---redundant, since it can be
9210: obtained with @code{GET_CODE (@var{x})}.
9211:
9212: @item DOLLARS_IN_IDENTIFIERS
9213: Define this to be nonzero if the character @samp{$} should be allowed
9214: by default in identifier names.
1.1.1.7 root 9215:
9216: @item USE_C_ALLOCA
9217: Define this macro to indicate that the compiler is running with the
9218: @code{alloca} implemented in C. This version of @code{alloca} can be
9219: found in the file @file{alloca.c}; to use it, you must also edit the
9220: @file{Makefile}.
9221:
9222: This macro, unlike most, describes the machine that the compiler is
9223: running on, rather than the one the compiler is compiling for.
9224: Therefore, it should be set in the @file{xm-@var{machine}.h} file
1.1.1.8 ! root 9225: rather than in the @file{tm-@var{machine}.h} file.
1.1.1.7 root 9226:
9227: If you do define this macro, you should probably do it as follows:
9228:
9229: @example
9230: #ifndef __GNUC__
9231: #define USE_C_ALLOCA
9232: #else
1.1.1.8 ! root 9233: #define alloca __builtin_alloca
1.1.1.7 root 9234: #endif
9235: @end example
9236:
9237: @noindent
9238: so that when the compiler is compiled with GNU CC it uses the more
9239: efficient built-in @code{alloca} function.
1.1 root 9240: @end table
9241:
1.1.1.8 ! root 9242: @node Assembler Format,, Misc, Machine Macros
1.1 root 9243: @section Output of Assembler Code
9244:
9245: @table @code
9246: @item ASM_SPEC
9247: A C string constant that tells the GNU CC driver program options to
9248: pass to the assembler. It can also specify how to translate options
9249: you give to GNU CC into options for GNU CC to pass to the assembler.
9250: See the file @file{tm-sun3.h} for an example of this.
9251:
9252: Do not define this macro if it does not need to do anything.
9253:
9254: @item LINK_SPEC
9255: A C string constant that tells the GNU CC driver program options to
9256: pass to the linker. It can also specify how to translate options you
9257: give to GNU CC into options for GNU CC to pass to the linker.
9258:
9259: Do not define this macro if it does not need to do anything.
9260:
9261: @item LIB_SPEC
9262: Another C string constant used much like @code{LINK_SPEC}. The difference
9263: between the two is that @code{LIBS_SPEC} is used at the end of the
9264: command given to the linker.
9265:
9266: If this macro is not defined, a default is provided that
9267: loads the standard C library from the usual place. See @file{gcc.c}.
9268:
9269: @item STARTFILE_SPEC
9270: Another C string constant used much like @code{LINK_SPEC}. The
9271: difference between the two is that @code{STARTFILE_SPEC} is used at
9272: the very beginning of the command given to the linker.
9273:
9274: If this macro is not defined, a default is provided that loads the
9275: standard C startup file from the usual place. See @file{gcc.c}.
9276:
1.1.1.7 root 9277: @item STANDARD_EXEC_PREFIX
9278: Define this macro as a C string constant if you wish to override the
9279: standard choice of @file{/usr/local/lib/gcc-} as the default prefix to
9280: try when searching for the executable files of the compiler.
9281:
9282: The prefix specified by the @samp{-B} option, if any, is tried before
9283: the default prefix. After the default prefix, if the executable is
9284: not found that way, @file{/usr/lib/gcc-} is tried next; then the
9285: directories in your search path for shell commands are searched.
9286:
1.1.1.4 root 9287: @item STANDARD_STARTFILE_PREFIX
9288: Define this macro as a C string constant if you wish to override the
1.1.1.7 root 9289: standard choice of @file{/usr/local/lib/} as the default prefix to try
9290: when searching for startup files such as @file{crt0.o}.
9291:
9292: In this search, all the prefixes tried for executable files are tried
9293: first. Then comes the default startfile prefix specified by this
9294: macro, followed by the prefixes @file{/lib/} and @file{/usr/lib/} as
9295: last resorts.
1.1.1.4 root 9296:
1.1 root 9297: @item ASM_FILE_START (@var{stream})
9298: A C expression which outputs to the stdio stream @var{stream}
9299: some appropriate text to go at the start of an assembler file.
9300:
9301: Normally this macro is defined to output a line containing
9302: @samp{#NO_APP}, which is a comment that has no effect on most
9303: assemblers but tells the GNU assembler that it can save time by not
9304: checking for certain assembler constructs.
9305:
9306: On systems that use SDB, it is necessary to output certain commands;
9307: see @file{tm-attasm.h}.
9308:
1.1.1.8 ! root 9309: @item ASM_FILE_END (@var{stream})
! 9310: A C expression which outputs to the stdio stream @var{stream}
! 9311: some appropriate text to go at the end of an assembler file.
! 9312:
! 9313: If this macro is not defined, the default is to output nothing
! 9314: special at the end of the file. Most systems don't require any
! 9315: definition.
! 9316:
! 9317: On systems that use SDB, it is necessary to output certain commands;
! 9318: see @file{tm-attasm.h}.
! 9319:
! 9320: @item ASM_IDENTIFY_GCC (@var{file})
! 9321: A C statement to output assembler commands which will identify
! 9322: the object file as having been compiled with GNU CC (or another
! 9323: GNU compiler).
! 9324:
! 9325: If you don't define this macro, the string @samp{gcc_compiled.:}
! 9326: is output. This string is calculated to define a symbol which,
! 9327: on BSD systems, will never be defined for any other reason.
! 9328: GDB checks for the presence of this symbol when reading the
! 9329: symbol table of an executable.
! 9330:
! 9331: On non-BSD systems, you must arrange communication with GDB in
! 9332: some other fashion. If GDB is not used on your system, you can
! 9333: define this macro with an empty body.
! 9334:
1.1 root 9335: @item ASM_APP_ON
9336: A C string constant for text to be output before each @code{asm}
9337: statement or group of consecutive ones. Normally this is
9338: @code{"#APP"}, which is a comment that has no effect on most
9339: assemblers but tells the GNU assembler that it must check the lines
9340: that follow for all valid assembler constructs.
9341:
9342: @item ASM_APP_OFF
9343: A C string constant for text to be output after each @code{asm}
9344: statement or group of consecutive ones. Normally this is
9345: @code{"#NO_APP"}, which tells the GNU assembler to resume making the
9346: time-saving assumptions that are valid for ordinary compiler output.
9347:
9348: @item TEXT_SECTION_ASM_OP
9349: A C string constant for the assembler operation that should precede
9350: instructions and read-only data. Normally @code{".text"} is right.
9351:
9352: @item DATA_SECTION_ASM_OP
9353: A C string constant for the assembler operation to identify the
9354: following data as writable initialized data. Normally @code{".data"}
9355: is right.
9356:
1.1.1.8 ! root 9357: @item EXTRA_SECTIONS
! 9358: A list of names for sections other than the standard two, which are
! 9359: @code{in_text} and @code{in_data}. You need not define this macro
! 9360: on a system with no other sections (that GCC needs to use).
! 9361:
! 9362: @item EXTRA_SECTION_FUNCTIONS
! 9363: One or more functions to be defined in @file{varasm.c}. These
! 9364: functions should do jobs analogous to those of @code{text_section} and
! 9365: @code{data_section}, for your additional sections. Do not define this
! 9366: macro if you do not define @code{EXTRA_SECTIONS}.
! 9367:
! 9368: @item SELECT_SECTION (@var{exp})
! 9369: A C statement or statements to switch to the appropriate section for
! 9370: output of @var{exp}. You can assume that @var{exp} is either a
! 9371: @code{VAR_DECL} node or a constant of some sort. Select the section
! 9372: by calling @code{text_section} or one of the alternatives for other
! 9373: sections.
! 9374:
! 9375: Do not define this macro if you use only the standard two sections
! 9376: and put all read-only variables and constants in the text section.
! 9377:
! 9378: @item SELECT_RTX_SECTION (@var{mode}, @var{rtx})
! 9379: A C statement or statements to switch to the appropriate section for
! 9380: output of @var{rtx} in mode @var{mode}. You can assume that @var{rtx}
! 9381: is some kind of constant in RTL. The argument @var{mode} is redundant
! 9382: except in the case of a @code{const_int} rtx. Select the section by
! 9383: calling @code{text_section} or one of the alternatives for other
! 9384: sections.
! 9385:
! 9386: Do not define this macro if you use only the standard two sections and
! 9387: put all constants in the text section.
! 9388:
1.1 root 9389: @item REGISTER_NAMES
9390: A C initializer containing the assembler's names for the machine
9391: registers, each one as a C string constant. This is what translates
9392: register numbers in the compiler into assembler language.
9393:
9394: @item DBX_REGISTER_NUMBER (@var{regno})
9395: A C expression that returns the DBX register number for the compiler
9396: register number @var{regno}. In simple cases, the value of this
9397: expression may be @var{regno} itself. But sometimes there are some
9398: registers that the compiler knows about and DBX does not, or vice
9399: versa. In such cases, some register may need to have one number in
9400: the compiler and another for DBX.
9401:
9402: @item DBX_DEBUGGING_INFO
9403: Define this macro if GNU CC should produce debugging output for DBX
9404: in response to the @samp{-g} option.
9405:
9406: @item SDB_DEBUGGING_INFO
9407: Define this macro if GNU CC should produce debugging output for SDB
9408: in response to the @samp{-g} option.
9409:
9410: @item PUT_SDB_@var{op}
9411: Define these macros to override the assembler syntax for the special
9412: SDB assembler directives. See @file{sdbout.c} for a list of these
9413: macros and their arguments. If the standard syntax is used, you need
9414: not define them yourself.
9415:
9416: @item SDB_GENERATE_FAKE
9417: Define this macro to override the usual method of constructing a dummy
9418: name for anonymous structure and union types. See @file{sdbout.c} for
9419: more infomation.
9420:
9421: @item DBX_NO_XREFS
9422: Define this macro if DBX on your system does not support the construct
9423: @samp{xs@var{tagname}}. On some systems, this construct is used to
9424: describe a forward reference to a structure named @var{tagname}.
9425: On other systems, this construct is not supported at all.
9426:
9427: @item DBX_CONTIN_LENGTH
9428: A symbol name in DBX-format debugging information is normally
9429: continued (split into two separate @code{.stabs} directives) when it
9430: exceeds a certain length (by default, 80 characters). On some
9431: operating systems, DBX requires this splitting; on others, splitting
9432: must not be done. You can inhibit splitting by defining this macro
9433: with the value zero. You can override the default splitting-length by
9434: defining this macro as an expression for the length you desire.
9435:
9436: @item DBX_CONTIN_CHAR
9437: Normally continuation is indicated by adding a @samp{\} character to
9438: the end of a @code{.stabs} string when a continuation follows. To use
9439: a different character instead, define this macro as a character
9440: constant for the character you want to use. Do not define this macro
9441: if backslash is correct for your system.
9442:
1.1.1.8 ! root 9443: @item DBX_STATIC_STAB_DATA_SECTION
! 9444: Define this macro if it is necessary to go to the data section before
! 9445: outputting the @samp{.stabs} pseudo-op for a non-global static
! 9446: variable.
! 9447:
1.1 root 9448: @item ASM_OUTPUT_LABEL (@var{stream}, @var{name})
9449: A C statement (sans semicolon) to output to the stdio stream
1.1.1.8 ! root 9450: @var{stream} the assembler definition of a label named @var{name}.
! 9451: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
! 9452: output the name itself; before and after that, output the additional
1.1 root 9453: assembler syntax for defining the name, and a newline.
9454:
9455: @item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl})
9456: A C statement (sans semicolon) to output to the stdio stream
9457: @var{stream} any text necessary for declaring the name @var{name} of a
9458: function which is being defined. This macro is responsible for
9459: outputting the label definition (perhaps using
9460: @code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the
9461: @code{FUNCTION_DECL} tree node representing the function.
9462:
9463: If this macro is not defined, then the function name is defined in the
9464: usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
9465:
9466: @item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name})
9467: A C statement (sans semicolon) to output to the stdio stream
9468: @var{stream} some commands that will make the label @var{name} global;
9469: that is, available for reference from other files. Use the expression
9470: @code{assemble_name (@var{stream}, @var{name})} to output the name
9471: itself; before and after that, output the additional assembler syntax
9472: for making that name global, and a newline.
9473:
1.1.1.8 ! root 9474: @item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name})
1.1 root 9475: A C statement (sans semicolon) to output to the stdio stream
9476: @var{stream} any text necessary for declaring the name of an external
9477: symbol named @var{name} which is referenced in this compilation but
9478: not defined. The value of @var{decl} is the tree node for the
9479: declaration.
9480:
9481: This macro need not be defined if it does not need to output anything.
9482: The GNU assembler and most Unix assemblers don't require anything.
9483:
9484: @item ASM_OUTPUT_LABELREF (@var{stream}, @var{name})
1.1.1.8 ! root 9485: A C statement to output to the stdio stream @var{stream} a reference
! 9486: in assembler syntax to a label named @var{name}. The character
! 9487: @samp{_} should be added to the front of the name, if that is
! 9488: customary on your operating system, as it is in most Berkeley Unix
! 9489: systems. This macro is used in @code{assemble_name}.
1.1 root 9490:
9491: @item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num})
1.1.1.8 ! root 9492: A C statement to store into the string @var{string} a label whose name
! 9493: is made from the string @var{prefix} and the number @var{num}.
1.1 root 9494:
9495: This string, when output subsequently by @code{ASM_OUTPUT_LABELREF},
9496: should produce the same output that @code{ASM_OUTPUT_INTERNAL_LABEL}
9497: would produce with the same @var{prefix} and @var{num}.
9498:
9499: @item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num})
9500: A C statement to output to the stdio stream @var{stream} a label whose
9501: name is made from the string @var{prefix} and the number @var{num}.
9502: These labels are used for internal purposes, and there is no reason
9503: for them to appear in the symbol table of the object file. On many
9504: systems, the letter @samp{L} at the beginning of a label has this
9505: effect. The usual definition of this macro is as follows:
9506:
9507: @example
9508: fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num})
9509: @end example
9510:
9511: @item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table})
9512: Define this if the label before a jump-table needs to be output
9513: specially. The first three arguments are the same as for
9514: @code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the
1.1.1.8 ! root 9515: jump-table which follows (a @code{jump_insn} containing an
! 9516: @code{addr_vec} or @code{addr_diff_vec}).
1.1 root 9517:
9518: This feature is used on system V to output a @code{swbeg} statement
9519: for the table.
9520:
9521: If this macro is not defined, these labels are output with
9522: @code{ASM_OUTPUT_INTERNAL_LABEL}.
9523:
9524: @item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table})
1.1.1.8 ! root 9525: Define this if something special must be output at the end of a
! 9526: jump-table. The definition should be a C statement to be executed
! 9527: after the assembler code for the table is written. It should write
! 9528: the appropriate code to stdio stream @var{stream}. The argument
! 9529: @var{table} is the jump-table insn, and @var{num} is the label-number
! 9530: of the preceding label.
1.1 root 9531:
9532: If this macro is not defined, nothing special is output at the end of
9533: the jump-table.
9534:
1.1.1.4 root 9535: @item ASM_OUTPUT_ALIGN_CODE (@var{file})
9536: A C expression to output text to align the location counter in the way
9537: that is desirable at a point in the code that is reached only by
9538: jumping.
9539:
9540: This macro need not be defined if you don't want any special alignment
9541: to be done at such a time. Most machine descriptions do not currently
9542: define the macro.
9543:
1.1 root 9544: @item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number})
9545: A C expression to assign to @var{outvar} (which is a variable of type
9546: @code{char *}) a newly allocated string made from the string
9547: @var{name} and the number @var{number}, with some suitable punctuation
9548: added. Use @code{alloca} to get space for the string.
9549:
9550: This string will be used as the argument to @code{ASM_OUTPUT_LABELREF}
9551: to produce an assembler label for an internal static variable whose
9552: name is @var{name}. Therefore, the string must be such as to result
9553: in valid assembler code. The argument @var{number} is different each
9554: time this macro is executed; it prevents conflicts between
9555: similarly-named internal static variables in different scopes.
9556:
9557: Ideally this string should not be a valid C identifier, to prevent any
9558: conflict with the user's own symbols. Most assemblers allow periods
9559: or percent signs in assembler symbols; putting at least one of these
9560: between the name and the number will suffice.
9561:
9562: @item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno})
9563: A C expression to output to @var{stream} some assembler code
9564: which will push hard register number @var{regno} onto the stack.
9565: The code need not be optimal, since this macro is used only when
9566: profiling.
9567:
9568: @item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno})
9569: A C expression to output to @var{stream} some assembler code
9570: which will pop hard register number @var{regno} off of the stack.
9571: The code need not be optimal, since this macro is used only when
9572: profiling.
9573:
9574: @item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{value}, @var{rel})
9575: This macro should be provided on machines where the addresses
9576: in a dispatch table are relative to the table's own address.
9577:
9578: The definition should be a C statement to output to the stdio stream
9579: @var{stream} an assembler pseudo-instruction to generate a difference
9580: between two labels. @var{value} and @var{rel} are the numbers of two
9581: internal labels. The definitions of these labels are output using
9582: @code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same
9583: way here. For example,
9584:
9585: @example
9586: fprintf (@var{stream}, "\t.word L%d-L%d\n",
9587: @var{value}, @var{rel})
9588: @end example
9589:
9590: @item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value})
9591: This macro should be provided on machines where the addresses
9592: in a dispatch table are absolute.
9593:
9594: The definition should be a C statement to output to the stdio stream
9595: @var{stream} an assembler pseudo-instruction to generate a reference to
9596: a label. @var{value} is the number of an internal label whose
9597: definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}.
9598: For example,
9599:
9600: @example
9601: fprintf (@var{stream}, "\t.word L%d\n", @var{value})
9602: @end example
9603:
9604: @item ASM_OUTPUT_DOUBLE (@var{stream}, @var{value})
9605: A C statement to output to the stdio stream @var{stream} an assembler
9606: instruction to assemble a @code{double} constant whose value is
9607: @var{value}. @var{value} will be a C expression of type
9608: @code{double}.
9609:
9610: @item ASM_OUTPUT_FLOAT (@var{stream}, @var{value})
9611: A C statement to output to the stdio stream @var{stream} an assembler
9612: instruction to assemble a @code{float} constant whose value is
9613: @var{value}. @var{value} will be a C expression of type @code{float}.
9614:
9615: @item ASM_OUTPUT_INT (@var{stream}, @var{exp})
9616: @itemx ASM_OUTPUT_SHORT (@var{stream}, @var{exp})
9617: @itemx ASM_OUTPUT_CHAR (@var{stream}, @var{exp})
9618: A C statement to output to the stdio stream @var{stream} an assembler
9619: instruction to assemble a @code{int}, @code{short} or @code{char}
9620: constant whose value is @var{value}. The argument @var{exp} will be
9621: an RTL expression which represents a constant value. Use
9622: @samp{output_addr_const (@var{exp})} to output this value as an
9623: assembler expression.@refill
9624:
1.1.1.8 ! root 9625: @item ASM_OUTPUT_DOUBLE_INT (@var{stream}, @var{exp})
! 9626: A C statement to output to the stdio stream @var{stream} an assembler
! 9627: instruction to assemble a @code{long long} constant whose value is
! 9628: @var{exp}. The argument @var{exp} will be an RTL expression which
! 9629: represents a constant value. It may be a @code{const_double} RTX,
! 9630: or it may be an ordinary single-precision constant. In the latter
! 9631: case, you should zero-extend it.
! 9632:
1.1 root 9633: @item ASM_OUTPUT_BYTE (@var{stream}, @var{value})
9634: A C statement to output to the stdio stream @var{stream} an assembler
9635: instruction to assemble a single byte containing the number @var{value}.
9636:
9637: @item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len})
9638: A C statement to output to the stdio stream @var{stream} an assembler
9639: instruction to assemble a string constant containing the @var{len}
9640: bytes at @var{ptr}. @var{ptr} will be a C expression of type
9641: @code{char *} and @var{len} a C expression of type @code{int}.
9642:
9643: If the assembler has a @code{.ascii} pseudo-op as found in the
9644: Berkeley Unix assembler, do not define the macro
9645: @code{ASM_OUTPUT_ASCII}.
9646:
9647: @item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes})
9648: A C statement to output to the stdio stream @var{stream} an assembler
9649: instruction to advance the location counter by @var{nbytes} bytes.
9650: @var{nbytes} will be a C expression of type @code{int}.
9651:
9652: @item ASM_OUTPUT_ALIGN (@var{stream}, @var{power})
9653: A C statement to output to the stdio stream @var{stream} an assembler
9654: instruction to advance the location counter to a multiple of 2 to the
9655: @var{power} bytes. @var{power} will be a C expression of type @code{int}.
9656:
1.1.1.7 root 9657: @item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded})
1.1 root 9658: A C statement (sans semicolon) to output to the stdio stream
1.1.1.7 root 9659: @var{stream} the assembler definition of a common-label named
9660: @var{name} whose size is @var{size} bytes. The variable @var{rounded}
9661: is the size rounded up to whatever alignment the caller wants.
9662:
9663: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
9664: output the name itself; before and after that, output the additional
9665: assembler syntax for defining the name, and a newline.
1.1 root 9666:
9667: This macro controls how the assembler definitions of uninitialized
9668: global variables are output.
9669:
1.1.1.7 root 9670: @item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded})
1.1 root 9671: A C statement (sans semicolon) to output to the stdio stream
9672: @var{stream} the assembler definition of a local-common-label named
1.1.1.7 root 9673: @var{name} whose size is @var{size} bytes. The variable @var{rounded}
9674: is the size rounded up to whatever alignment the caller wants.
9675:
9676: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
9677: output the name itself; before and after that, output the additional
9678: assembler syntax for defining the name, and a newline.
1.1 root 9679:
9680: This macro controls how the assembler definitions of uninitialized
9681: static variables are output.
9682:
1.1.1.8 ! root 9683: @item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name})
! 9684: A C statment to output DBX or SDB debugging information which indicates
! 9685: that filename @var{name} is the current source file to the stdio stream
! 9686: @var{stream}.
! 9687:
! 9688: This macro need not be defined if the standard form of debugging
! 9689: information for the debugger in use is appropriate.
! 9690:
1.1 root 9691: @item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line})
9692: A C statment to output DBX or SDB debugging information before code
9693: for line number @var{line} of the current source file to the
9694: stdio stream @var{stream}.
9695:
9696: This macro need not be defined if the standard form of debugging
9697: information for the debugger in use is appropriate.
9698:
9699: @item ASM_OUTPUT_IDENT (@var{stream}, @var{string})
9700: A C statement to output something to the assembler file to handle a
9701: @samp{#ident} directive containing the text @var{string}. If this
1.1.1.7 root 9702: macro is not defined, nothing is output for a @samp{#ident} directive.
1.1 root 9703:
9704: @item TARGET_BELL
9705: A C constant expression for the integer value for escape sequence
9706: @samp{\a}.
9707:
9708: @item TARGET_BS
9709: @itemx TARGET_TAB
9710: @itemx TARGET_NEWLINE
9711: C constant expressions for the integer values for escape sequences
9712: @samp{\b}, @samp{\t} and @samp{\n}.
9713:
9714: @item TARGET_VT
9715: @itemx TARGET_FF
9716: @itemx TARGET_CR
9717: C constant expressions for the integer values for escape sequences
9718: @samp{\v}, @samp{\f} and @samp{\r}.
9719:
9720: @item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr})
9721: Define this macro if you are using an unusual assembler that
9722: requires different names for the machine instructions.
9723:
9724: The definition is a C statement or statements which output an
9725: assembler instruction opcode to the stdio stream @var{stream}. The
9726: macro-operand @var{ptr} is a variable of type @code{char *} which
9727: points to the opcode name in its ``internal'' form---the form that is
9728: written in the machine description. The definition should output the
9729: opcode name to @var{stream}, performing any translation you desire, and
9730: increment the variable @var{ptr} to point at the end of the opcode
9731: so that it will not be output twice.
9732:
9733: In fact, your macro definition may process less than the entire opcode
9734: name, or more than the opcode name; but if you want to process text
9735: that includes @samp{%}-sequences to substitute operands, you must take
9736: care of the substitution yourself. Just be sure to increment
9737: @var{ptr} over whatever text should not be output normally.
9738:
1.1.1.8 ! root 9739: If you need to look at the operand values, they can be found as the
! 9740: elements of @code{recog_operand}.
! 9741:
1.1 root 9742: If the macro definition does nothing, the instruction is output
9743: in the usual way.
9744:
9745: @item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands})
9746: If defined, a C statement to be executed just prior to the output of
9747: assembler code for @var{insn}, to modify the extracted operands so
9748: they will be output differently.
9749:
9750: Here the argument @var{opvec} is the vector containing the operands
9751: extracted from @var{insn}, and @var{noperands} is the number of
9752: elements of the vector which contain meaningful data for this insn.
9753: The contents of this vector are what will be used to convert the insn
9754: template into assembler code, so you can change the assembler output
9755: by changing the contents of the vector.
9756:
9757: This macro is useful when various assembler syntaxes share a single
9758: file of instruction patterns; by defining this macro differently, you
9759: can cause a large class of instructions to be output differently (such
9760: as with rearranged operands). Naturally, variations in assembler
9761: syntax affecting individual insn patterns ought to be handled by
9762: writing conditional output routines in those patterns.
9763:
9764: If this macro is not defined, it is equivalent to a null statement.
9765:
9766: @item PRINT_OPERAND (@var{stream}, @var{x}, @var{code})
9767: A C compound statement to output to stdio stream @var{stream} the
9768: assembler syntax for an instruction operand @var{x}. @var{x} is an
9769: RTL expression.
9770:
9771: @var{code} is a value that can be used to specify one of several ways
9772: of printing the operand. It is used when identical operands must be
9773: printed differently depending on the context. @var{code} comes from
9774: the @samp{%} specification that was used to request printing of the
9775: operand. If the specification was just @samp{%@var{digit}} then
9776: @var{code} is 0; if the specification was @samp{%@var{ltr}
9777: @var{digit}} then @var{code} is the ASCII code for @var{ltr}.
9778:
9779: If @var{x} is a register, this macro should print the register's name.
9780: The names can be found in an array @code{reg_names} whose type is
9781: @code{char *[]}. @code{reg_names} is initialized from
9782: @code{REGISTER_NAMES}.
9783:
9784: When the machine description has a specification @samp{%@var{punct}}
9785: (a @samp{%} followed by a punctuation character), this macro is called
9786: with a null pointer for @var{x} and the punctuation character for
9787: @var{code}.
9788:
1.1.1.8 ! root 9789: @item PRINT_OPERAND_PUNCT_VALID_P (@var{code})
! 9790: A C expression which evaluates to true if @var{code} is a valid
! 9791: punctuation character for use in the @code{PRINT_OPERAND} macro. If
! 9792: @code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no
! 9793: punctuation characters (except for the standard one, @samp{%}) are used
! 9794: in this way.
! 9795:
1.1 root 9796: @item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x})
9797: A C compound statement to output to stdio stream @var{stream} the
9798: assembler syntax for an instruction operand that is a memory reference
9799: whose address is @var{x}. @var{x} is an RTL expression.
9800:
9801: @item ASM_OPEN_PAREN
9802: @itemx ASM_CLOSE_PAREN
9803: These macros are defined as C string constant, describing the syntax
9804: in the assembler for grouping arithmetic expressions. The following
9805: definitions are correct for most assemblers:
9806:
9807: @example
9808: #define ASM_OPEN_PAREN "("
9809: #define ASM_CLOSE_PAREN ")"
9810: @end example
9811: @end table
9812:
9813: @node Config,, Machine Macros, Top
9814: @chapter The Configuration File
9815:
1.1.1.3 root 9816: The configuration file @file{xm-@var{machine}.h} contains macro definitions
9817: that describe the machine and system on which the compiler is running.
9818: Most of the values in it are actually the same on all machines that GNU CC
9819: runs on, so large parts of all configuration files are identical. But
1.1 root 9820: there are some macros that vary:
9821:
9822: @table @code
9823: @item FAILURE_EXIT_CODE
9824: A C expression for the status code to be returned when the compiler
9825: exits after serious errors.
9826:
9827: @item SUCCESS_EXIT_CODE
9828: A C expression for the status code to be returned when the compiler
9829: exits without serious errors.
9830: @end table
9831:
1.1.1.3 root 9832: In addition, configuration files for system V define @code{bcopy},
9833: @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
9834: as a macro when compiled with GNU CC, in order to take advantage of the
9835: benefit of GNU CC's built-in @code{alloca}.
9836:
1.1 root 9837: @contents
9838: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.