![[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.10 root 9: Copyright (C) 1988, 1989, 1990 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.9 root 24: sections entitled ``GNU General Public License'' and ``Protect Your
25: Freedom---Fight `Look And Feel'@w{}'' are included exactly as in the
26: original, and provided that the entire resulting derived work is
27: distributed under the terms of a permission notice identical to this
28: one.
1.1 root 29:
30: Permission is granted to copy and distribute translations of this manual
31: into another language, under the above conditions for modified versions,
1.1.1.9 root 32: except that the sections entitled ``GNU General Public License'' and
33: ``Protect Your Freedom---Fight `Look And Feel'@w{}'' and this permission
34: notice may be included in translations approved by the Free Software
35: Foundation instead of in the original English.
1.1 root 36: @end ifinfo
37:
38: @setchapternewpage odd
39:
40: @titlepage
41: @center @titlefont{Using and Porting GNU CC}
42: @sp 2
43: @center Richard M. Stallman
44: @sp 3
1.1.1.14! root 45: @center last updated 19 Sep 1992
1.1 root 46: @sp 1
1.1.1.14! root 47: @center for version 1.42
1.1 root 48: @page
49: @vskip 0pt plus 1filll
1.1.1.13 root 50: Copyright @copyright{} 1988, 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
1.1 root 51:
52: Permission is granted to make and distribute verbatim copies of
53: this manual provided the copyright notice and this permission notice
54: are preserved on all copies.
55:
56: Permission is granted to copy and distribute modified versions of this
57: manual under the conditions for verbatim copying, provided also that the
1.1.1.9 root 58: sections entitled ``GNU General Public License'' and ``Protect Your
59: Freedom---Fight `Look And Feel'@w{}'' are included exactly as in the
60: original, and provided that the entire resulting derived work is
61: distributed under the terms of a permission notice identical to this
62: one.
1.1 root 63:
64: Permission is granted to copy and distribute translations of this manual
65: into another language, under the above conditions for modified versions,
1.1.1.9 root 66: except that the sections entitled ``GNU General Public License'' and
67: ``Protect Your Freedom---Fight `Look And Feel'@w{}'' and this permission
68: notice may be included in translations approved by the Free Software
69: Foundation instead of in the original English.
1.1 root 70: @end titlepage
71: @page
72:
73: @ifinfo
74: @node Top, Copying,, (DIR)
75: @ichapter Introduction
76:
77: This manual documents how to run, install and port the GNU C compiler, as
78: well as its new features and incompatibilities, and how to report bugs.
79:
80: @end ifinfo
81: @menu
1.1.1.6 root 82: * Copying:: GNU General Public License says
1.1 root 83: how you can copy and share GNU CC.
84: * Contributors:: People who have contributed to GNU CC.
1.1.1.9 root 85: * Boycott:: Protect your freedom---fight ``look and feel''.
1.1 root 86: * Options:: Command options supported by @samp{gcc}.
87: * Installation:: How to configure, compile and install GNU CC.
88: * Trouble:: If you have trouble installing GNU CC.
1.1.1.10 root 89: * Service:: How to find suppliers of services for GNU CC users.
1.1 root 90: * Incompatibilities:: Incompatibilities of GNU CC.
91: * Extensions:: GNU extensions to the C language.
92: * Bugs:: How to report bugs (if you want to get them fixed).
93: * Portability:: Goals of GNU CC's portability features.
94: * Interface:: Function-call interface of GNU CC output.
95: * Passes:: Order of passes, what they do, and what each file is for.
96: * RTL:: The intermediate representation that most passes work on.
97: * Machine Desc:: How to write machine description instruction patterns.
98: * Machine Macros:: How to write the machine description C macros.
1.1.1.8 root 99: * Config:: Writing the @file{xm-@var{machine}.h} file.
1.1 root 100: @end menu
101:
102: @node Copying, Contributors, Top, Top
1.1.1.6 root 103: @unnumbered GNU GENERAL PUBLIC LICENSE
104: @center Version 1, February 1989
1.1 root 105:
1.1.1.6 root 106: @display
107: Copyright @copyright{} 1989 Free Software Foundation, Inc.
108: 675 Mass Ave, Cambridge, MA 02139, USA
109:
110: Everyone is permitted to copy and distribute verbatim copies
111: of this license document, but changing it is not allowed.
112: @end display
113:
114: @unnumberedsec Preamble
115:
116: The license agreements of most software companies try to keep users
117: at the mercy of those companies. By contrast, our General Public
118: License is intended to guarantee your freedom to share and change free
119: software---to make sure the software is free for all its users. The
120: General Public License applies to the Free Software Foundation's
121: software and to any other program whose authors commit to using it.
122: You can use it for your programs, too.
123:
124: When we speak of free software, we are referring to freedom, not
125: price. Specifically, the General Public License is designed to make
126: sure that you have the freedom to give away or sell copies of free
127: software, that you receive source code or can get it if you want it,
128: that you can change the software or use pieces of it in new free
129: programs; and that you know you can do these things.
130:
131: To protect your rights, we need to make restrictions that forbid
132: anyone to deny you these rights or to ask you to surrender the rights.
133: These restrictions translate to certain responsibilities for you if you
134: distribute copies of the software, or if you modify it.
135:
136: For example, if you distribute copies of a such a program, whether
137: gratis or for a fee, you must give the recipients all the rights that
138: you have. You must make sure that they, too, receive or can get the
1.1 root 139: source code. And you must tell them their rights.
140:
1.1.1.6 root 141: We protect your rights with two steps: (1) copyright the software, and
142: (2) offer you this license which gives you legal permission to copy,
143: distribute and/or modify the software.
144:
145: Also, for each author's protection and ours, we want to make certain
146: that everyone understands that there is no warranty for this free
147: software. If the software is modified by someone else and passed on, we
148: want its recipients to know that what they have is not the original, so
149: that any problems introduced by others will not reflect on the original
150: authors' reputations.
1.1 root 151:
1.1.1.6 root 152: The precise terms and conditions for copying, distribution and
153: modification follow.
1.1 root 154:
1.1.1.6 root 155: @iftex
156: @unnumberedsec TERMS AND CONDITIONS
157: @end iftex
158: @ifinfo
159: @center TERMS AND CONDITIONS
160: @end ifinfo
1.1 root 161:
1.1.1.6 root 162: @enumerate
1.1 root 163: @item
1.1.1.6 root 164: This License Agreement applies to any program or other work which
165: contains a notice placed by the copyright holder saying it may be
166: distributed under the terms of this General Public License. The
167: ``Program'', below, refers to any such program or work, and a ``work based
168: on the Program'' means either the Program or any work containing the
169: Program or a portion of it, either verbatim or with modifications. Each
170: licensee is addressed as ``you''.
171:
172: @item
173: You may copy and distribute verbatim copies of the Program's source
174: code as you receive it, in any medium, provided that you conspicuously and
175: appropriately publish on each copy an appropriate copyright notice and
176: disclaimer of warranty; keep intact all the notices that refer to this
177: General Public License and to the absence of any warranty; and give any
178: other recipients of the Program a copy of this General Public License
179: along with the Program. You may charge a fee for the physical act of
180: transferring a copy.
181:
182: @item
183: You may modify your copy or copies of the Program or any portion of
184: it, and copy and distribute such modifications under the terms of Paragraph
185: 1 above, provided that you also do the following:
1.1 root 186:
187: @itemize @bullet
188: @item
1.1.1.6 root 189: cause the modified files to carry prominent notices stating that
190: you changed the files and the date of any change; and
1.1 root 191:
192: @item
193: cause the whole of any work that you distribute or publish, that
1.1.1.6 root 194: in whole or in part contains the Program or any part thereof, either
195: with or without modifications, to be licensed at no charge to all
196: third parties under the terms of this General Public License (except
197: that you may choose to grant warranty protection to some or all
198: third parties, at your option).
199:
200: @item
201: If the modified program normally reads commands interactively when
202: run, you must cause it, when started running for such interactive use
203: in the simplest and most usual way, to print or display an
204: announcement including an appropriate copyright notice and a notice
205: that there is no warranty (or else, saying that you provide a
206: warranty) and that users may redistribute the program under these
207: conditions, and telling the user how to view a copy of this General
208: Public License.
209:
210: @item
211: You may charge a fee for the physical act of transferring a
212: copy, and you may at your option offer warranty protection in
213: exchange for a fee.
1.1 root 214: @end itemize
215:
1.1.1.6 root 216: Mere aggregation of another independent work with the Program (or its
1.1 root 217: derivative) on a volume of a storage or distribution medium does not bring
1.1.1.6 root 218: the other work under the scope of these terms.
1.1 root 219:
220: @item
1.1.1.6 root 221: You may copy and distribute the Program (or a portion or derivative of
222: it, under Paragraph 2) in object code or executable form under the terms of
223: Paragraphs 1 and 2 above provided that you also do one of the following:
1.1 root 224:
225: @itemize @bullet
226: @item
227: accompany it with the complete corresponding machine-readable
228: source code, which must be distributed under the terms of
229: Paragraphs 1 and 2 above; or,
230:
231: @item
232: accompany it with a written offer, valid for at least three
1.1.1.6 root 233: years, to give any third party free (except for a nominal charge
234: for the cost of distribution) a complete machine-readable copy of the
1.1 root 235: corresponding source code, to be distributed under the terms of
236: Paragraphs 1 and 2 above; or,
237:
238: @item
239: accompany it with the information you received as to where the
240: corresponding source code may be obtained. (This alternative is
241: allowed only for noncommercial distribution and only if you
242: received the program in object code or executable form alone.)
243: @end itemize
244:
1.1.1.6 root 245: Source code for a work means the preferred form of the work for making
246: modifications to it. For an executable file, complete source code means
247: all the source code for all modules it contains; but, as a special
248: exception, it need not include source code for modules which are standard
249: libraries that accompany the operating system on which the executable
250: file runs, or for standard header files or definitions files that
251: accompany that operating system.
252:
253: @item
254: You may not copy, modify, sublicense, distribute or transfer the
255: Program except as expressly provided under this General Public License.
256: Any attempt otherwise to copy, modify, sublicense, distribute or transfer
257: the Program is void, and will automatically terminate your rights to use
258: the Program under this License. However, parties who have received
259: copies, or rights to use copies, from you under this General Public
260: License will not have their licenses terminated so long as such parties
261: remain in full compliance.
262:
263: @item
264: By copying, distributing or modifying the Program (or any work based
265: on the Program) you indicate your acceptance of this license to do so,
266: and all its terms and conditions.
267:
268: @item
269: Each time you redistribute the Program (or any work based on the
270: Program), the recipient automatically receives a license from the original
271: licensor to copy, distribute or modify the Program subject to these
272: terms and conditions. You may not impose any further restrictions on the
273: recipients' exercise of the rights granted herein.
274:
275: @item
276: The Free Software Foundation may publish revised and/or new versions
277: of the General Public License from time to time. Such new versions will
278: be similar in spirit to the present version, but may differ in detail to
279: address new problems or concerns.
280:
281: Each version is given a distinguishing version number. If the Program
282: specifies a version number of the license which applies to it and ``any
283: later version'', you have the option of following the terms and conditions
284: either of that version or of any later version published by the Free
285: Software Foundation. If the Program does not specify a version number of
286: the license, you may choose any version ever published by the Free Software
287: Foundation.
288:
289: @item
290: If you wish to incorporate parts of the Program into other free
291: programs whose distribution conditions are different, write to the author
292: to ask for permission. For software which is copyrighted by the Free
293: Software Foundation, write to the Free Software Foundation; we sometimes
294: make exceptions for this. Our decision will be guided by the two goals
295: of preserving the free status of all derivatives of our free software and
296: of promoting the sharing and reuse of software generally.
297:
298: @iftex
299: @heading NO WARRANTY
300: @end iftex
301: @ifinfo
302: @center NO WARRANTY
303: @end ifinfo
304:
305: @item
306: BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
307: FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
308: OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
309: PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
310: OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
311: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
312: TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
313: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
314: REPAIR OR CORRECTION.
315:
316: @item
317: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
318: ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
319: REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
320: INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
321: ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
322: LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
323: SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
324: WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
325: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
1.1 root 326: @end enumerate
327:
1.1.1.6 root 328: @iftex
329: @heading END OF TERMS AND CONDITIONS
330: @end iftex
331: @ifinfo
332: @center END OF TERMS AND CONDITIONS
333: @end ifinfo
334:
335: @page
336: @unnumberedsec Appendix: How to Apply These Terms to Your New Programs
337:
338: If you develop a new program, and you want it to be of the greatest
339: possible use to humanity, the best way to achieve this is to make it
340: free software which everyone can redistribute and change under these
341: terms.
342:
343: To do so, attach the following notices to the program. It is safest to
344: attach them to the start of each source file to most effectively convey
345: the exclusion of warranty; and each file should have at least the
346: ``copyright'' line and a pointer to where the full notice is found.
347:
348: @smallexample
349: @var{one line to give the program's name and a brief idea of what it does.}
350: Copyright (C) 19@var{yy} @var{name of author}
351:
352: This program is free software; you can redistribute it and/or modify
353: it under the terms of the GNU General Public License as published by
354: the Free Software Foundation; either version 1, or (at your option)
355: any later version.
356:
357: This program is distributed in the hope that it will be useful,
358: but WITHOUT ANY WARRANTY; without even the implied warranty of
359: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
360: GNU General Public License for more details.
361:
362: You should have received a copy of the GNU General Public License
363: along with this program; if not, write to the Free Software
364: Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
365: @end smallexample
366:
367: Also add information on how to contact you by electronic and paper mail.
368:
369: If the program is interactive, make it output a short notice like this
370: when it starts in an interactive mode:
371:
372: @smallexample
373: Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
374: Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
375: This is free software, and you are welcome to redistribute it
376: under certain conditions; type `show c' for details.
377: @end smallexample
378:
379: The hypothetical commands `show w' and `show c' should show the
380: appropriate parts of the General Public License. Of course, the
381: commands you use may be called something other than `show w' and `show
382: c'; they could even be mouse-clicks or menu items---whatever suits your
383: program.
384:
385: You should also get your employer (if you work as a programmer) or your
386: school, if any, to sign a ``copyright disclaimer'' for the program, if
387: necessary. Here a sample; alter the names:
388:
389: @example
390: Yoyodyne, Inc., hereby disclaims all copyright interest in the
391: program `Gnomovision' (a program to direct compilers to make passes
392: at assemblers) written by James Hacker.
393:
394: @var{signature of Ty Coon}, 1 April 1989
395: Ty Coon, President of Vice
396: @end example
397:
398: That's all there is to it!
1.1 root 399:
1.1.1.9 root 400: @node Contributors, Boycott, Copying, Top
1.1 root 401: @unnumbered Contributors to GNU CC
402:
403: In addition to Richard Stallman, several people have written parts
404: of GNU CC.
405:
406: @itemize @bullet
407: @item
408: The idea of using RTL and some of the optimization ideas came from the
409: U. of Arizona Portable Optimizer, written by Jack Davidson and
410: Christopher Fraser. See ``Register Allocation and Exhaustive Peephole
411: Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
412: 857-866.
413:
414: @item
415: Paul Rubin wrote most of the preprocessor.
416:
417: @item
1.1.1.6 root 418: Leonard Tower wrote parts of the parser, RTL generator, and RTL
1.1 root 419: definitions, and of the Vax machine description.
420:
421: @item
422: Ted Lemon wrote parts of the RTL reader and printer.
423:
424: @item
425: Jim Wilson implemented loop strength reduction and some other
426: loop optimizations.
427:
428: @item
429: Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
1.1.1.8 root 430: the support for the Sony NEWS machine.
1.1 root 431:
432: @item
433: Charles LaBrec contributed the support for the Integrated Solutions
434: 68020 system.
435:
436: @item
437: Michael Tiemann of MCC wrote most of the description of the National
438: Semiconductor 32000 series cpu. He also wrote the code for inline
439: function integration and for the SPARC cpu and Motorola 88000 cpu
440: and part of the Sun FPA support.
441:
442: @item
443: Jan Stein of the Chalmers Computer Society provided support for
444: Genix, as well as part of the 32000 machine description.
445:
446: @item
447: Randy Smith finished the Sun FPA support.
448:
449: @item
450: Robert Brown implemented the support for Encore 32000 systems.
451:
452: @item
453: David Kashtan of SRI adapted GNU CC to the Vomit-Making System.
454:
455: @item
456: Alex Crain provided changes for the 3b1.
457:
458: @item
459: Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for
460: the 9000 series 300.
461:
462: @item
463: William Schelter did most of the work on the Intel 80386 support.
1.1.1.5 root 464:
465: @item
466: Christopher Smith did the port for Convex machines.
467:
468: @item
469: Paul Petersen wrote the machine description for the Alliant FX/8.
1.1.1.7 root 470:
471: @item
1.1.1.8 root 472: Alain Lichnewsky ported GNU CC to the Mips cpu.
473:
474: @item
475: Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the Tahoe.
476:
477: @item
478: Jonathan Stone wrote the machine description for the Pyramid computer.
1.1 root 479: @end itemize
480:
1.1.1.9 root 481: @node Boycott, Options, Contributors, Top
482: @chapter Protect Your Freedom---Fight ``Look And Feel''
483:
1.1.1.10 root 484: @quotation
485: @i{This section is a political message from the League for Programming
486: Freedom to the users of GNU CC. It is included here as an expression
487: of support for the League on the part of the Free Software Foundation
488: and Richard Stallman.}
489: @end quotation
490:
1.1.1.9 root 491: Ashton-Tate, Apple, Lotus and Xerox are trying to create a new form of
492: legal monopoly: a copyright on a class of user interfaces. These
493: monopolies would cause serious problems for users and developers of
494: computer software and systems.
495:
1.1.1.10 root 496: Until a few years ago, the law seemed clear: no one could restrict
1.1.1.9 root 497: others from using a user interface; programmers were free to implement
498: any interface they chose. Imitating interfaces, sometimes with changes,
499: was standard practice in the computer field. The interfaces we know
500: evolved gradually in this way; for example, the Macintosh user interface
501: drew ideas from the Xerox interface, which in turn drew on work done at
1.1.1.10 root 502: Stanford and SRI. 1-2-3 imitated VisiCalc, and dBase imitated a
503: database program from JPL.
1.1.1.9 root 504:
505: Most computer companies, and nearly all computer users, were happy with
506: this state of affairs. The companies that are suing say it does not
507: offer ``enough incentive'' to develop their products, but they must have
508: considered it ``enough'' when they made their decision to do so. It
509: seems they are not satisfied with the opportunity to continue to compete
510: in the marketplace---not even with a head start.
511:
512: If Xerox, Lotus, Apple and Ashton-Tate are permitted to make law through
513: the courts, the precedent will hobble the software industry:
514:
515: @itemize @bullet
516: @item
1.1.1.11 root 517: Gratuitous incompatibilities will burden users. Imagine if each
1.1.1.9 root 518: car manufacturer had to arrange the pedals in a different order.
519:
520: @item
521: Software will become and remain more expensive. Users will be
522: ``locked in'' to proprietary interfaces, for which there is no real
523: competition.
524:
525: @item
526: Large companies have an unfair advantage wherever lawsuits become
527: commonplace. Since they can easily afford to sue, they can intimidate
528: small companies with threats even when they don't really have a case.
529:
530: @item
531: User interface improvements will come slower, since incremental
532: evolution through creative imitation will no longer be permitted.
533:
534: @item
535: Even Apple, etc., will find it harder to make improvements if
536: they can no longer adapt the good ideas that others introduce, for
537: fear of weakening their own legal positions. Some users suggest that
538: this stagnation may already have started.
1.1.1.10 root 539:
540: @item
541: If you use GNU software, you might find it of some concern that user
542: interface copyright will make it hard for the Free Software Foundation
543: to develop programs compatible with the interfaces that you already
544: know.
1.1.1.9 root 545: @end itemize
546:
1.1.1.10 root 547: To protect our freedom from lawsuits like these, a group of programmers
548: and users have formed a new grass-roots political organization, the
549: League for Programming Freedom.
550:
551: The purpose of the League is to oppose new monopolistic practices such
552: as user-interface copyright and software patents; it calls for a return
553: to the legal policies of the recent past, in which these practices were
554: not allowed. The League is not concerned with free software as an
555: issue, and not affiliated with the Free Software Foundation.
556:
557: The League's membership rolls include John McCarthy, inventor of Lisp,
558: Marvin Minsky, founder of the Artificial Intelligence lab, Guy L.
559: Steele, Jr., author of well-known books on Lisp and C, as well as
560: Richard Stallman, the developer of GNU CC. Please join and add your
561: name to the list. Membership dues in the League are $42 per year for
562: programmers, managers and professionals; $10.50 for students; $21 for
563: others.
564:
565: The League needs both activist members and members who only pay their
566: dues.
567:
568: To join, or for more information, phone (617) 492-0023 or write to:
569:
570: @example
571: League for Programming Freedom
572: 1 Kendall Square #143
573: P.O. Box 9171
574: Cambridge, MA 02139 league@@prep.ai.mit.edu
575: @end example
576:
577: Here are some suggestions from the League for how you can protect your
578: freedom to write programs:
1.1.1.9 root 579:
580: @itemize @bullet
581: @item
582: Don't buy from Xerox, Lotus, Apple or Ashton-Tate. Buy from their
583: competitors or from the defendants they are suing.
584:
585: @item
586: Don't develop software to work with the systems made by these companies.
587:
588: @item
589: Port your existing software to competing systems, so that you encourage
590: users to switch.
591:
592: @item
593: Write letters to company presidents to let them know their conduct
594: is unacceptable.
595:
596: @item
597: Tell your friends and colleagues about this issue and how it threatens
598: to ruin the computer industry.
599:
600: @item
601: Above all, don't work for the look-and-feel plaintiffs, and don't
602: accept contracts from them.
603:
604: @item
1.1.1.11 root 605: Write to Congress to explain the importance of this issue.
1.1.1.9 root 606:
607: @example
1.1.1.11 root 608: House Subcommittee on Intellectual Property
609: 2137 Rayburn Bldg
610: Washington, DC 20515
1.1.1.9 root 611:
1.1.1.11 root 612: Senate Subcommittee on Patents, Trademarks and Copyrights
613: United States Senate
614: Washington, DC 20510
615: @end example
1.1.1.9 root 616: @end itemize
617:
618: Express your opinion! You can make a difference.
619:
620: @node Options, Installation, Boycott, Top
1.1 root 621: @chapter GNU CC Command Options
622:
623: The GNU C compiler uses a command syntax much like the Unix C compiler.
624: The @code{gcc} program accepts options and file names as operands.
625: Multiple single-letter options may @emph{not} be grouped: @samp{-dr} is
1.1.1.8 root 626: very different from @w{@samp{-d -r}}.
1.1 root 627:
628: When you invoke GNU CC, it normally does preprocessing, compilation,
629: assembly and linking. File names which end in @samp{.c} are taken as C
1.1.1.5 root 630: source to be preprocessed and compiled; file names ending in @samp{.i}
631: are taken as preprocessor output to be compiled; compiler output files
632: plus any input files with names ending in @samp{.s} are assembled; then
633: the resulting object files, plus any other input files, are linked
634: together to produce an executable.
1.1 root 635:
636: Command options allow you to stop this process at an intermediate stage.
637: For example, the @samp{-c} option says not to run the linker. Then the
638: output consists of object files output by the assembler.
639:
1.1.1.5 root 640: Other command options are passed on to one stage of processing. Some
641: options control the preprocessor and others the compiler itself. Yet
642: other options control the assembler and linker; these are not documented
643: here, but you rarely need to use any of them.
1.1 root 644:
645: Here are the options to control the overall compilation process, including
646: those that say whether to link, whether to assemble, and so on.
647:
648: @table @samp
649: @item -o @var{file}
650: Place output in file @var{file}. This applies regardless to whatever
651: sort of output is being produced, whether it be an executable file,
652: an object file, an assembler file or preprocessed C code.
653:
654: If @samp{-o} is not specified, the default is to put an executable file
655: in @file{a.out}, the object file @file{@var{source}.c} in
656: @file{@var{source}.o}, an assembler file in @file{@var{source}.s}, and
657: preprocessed C on standard output.@refill
658:
659: @item -c
660: Compile or assemble the source files, but do not link. Produce object
661: files with names made by replacing @samp{.c} or @samp{.s} with
662: @samp{.o} at the end of the input file names. Do nothing at all for
663: object files specified as input.
664:
665: @item -S
666: Compile into assembler code but do not assemble. The assembler output
667: file name is made by replacing @samp{.c} with @samp{.s} at the end of
668: the input file name. Do nothing at all for assembler source files or
669: object files specified as input.
670:
671: @item -E
672: Run only the C preprocessor. Preprocess all the C source files
673: specified and output the results to standard output.
674:
675: @item -v
676: Compiler driver program prints the commands it executes as it runs
677: the preprocessor, compiler proper, assembler and linker. Some of
678: these are directed to print their own version numbers.
679:
1.1.1.5 root 680: @item -pipe
681: Use pipes rather than temporary files for communication between the
682: various stages of compilation. This fails to work on some systems
683: where the assembler is unable to read from a pipe; but the GNU
684: assembler has no trouble.
685:
1.1 root 686: @item -B@var{prefix}
687: Compiler driver program tries @var{prefix} as a prefix for each
688: program it tries to run. These programs are @file{cpp}, @file{cc1},
689: @file{as} and @file{ld}.
690:
691: For each subprogram to be run, the compiler driver first tries the
692: @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
693: was not specified, the driver tries two standard prefixes, which are
694: @file{/usr/lib/gcc-} and @file{/usr/local/lib/gcc-}. If neither of
695: those results in a file name that is found, the unmodified program
696: name is searched for using the directories specified in your
697: @samp{PATH} environment variable.
698:
699: The run-time support file @file{gnulib} is also searched for using
700: the @samp{-B} prefix, if needed. If it is not found there, the two
701: standard prefixes above are tried, and that is all. The file is left
702: out of the link if it is not found by those means. Most of the time,
703: on most machines, you can do without it.
1.1.1.5 root 704:
705: You can get a similar result from the environment variable;
706: @code{GCC_EXEC_PREFIX} if it is defined, its value is used as a prefix
707: in the same way. If both the @samp{-B} option and the
708: @code{GCC_EXEC_PREFIX} variable are present, the @samp{-B} option is
709: used first and the environment variable value second.
1.1.1.8 root 710:
711: @item -b@var{prefix}
712: The argument @var{prefix} is used as a second prefix for the compiler
713: executables and libraries. This prefix is optional: the compiler tries
714: each file first with it, then without it. This prefix follows the
715: prefix specified with @samp{-B} or the default prefixes.
716:
717: Thus, @samp{-bvax- -Bcc/} in the presence of environment variable
718: @code{GCC_EXEC_PREFIX} with definition @file{/u/foo/} causes GNU CC to
719: try the following file names for the preprocessor executable:
720:
721: @example
722: cc/vax-cpp
723: cc/cpp
724: /u/foo/vax-cpp
725: /u/foo/cpp
726: /usr/local/lib/gcc-vax-cpp
727: /usr/local/lib/gcc-cpp
728: /usr/lib/gcc-vax-cpp
729: /usr/lib/gcc-cpp
730: @end example
1.1 root 731: @end table
732:
733: These options control the details of C compilation itself.
734:
735: @table @samp
736: @item -ansi
737: Support all ANSI standard C programs.
738:
739: This turns off certain features of GNU C that are incompatible with
740: ANSI C, such as the @code{asm}, @code{inline} and @code{typeof}
741: keywords, and predefined macros such as @code{unix} and @code{vax}
742: that identify the type of system you are using. It also enables the
743: undesirable and rarely used ANSI trigraph feature.
744:
1.1.1.8 root 745: The alternate keywords @code{__asm__}, @code{__inline__} and
746: @code{__typeof__} continue to work despite @samp{-ansi}. You would not
1.1.1.7 root 747: want to use them in an ANSI C program, of course, but it useful to put
748: them in header files that might be included in compilations done with
1.1.1.8 root 749: @samp{-ansi}. Alternate predefined macros such as @code{__unix__} and
750: @code{__vax__} are also available, with or without @samp{-ansi}.
1.1.1.7 root 751:
1.1 root 752: The @samp{-ansi} option does not cause non-ANSI programs to be
753: rejected gratuitously. For that, @samp{-pedantic} is required in
754: addition to @samp{-ansi}.
755:
756: The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
757: option is used. Some header files may notice this macro and refrain
758: from declaring certain functions or defining certain macros that the
1.1.1.7 root 759: ANSI standard doesn't call for; this is to avoid interfering with any
760: programs that might use these names for other things.
1.1 root 761:
762: @item -traditional
763: Attempt to support some aspects of traditional C compilers.
764: Specifically:
765:
766: @itemize @bullet
767: @item
768: All @code{extern} declarations take effect globally even if they
769: are written inside of a function definition. This includes implicit
770: declarations of functions.
771:
772: @item
773: The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
1.1.1.10 root 774: and @code{volatile} are not recognized. (You can still use the alternative
775: keywords such as @code{__typeof__}, @code{__inline__}, and so on.)
1.1 root 776:
777: @item
778: Comparisons between pointers and integers are always allowed.
779:
780: @item
781: Integer types @code{unsigned short} and @code{unsigned char} promote
782: to @code{unsigned int}.
783:
784: @item
785: Out-of-range floating point literals are not an error.
786:
787: @item
1.1.1.8 root 788: String ``constants'' are not necessarily constant; they are stored in
789: writable space, and identical looking constants are allocated
790: separately.
791:
792: @item
1.1.1.2 root 793: All automatic variables not declared @code{register} are preserved by
794: @code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
795: not declared @code{volatile} may be clobbered.
796:
797: @item
1.1 root 798: In the preprocessor, comments convert to nothing at all, rather than
799: to a space. This allows traditional token concatenation.
800:
801: @item
802: In the preprocessor, macro arguments are recognized within string
803: constants in a macro definition (and their values are stringified,
804: though without additional quote marks, when they appear in such a
805: context). The preprocessor always considers a string constant to end
806: at a newline.
807:
808: @item
809: The predefined macro @code{__STDC__} is not defined when you use
810: @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
811: which @code{__GNUC__} indicates are not affected by
812: @samp{-traditional}). If you need to write header files that work
813: differently depending on whether @samp{-traditional} is in use, by
814: testing both of these predefined macros you can distinguish four
815: situations: GNU C, traditional GNU C, other ANSI C compilers, and
816: other old C compilers.
817: @end itemize
818:
819: @item -O
820: Optimize. Optimizing compilation takes somewhat more time, and a lot
821: more memory for a large function.
822:
823: Without @samp{-O}, the compiler's goal is to reduce the cost of
824: compilation and to make debugging produce the expected results.
825: Statements are independent: if you stop the program with a breakpoint
826: between statements, you can then assign a new value to any variable or
827: change the program counter to any other statement in the function and
828: get exactly the results you would expect from the source code.
829:
830: Without @samp{-O}, only variables declared @code{register} are
831: allocated in registers. The resulting compiled code is a little worse
832: than produced by PCC without @samp{-O}.
833:
834: With @samp{-O}, the compiler tries to reduce code size and execution
835: time.
836:
837: Some of the @samp{-f} options described below turn specific kinds of
838: optimization on or off.
839:
840: @item -g
841: Produce debugging information in the operating system's native format
842: (for DBX or SDB). GDB also can work with this debugging information.
843:
844: Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
845: @samp{-O}. The shortcuts taken by optimized code may occasionally
846: produce surprising results: some variables you declared may not exist
847: at all; flow of control may briefly move where you did not expect it;
848: some statements may not be executed because they compute constant
849: results or their values were already at hand; some statements may
850: execute in different places because they were moved out of loops.
851: Nevertheless it proves possible to debug optimized output. This makes
852: it reasonable to use the optimizer for programs that might have bugs.
853:
854: @item -gg
1.1.1.8 root 855: Produce debugging information in the old GDB format. This is obsolete.
1.1 root 856:
857: @item -w
858: Inhibit all warning messages.
859:
860: @item -W
861: Print extra warning messages for these events:
862:
863: @itemize @bullet
864: @item
865: An automatic variable is used without first being initialized.
866:
867: These warnings are possible only in optimizing compilation,
868: because they require data flow information that is computed only
1.1.1.6 root 869: when optimizing. If you don't specify @samp{-O}, you simply won't
870: get these warnings.
871:
872: These warnings occur only for variables that are candidates for
873: register allocation. Therefore, they do not occur for a variable that
874: is declared @code{volatile}, or whose address is taken, or whose size
875: is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
876: structures, unions or arrays, even when they are in registers.
877:
878: Note that there may be no warning about a variable that is used only
879: to compute a value that itself is never used, because such
880: computations may be deleted by data flow analysis before the warnings
881: are printed.
1.1 root 882:
883: These warnings are made optional because GNU CC is not smart
884: enough to see all the reasons why the code might be correct
885: despite appearing to have an error. Here is one example of how
886: this can happen:
887:
888: @example
889: @{
890: int x;
891: switch (y)
892: @{
893: case 1: x = 1;
894: break;
895: case 2: x = 4;
896: break;
897: case 3: x = 5;
898: @}
899: foo (x);
900: @}
901: @end example
902:
903: @noindent
904: If the value of @code{y} is always 1, 2 or 3, then @code{x} is
905: always initialized, but GNU CC doesn't know this. Here is
906: another common case:
907:
908: @example
909: @{
910: int save_y;
911: if (change_y) save_y = y, y = new_y;
912: @dots{}
913: if (change_y) y = save_y;
914: @}
915: @end example
916:
917: @noindent
918: This has no bug because @code{save_y} is used only if it is set.
919:
1.1.1.5 root 920: Some spurious warnings can be avoided if you declare as
921: @code{volatile} all the functions you use that never return.
922: @xref{Function Attributes}.
923:
1.1 root 924: @item
925: A nonvolatile automatic variable might be changed by a call to
926: @code{longjmp}. These warnings as well are possible only in
927: optimizing compilation.
928:
929: The compiler sees only the calls to @code{setjmp}. It cannot know
930: where @code{longjmp} will be called; in fact, a signal handler could
931: call it at any point in the code. As a result, you may get a warning
932: even when there is in fact no problem because @code{longjmp} cannot
933: in fact be called at the place which would cause a problem.
934:
935: @item
936: A function can return either with or without a value. (Falling
937: off the end of the function body is considered returning without
1.1.1.6 root 938: a value.) For example, this function would evoke such a
1.1 root 939: warning:
940:
941: @example
942: foo (a)
943: @{
944: if (a > 0)
945: return a;
946: @}
947: @end example
948:
949: Spurious warnings can occur because GNU CC does not realize that
950: certain functions (including @code{abort} and @code{longjmp})
951: will never return.
1.1.1.4 root 952:
953: @item
954: An expression-statement contains no side effects.
1.1 root 955: @end itemize
956:
957: In the future, other useful warnings may also be enabled by this
958: option.
959:
960: @item -Wimplicit
961: Warn whenever a function is implicitly declared.
962:
963: @item -Wreturn-type
964: Warn whenever a function is defined with a return-type that defaults
965: to @code{int}. Also warn about any @code{return} statement with no
966: return-value in a function whose return-type is not @code{void}.
967:
968: @item -Wunused
1.1.1.5 root 969: Warn whenever a local variable is unused aside from its declaration,
1.1.1.8 root 970: whenever a function is declared static but never defined, and whenever
971: a statement computes a result that is explicitly not used.
1.1.1.7 root 972:
973: @item -Wswitch
974: Warn whenever a @code{switch} statement has an index of enumeral type
975: and lacks a @code{case} for one or more of the named codes of that
976: enumeration. (The presence of a @code{default} label prevents this
977: warning.) @code{case} labels outside the enumeration range also
978: provoke warnings when this option is used.
979:
1.1 root 980: @item -Wcomment
981: Warn whenever a comment-start sequence @samp{/*} appears in a comment.
982:
1.1.1.7 root 983: @item -Wtrigraphs
984: Warn if any trigraphs are encountered (assuming they are enabled).
985:
1.1 root 986: @item -Wall
1.1.1.8 root 987: All of the above @samp{-W} options combined. These are all the
988: options which pertain to usage that we recommend avoiding and that we
989: believe is easy to avoid, even in conjunction with macros.
990:
991: The other @samp{-W@dots{}} options below are not implied by @samp{-Wall}
992: because certain kinds of useful macros are almost impossible to write
993: without causing those warnings.
994:
995: @item -Wshadow
996: Warn whenever a local variable shadows another local variable.
997:
998: @item -Wid-clash-@var{len}
999: Warn whenever two distinct identifiers match in the first @var{len}
1000: characters. This may help you prepare a program that will compile
1001: with certain obsolete, brain-damaged compilers.
1002:
1003: @item -Wpointer-arith
1004: Warn about anything that depends on the ``size of'' a function type or
1005: of @code{void}. GNU C assigns these types a size of 1, for
1006: convenience in calculations with @code{void *} pointers and pointers
1007: to functions.
1.1 root 1008:
1.1.1.6 root 1009: @item -Wcast-qual
1010: Warn whenever a pointer is cast so as to remove a type qualifier from
1011: the target type. For example, warn if a @code{const char *} is cast
1012: to an ordinary @code{char *}.
1013:
1.1 root 1014: @item -Wwrite-strings
1015: Give string constants the type @code{const char[@var{length}]} so that
1016: copying the address of one into a non-@code{const} @code{char *}
1017: pointer will get a warning. These warnings will help you find at
1018: compile time code that can try to write into a string constant, but
1019: only if you have been very careful about using @code{const} in
1020: declarations and prototypes. Otherwise, it will just be a nuisance;
1021: this is why we did not make @samp{-Wall} request these warnings.
1022:
1023: @item -p
1024: Generate extra code to write profile information suitable for the
1025: analysis program @code{prof}.
1026:
1027: @item -pg
1028: Generate extra code to write profile information suitable for the
1029: analysis program @code{gprof}.
1030:
1.1.1.6 root 1031: @item -a
1.1.1.8 root 1032: Generate extra code to write profile information for basic blocks, which
1033: will record the number of times each basic block is executed. This data
1034: could be analyzed by a program like @code{tcov}. Note, however, that
1035: the format of the data is not what @code{tcov} expects. Eventually GNU
1.1.1.6 root 1036: @code{gprof} should be extended to process this data.
1037:
1.1 root 1038: @item -l@var{library}
1039: Search a standard list of directories for a library named
1040: @var{library}, which is actually a file named
1041: @file{lib@var{library}.a}. The linker uses this file as if it
1042: had been specified precisely by name.
1043:
1044: The directories searched include several standard system directories
1045: plus any that you specify with @samp{-L}.
1046:
1047: Normally the files found this way are library files---archive files
1048: whose members are object files. The linker handles an archive file by
1049: scanning through it for members which define symbols that have so far
1050: been referenced but not defined. But if the file that is found is an
1051: ordinary object file, it is linked in the usual fashion. The only
1052: difference between using an @samp{-l} option and specifying a file name
1053: is that @samp{-l} searches several directories.
1054:
1055: @item -L@var{dir}
1056: Add directory @var{dir} to the list of directories to be searched
1057: for @samp{-l}.
1058:
1059: @item -nostdlib
1.1.1.9 root 1060: Don't use the standard system libraries and startup files when linking.
1061: Only the files you specify will be passed to the linker.
1.1 root 1062:
1063: @item -m@var{machinespec}
1064: Machine-dependent option specifying something about the type of target
1065: machine. These options are defined by the macro
1066: @code{TARGET_SWITCHES} in the machine description. The default for
1067: the options is also defined by that macro, which enables you to change
1068: the defaults.@refill
1069:
1070: These are the @samp{-m} options defined in the 68000 machine
1071: description:
1072:
1073: @table @samp
1074: @item -m68020
1075: @itemx -mc68020
1076: Generate output for a 68020 (rather than a 68000). This is the
1077: default if you use the unmodified sources.
1078:
1079: @item -m68000
1080: @item -mc68000
1081: Generate output for a 68000 (rather than a 68020).
1082:
1083: @item -m68881
1084: Generate output containing 68881 instructions for floating point.
1085: This is the default if you use the unmodified sources.
1086:
1087: @item -mfpa
1088: Generate output containing Sun FPA instructions for floating point.
1089:
1090: @item -msoft-float
1091: Generate output containing library calls for floating point.
1092:
1093: @item -mshort
1094: Consider type @code{int} to be 16 bits wide, like @code{short int}.
1095:
1096: @item -mnobitfield
1097: Do not use the bit-field instructions. @samp{-m68000} implies
1098: @samp{-mnobitfield}.
1099:
1100: @item -mbitfield
1101: Do use the bit-field instructions. @samp{-m68020} implies
1102: @samp{-mbitfield}. This is the default if you use the unmodified
1103: sources.
1104:
1105: @item -mrtd
1106: Use a different function-calling convention, in which functions
1107: that take a fixed number of arguments return with the @code{rtd}
1108: instruction, which pops their arguments while returning. This
1109: saves one instruction in the caller since there is no need to pop
1110: the arguments there.
1111:
1112: This calling convention is incompatible with the one normally
1113: used on Unix, so you cannot use it if you need to call libraries
1114: compiled with the Unix compiler.
1115:
1116: Also, you must provide function prototypes for all functions that
1117: take variable numbers of arguments (including @code{printf});
1118: otherwise incorrect code will be generated for calls to those
1119: functions.
1120:
1121: In addition, seriously incorrect code will result if you call a
1122: function with too many arguments. (Normally, extra arguments are
1123: harmlessly ignored.)
1124:
1125: The @code{rtd} instruction is supported by the 68010 and 68020
1126: processors, but not by the 68000.
1127: @end table
1128:
1129: These @samp{-m} options are defined in the Vax machine description:
1130:
1131: @table @samp
1132: @item -munix
1133: Do not output certain jump instructions (@code{aobleq} and so on)
1134: that the Unix assembler for the Vax cannot handle across long
1135: ranges.
1136:
1137: @item -mgnu
1138: Do output those jump instructions, on the assumption that you
1139: will assemble with the GNU assembler.
1140:
1141: @item -mg
1142: Output code for g-format floating point numbers instead of d-format.
1143: @end table
1144:
1.1.1.5 root 1145: These @samp{-m} switches are supported on the Sparc:
1146:
1147: @table @samp
1148: @item -mfpu
1149: Generate output containing floating point instructions. This is the
1150: default if you use the unmodified sources.
1151:
1.1.1.9 root 1152: @ignore
1.1.1.5 root 1153: @item -msoft-float
1154: Generate output containing library calls for floating point.
1155:
1.1.1.9 root 1156: @end ignore
1.1.1.5 root 1157: @item -mno-epilogue
1.1.1.6 root 1158: Generate separate return instructions for @code{return} statements.
1159: This has both advantages and disadvantages; I don't recall what they
1160: are.
1.1.1.5 root 1161: @end table
1162:
1163: These @samp{-m} options are defined in the Convex machine description:
1164:
1165: @table @samp
1166: @item -mc1
1167: Generate output for a C1. This is the default when the compiler is
1168: configured for a C1.
1169:
1170: @item -mc2
1171: Generate output for a C2. This is the default when the compiler is
1172: configured for a C2.
1173:
1174: @item -margcount
1175: Generate code which puts an argument count in the word preceding each
1176: argument list. Some nonportable Convex and Vax programs need this
1177: word. (Debuggers don't; this info is in the symbol table.)
1178:
1179: @item -mnoargcount
1180: Omit the argument count word. This is the default if you use the
1181: unmodified sources.
1182: @end table
1183:
1.1 root 1184: @item -f@var{flag}
1.1.1.4 root 1185: Specify machine-independent flags. Most flags have both positive and
1186: negative forms; the negative form of @samp{-ffoo} would be
1187: @samp{-fno-foo}. In the table below, only one of the forms is
1188: listed---the one which is not the default. You can figure out the
1189: other form by either removing @samp{no-} or adding it.
1.1 root 1190:
1191: @table @samp
1.1.1.6 root 1192: @item -fpcc-struct-return
1193: Use the same convention for returning @code{struct} and @code{union}
1194: values that is used by the usual C compiler on your system. This
1195: convention is less efficient for small structures, and on many
1196: machines it fails to be reentrant; but it has the advantage of
1197: allowing intercallability between GCC-compiled code and PCC-compiled
1198: code.
1199:
1.1 root 1200: @item -ffloat-store
1201: Do not store floating-point variables in registers. This
1202: prevents undesirable excess precision on machines such as the
1203: 68000 where the floating registers (of the 68881) keep more
1204: precision than a @code{double} is supposed to have.
1205:
1206: For most programs, the excess precision does only good, but a few
1207: programs rely on the precise definition of IEEE floating point.
1208: Use @samp{-ffloat-store} for such programs.
1209:
1210: @item -fno-asm
1211: Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1.1.1.7 root 1212: keyword. These words may then be used as identifiers. You can
1.1.1.8 root 1213: use @code{__asm__}, @code{__inline__} and @code{__typeof__} instead.
1.1 root 1214:
1215: @item -fno-defer-pop
1216: Always pop the arguments to each function call as soon as that
1217: function returns. Normally the compiler (when optimizing) lets
1218: arguments accumulate on the stack for several function calls and
1219: pops them all at once.
1220:
1221: @item -fstrength-reduce
1222: Perform the optimizations of loop strength reduction and
1223: elimination of iteration variables.
1224:
1225: @item -fcombine-regs
1226: Allow the combine pass to combine an instruction that copies one
1227: register into another. This might or might not produce better
1228: code when used in addition to @samp{-O}. I am interested in
1229: hearing about the difference this makes.
1230:
1231: @item -fforce-mem
1232: Force memory operands to be copied into registers before doing
1233: arithmetic on them. This may produce better code by making all
1234: memory references potential common subexpressions. When they are
1235: not common subexpressions, instruction combination should
1236: eliminate the separate register-load. I am interested in hearing
1237: about the difference this makes.
1238:
1239: @item -fforce-addr
1240: Force memory address constants to be copied into registers before
1241: doing arithmetic on them. This may produce better code just as
1242: @samp{-fforce-mem} may. I am interested in hearing about the
1243: difference this makes.
1244:
1245: @item -fomit-frame-pointer
1246: Don't keep the frame pointer in a register for functions that
1247: don't need one. This avoids the instructions to save, set up and
1248: restore frame pointers; it also makes an extra register available
1249: in many functions. @strong{It also makes debugging impossible.}
1250:
1251: On some machines, such as the Vax, this flag has no effect,
1252: because the standard calling sequence automatically handles the
1253: frame pointer and nothing is saved by pretending it doesn't
1254: exist. The machine-description macro
1255: @code{FRAME_POINTER_REQUIRED} controls whether a target machine
1256: supports this flag. @xref{Registers}.@refill
1257:
1258: @item -finline-functions
1259: Integrate all simple functions into their callers. The compiler
1260: heuristically decides which functions are simple enough to be
1261: worth integrating in this way.
1262:
1263: If all calls to a given function are integrated, and the function
1264: is declared @code{static}, then the function is normally not
1265: output as assembler code in its own right.
1266:
1.1.1.6 root 1267: @item -fcaller-saves
1268: Enable values to be allocated in registers that will be clobbered by
1269: function calls, by emitting extra instructions to save and restore the
1270: registers around such calls. Such allocation is done only when it
1271: seems to result in better code than would otherwise be produced.
1272:
1273: This option is enabled by default on certain machines, usually those
1274: which have no call-preserved registers to use instead.
1275:
1.1.1.13 root 1276: Don't use @samp{-fcaller-saves} together with
1277: @samp{-fomit-frame-pointer}. This combination does not work.
1278:
1.1 root 1279: @item -fkeep-inline-functions
1280: Even if all calls to a given function are integrated, and the
1281: function is declared @code{static}, nevertheless output a
1282: separate run-time callable version of the function.
1283:
1284: @item -fwritable-strings
1.1.1.8 root 1285: Store string constants in the writable data segment and don't uniquize
1286: them. This is for compatibility with old programs which assume they can
1287: write into string constants. @samp{-traditional} also has this effect.
1288:
1289: Writing into string constants is a very bad idea; ``constants'' should
1290: be constant.
1.1 root 1291:
1.1.1.4 root 1292: @item -fcond-mismatch
1293: Allow conditional expressions with mismatched types in the second and
1294: third arguments. The value of such an expression is void.
1295:
1.1 root 1296: @item -fno-function-cse
1297: Do not put function addresses in registers; make each instruction
1298: that calls a constant function contain the function's address
1299: explicitly.
1300:
1301: This option results in less efficient code, but some strange
1302: hacks that alter the assembler output may be confused by the
1303: optimizations performed when this option is not used.
1304:
1305: @item -fvolatile
1306: Consider all memory references through pointers to be volatile.
1307:
1.1.1.4 root 1308: @item -fshared-data
1309: Requests that the data and non-@code{const} variables of this
1310: compilation be shared data rather than private data. The distinction
1311: makes sense only on certain operating systems, where shared data is
1312: shared between processes running the same program, while private data
1313: exists in one copy per process.
1314:
1.1 root 1315: @item -funsigned-char
1.1.1.4 root 1316: Let the type @code{char} be the unsigned, like @code{unsigned char}.
1.1 root 1317:
1318: Each kind of machine has a default for what @code{char} should
1319: be. It is either like @code{unsigned char} by default or like
1320: @code{signed char} by default. (Actually, at present, the
1321: default is always signed.)
1322:
1323: The type @code{char} is always a distinct type from either
1324: @code{signed char} or @code{unsigned char}, even though its
1325: behavior is always just like one of those two.
1326:
1.1.1.4 root 1327: Note that this is equivalent to @samp{-fno-signed-char}, which is the
1328: negative form of @samp{-fsigned-char}.
1329:
1.1 root 1330: @item -fsigned-char
1331: Let the type @code{char} be signed, like @code{signed char}.
1332:
1.1.1.4 root 1333: Note that this is equivalent to @samp{-fno-unsigned-char}, which is
1334: the negative form of @samp{-funsigned-char}.
1335:
1.1.1.8 root 1336: @item -fdelayed-branch
1337: If supported for the target machine, attempt to reorder instructions
1338: to exploit instruction slots available after delayed branch
1339: instructions.
1340:
1.1 root 1341: @item -ffixed-@var{reg}
1342: Treat the register named @var{reg} as a fixed register; generated
1343: code should never refer to it (except perhaps as a stack pointer,
1344: frame pointer or in some other fixed role).
1345:
1346: @var{reg} must be the name of a register. The register names
1347: accepted are machine-specific and are defined in the
1348: @code{REGISTER_NAMES} macro in the machine description macro
1349: file.
1350:
1.1.1.4 root 1351: This flag does not have a negative form, because it specifies a
1352: three-way choice.
1353:
1.1 root 1354: @item -fcall-used-@var{reg}
1355: Treat the register named @var{reg} as an allocatable register
1356: that is clobbered by function calls. It may be allocated for
1357: temporaries or variables that do not live across a call.
1358: Functions compiled this way will not save and restore the
1359: register @var{reg}.
1360:
1361: Use of this flag for a register that has a fixed pervasive role
1362: in the machine's execution model, such as the stack pointer or
1363: frame pointer, will produce disastrous results.
1364:
1.1.1.4 root 1365: This flag does not have a negative form, because it specifies a
1366: three-way choice.
1367:
1.1 root 1368: @item -fcall-saved-@var{reg}
1369: Treat the register named @var{reg} as an allocatable register
1370: saved by functions. It may be allocated even for temporaries or
1371: variables that live across a call. Functions compiled this way
1372: will save and restore the register @var{reg} if they use it.
1373:
1374: Use of this flag for a register that has a fixed pervasive role
1375: in the machine's execution model, such as the stack pointer or
1376: frame pointer, will produce disastrous results.
1377:
1378: A different sort of disaster will result from the use of this
1379: flag for a register in which function values may be returned.
1.1.1.4 root 1380:
1381: This flag does not have a negative form, because it specifies a
1382: three-way choice.
1.1 root 1383: @end table
1384:
1385: @item -d@var{letters}
1386: Says to make debugging dumps at times specified by @var{letters}.
1387: Here are the possible letters:
1388:
1389: @table @samp
1390: @item r
1391: Dump after RTL generation.
1392: @item j
1393: Dump after first jump optimization.
1394: @item s
1395: Dump after CSE (including the jump optimization that sometimes
1396: follows CSE).
1397: @item L
1398: Dump after loop optimization.
1399: @item f
1400: Dump after flow analysis.
1401: @item c
1402: Dump after instruction combination.
1403: @item l
1404: Dump after local register allocation.
1405: @item g
1406: Dump after global register allocation.
1.1.1.8 root 1407: @item d
1408: Dump after delayed branch scheduling.
1409: @item J
1410: Dump after last jump optimization.
1.1 root 1411: @item m
1412: Print statistics on memory usage, at the end of the run.
1413: @end table
1414:
1415: @item -pedantic
1416: Issue all the warnings demanded by strict ANSI standard C; reject
1417: all programs that use forbidden extensions.
1418:
1419: Valid ANSI standard C programs should compile properly with or without
1420: this option (though a rare few will require @samp{-ansi}). However,
1421: without this option, certain GNU extensions and traditional C features
1422: are supported as well. With this option, they are rejected. There is
1423: no reason to @i{use} this option; it exists only to satisfy pedants.
1.1.1.5 root 1424:
1.1.1.8 root 1425: @samp{-pedantic} does not cause warning messages for use of the
1426: alternate keywords whose names begin and end with @samp{__}.
1427: @xref{Alternate Keywords}.
1428:
1.1.1.5 root 1429: @item -static
1430: On Suns running version 4, this prevents linking with the shared
1431: libraries. (@samp{-g} has the same effect.)
1.1 root 1432: @end table
1433:
1434: These options control the C preprocessor, which is run on each C source
1435: file before actual compilation. If you use the @samp{-E} option, nothing
1436: is done except C preprocessing. Some of these options make sense only
1437: together with @samp{-E} because they request preprocessor output that is
1438: not suitable for actual compilation.
1439:
1440: @table @samp
1441: @item -C
1442: Tell the preprocessor not to discard comments. Used with the
1443: @samp{-E} option.
1444:
1445: @item -I@var{dir}
1446: Search directory @var{dir} for include files.
1447:
1448: @item -I-
1449: Any directories specified with @samp{-I} options before the @samp{-I-}
1450: option are searched only for the case of @samp{#include "@var{file}"};
1451: they are not searched for @samp{#include <@var{file}>}.
1452:
1453: If additional directories are specified with @samp{-I} options after
1454: the @samp{-I-}, these directories are searched for all @samp{#include}
1455: directives. (Ordinarily @emph{all} @samp{-I} directories are used
1456: this way.)
1457:
1458: In addition, the @samp{-I-} option inhibits the use of the current
1.1.1.8 root 1459: directory (where the current input file came from) as the first search
1460: directory for @samp{#include "@var{file}"}. There is no way to override
1461: this effect of @samp{-I-}. With @samp{-I.} you can specify searching
1462: the directory which was current when the compiler was invoked. That is
1463: not exactly the same as what the preprocessor does by default, but it is
1464: often satisfactory.
1465:
1466: @samp{-I-} does not inhibit the use of the standard system directories
1467: for header files. Thus, @samp{-I-} and @samp{-nostdinc} are
1468: independent.
1469:
1470: @item -i @var{file}
1471: Process @var{file} as input, discarding the resulting output, before
1472: processing the regular input file. Because the output generated from
1473: @var{file} is discarded, the only effect of @samp{-i @var{file}} is to
1474: make the macros defined in @var{file} available for use in the main
1475: input.
1.1 root 1476:
1477: @item -nostdinc
1478: Do not search the standard system directories for header files. Only
1479: the directories you have specified with @samp{-I} options (and the
1480: current directory, if appropriate) are searched.
1481:
1482: Between @samp{-nostdinc} and @samp{-I-}, you can eliminate all
1483: directories from the search path except those you specify.
1484:
1485: @item -M
1486: Tell the preprocessor to output a rule suitable for @code{make}
1.1.1.10 root 1487: describing the dependencies of each object file. For each source
1.1 root 1488: file, the preprocessor outputs one @code{make}-rule whose target is
1489: the object file name for that source file and whose dependencies are
1490: all the files @samp{#include}d in it. This rule may be a single line
1491: or may be continued with @samp{\}-newline if it is long.
1492:
1493: @samp{-M} implies @samp{-E}.
1494:
1495: @item -MM
1496: Like @samp{-M} but the output mentions only the user-header files
1497: included with @samp{#include "@var{file}"}. System header files
1498: included with @samp{#include <@var{file}>} are omitted.
1499:
1500: @samp{-MM} implies @samp{-E}.
1501:
1502: @item -D@var{macro}
1.1.1.8 root 1503: Define macro @var{macro} with the string @samp{1} as its definition.
1.1 root 1504:
1505: @item -D@var{macro}=@var{defn}
1506: Define macro @var{macro} as @var{defn}.
1507:
1508: @item -U@var{macro}
1509: Undefine macro @var{macro}.
1510:
1.1.1.7 root 1511: @item -trigraphs
1.1 root 1512: Support ANSI C trigraphs. You don't want to know about this
1513: brain-damage. The @samp{-ansi} option also has this effect.
1514: @end table
1515:
1516: @node Installation, Trouble, Options, Top
1517: @chapter Installing GNU CC
1518:
1519: Here is the procedure for installing GNU CC on a Unix system.
1.1.1.8 root 1520:
1.1 root 1521: @menu
1.1.1.8 root 1522: * Other Dir:: Compiling in a separate directory (not where the source is).
1523: * Sun Install:: See below for installation on the Sun.
1524: * 3B1 Install:: See below for installation on the 3B1.
1.1.1.11 root 1525: * SCO Install:: See below for installation on SCO System V 3.2. (Or ESIX.)
1.1 root 1526: * VMS Install:: See below for installation on VMS.
1.1.1.9 root 1527: * HPUX Install:: See below for installation on HPUX.
1.1.1.11 root 1528: * Tower Install:: See below for installation on an NCR Tower.
1.1 root 1529: @end menu
1530: @iftex
1.1.1.9 root 1531: See below for VMS systems, and modified procedures needed on Sun
1532: systems, 3b1 machines and HPUX. The following section says how to
1533: compile in a separate directory on Unix; here we assume you compile in
1534: the same directory that contains the source files.
1.1 root 1535: @end iftex
1536:
1537: @enumerate
1538: @item
1539: Edit @file{Makefile}. If you are using HPUX, or any form of system V,
1540: you must make a few changes described in comments at the beginning of
1.1.1.9 root 1541: the file. Genix requires changes also, and so does the Pyramid.
1.1 root 1542:
1543: @item
1544: On a Sequent system, go to the Berkeley universe.
1545:
1546: @item
1.1.1.2 root 1547: Choose configuration files. The easy way to do this is to run the
1.1.1.8 root 1548: command file @file{config.gcc} with a single argument, which specifies
1549: the type of machine (and in some cases which operating system).
1.1.1.4 root 1550:
1551: Here is a list of the possible arguments:
1552:
1553: @table @samp
1554: @item vax
1555: Vaxes running BSD.
1556: @item vms
1557: Vaxes running VMS.
1558: @item vax-sysv
1559: Vaxes running system V.
1560: @item i386-sysv
1561: Intel 386 PCs running system V.
1.1.1.5 root 1562: @item i386-sysv-gas
1563: Intel 386 PCs running system V, using the GNU assembler and GNU
1564: linker.
1.1.1.13 root 1565: @item i386-sysv4
1566: Intel 386 PCs running system V.4. You must run the shell script
1567: @file{fixincludes-V4} in order for GNU CC to work properly. You must
1568: also uncomment some lines in @file{Makefile}.
1.1.1.6 root 1569: @item sequent-i386
1.1.1.4 root 1570: Sequent with Intel 386 processors.
1.1.1.8 root 1571: @item i386-aix
1572: Intel 386 PCs or PS/2s running AIX.
1.1.1.4 root 1573: @item sun2
1574: Sun 2 running system version 2 or 3.
1575: @item sun3
1.1.1.12 root 1576: Sun 3 running system version 4, with 68881.
1.1.1.7 root 1577: Note there we do not provide a configuration file to use an FPA
1.1.1.8 root 1578: by default, because programs that establish signal handlers for
1.1.1.7 root 1579: floating point traps inherently cannot work with the FPA.
1.1.1.5 root 1580: @item sun3-nfp
1.1.1.12 root 1581: Sun 3 running system version 4, without 68881.
1.1.1.4 root 1582: @item sun4
1.1.1.12 root 1583: Sun 4 running system version 4. @xref{Incompatibilities},
1.1.1.8 root 1584: for calling convention incompatibilities on the Sun 4 (sparc).
1.1.1.4 root 1585: @item sun2-os4
1586: Sun 2 running system version 4.
1.1.1.12 root 1587: @item sun3-os3
1588: Sun 3 running system version 2 or 3, with 68881.
1589: @item sun3-nfp-os3
1590: Sun 3 running system version 2 or 3, without 68881.
1591: @item sun4-os3
1592: Sun 4 running system version 2 or 3. @xref{Incompatibilities},
1.1.1.8 root 1593: for calling convention incompatibilities on the Sun 4 (sparc).
1.1.1.4 root 1594: @item sun386
1595: Sun 386 (``roadrunner'').
1.1.1.5 root 1596: @item alliant
1.1.1.8 root 1597: Alliant FX/8 computer. Note that the standard installed C compiler in
1598: Concentrix 5.0 has a bug which prevent it from compiling GNU CC
1599: correctly. You can patch the compiler bug as follows:
1600:
1601: @example
1602: cp /bin/pcc ./pcc
1.1.1.9 root 1603: adb -w ./pcc - << EOF
1.1.1.8 root 1604: 15f6?w 6610
1605: EOF
1606: @end example
1607:
1608: Then you must use the @samp{-ip12} option when compiling GNU CC
1609: with the patched compiler, as shown here:
1610:
1611: @example
1612: make CC="./pcc -ip12" CFLAGS=-w
1613: @end example
1614:
1615: Note also that Alliant's version of DBX does not manage to work with the
1616: output from GNU CC.
1617: @item tahoe
1618: The tahoe computer (running BSD, and using DBX).
1619: @item decstation
1620: The DEC 3100 Mips machine (``pmax''). Note that GNU CC cannot generate
1621: debugging information in the unusual format used on the Mips.
1.1.1.13 root 1622: @item mips-sysv-os5
1623: The Mips computer, RS series, with the System V environment
1624: running on revision 5.00 of RISC-OS as default.
1625: Note that GNU CC cannot generate debugging information in the unusual
1626: format used on the Mips, and also cannot be used to create
1627: programs that use shared libraries.
1.1.1.8 root 1628: @item mips-sysv
1629: The Mips computer, RS series, with the System V environment as default.
1630: Note that GNU CC cannot generate debugging information in the unusual
1631: format used on the Mips.
1.1.1.13 root 1632: @item mips-bsd43-os5
1633: The Mips computer, RS series, with the BSD 4.3 environment
1634: running revision 5.00 of RISC-OS as default.
1635: Note that GNU CC cannot generate debugging information in the unusual
1636: format used on the Mips, and also cannot be used to create
1637: programs that use shared libraries.
1.1.1.8 root 1638: @item mips-bsd43
1639: The Mips computer, RS series, with the BSD 4.3 environment as default.
1640: Note that GNU CC cannot generate debugging information in the unusual
1641: format used on the Mips.
1.1.1.13 root 1642: @item mips-os5
1643: The Mips computer, M series running revision 5.00 of RISC-OS.
1644: Note that GNU CC cannot generate debugging information in the
1645: unusual format used on the Mips, and also cannot be used to
1646: create programs that use shared libraries.
1.1.1.7 root 1647: @item mips
1.1.1.8 root 1648: The Mips computer, M series. Note that GNU CC cannot generate debugging
1649: information in the unusual format used on the Mips.
1650: @item iris
1.1.1.10 root 1651: Another variant of the Mips computer, the Silicon Graphics Iris 4D.
1652: Note that GNU CC cannot generate debugging information in the unusual
1653: format used on the Mips.
1.1.1.5 root 1654: @item convex-c1
1.1.1.12 root 1655: Convex C1 computer. With operating system version 9, use @samp{cc -pcc}
1656: as the compilation command when building stage 1 of GNU CC.
1.1.1.5 root 1657: @item convex-c2
1.1.1.12 root 1658: Convex C2 computer. With operating system version 9, use @samp{cc -pcc}
1659: as the compilation command when building stage 1 of GNU CC.
1.1.1.8 root 1660: @item pyramid
1661: Pyramid computer.
1.1.1.4 root 1662: @item hp9k320
1.1.1.7 root 1663: HP 9000 series 300 using HPUX assembler. Note there is no
1664: support in GNU CC for HP's debugger; thus, @samp{-g} is not
1665: available in this configuration.
1.1.1.8 root 1666: @item hp9k320-gas
1.1.1.4 root 1667: HP 9000 series 300 using GNU assembler, linker and debugger.
1.1.1.7 root 1668: This requires the HP-adapt package, which is available along with
1669: the GNU linker as part of the ``binutils'' distribution.
1670: This is on the GNU CC distribution tape.
1.1.1.8 root 1671: @item hp9k320-old
1672: HP 9000 series 300 using HPUX assembler, in operating system versions
1673: older than 6.5. Note there is no support in GNU CC for HP's debugger;
1674: thus, @samp{-g} is not available in this configuration.
1675: @item hp9k320-bsd
1676: HP 9000 series 300 running BSD.
1.1.1.12 root 1677: @item hp9k200-bsd
1678: HP 9000 series 200 running BSD. Note that the C compiler that comes
1679: with this system cannot compile GNU CC; contact @code{law@@super.org} to
1680: get binaries of GNU CC for bootstrapping. Additionally, a minor patch
1681: is necessary if you wish to build kernels with GNU CC; contact
1682: @code{law@@super.org} to get a copy of the patch.
1.1.1.4 root 1683: @item isi68
1.1.1.8 root 1684: ISI 68000 or 68020 system with a 68881.
1685: @item isi68-nfp
1686: ISI 68000 or 68020 system without a 68881.
1.1.1.4 root 1687: @item news800
1688: Sony NEWS 68020 system.
1.1.1.6 root 1689: @item next
1690: NeXT system.
1.1.1.10 root 1691: @item tower
1692: NCR Tower 32 system.
1.1.1.7 root 1693: @item altos
1694: Altos 3068. Note that you must use the GNU assembler, linker and
1695: debugger, with COFF-encapsulation. Also, you must fix a kernel
1696: bug. Details in the file @file{ALTOS-README}.
1.1.1.4 root 1697: @item 3b1
1.1.1.8 root 1698: AT&T 3b1, a.k.a. 7300 PC. Note that special procedures are needed
1699: to compile GNU CC with this machine's standard C compiler, due to
1700: bugs in that compiler. @xref{3b1 Install}. You can bootstrap it
1701: more easily with previous versions of GNU CC if you have them.
1.1.1.9 root 1702: @item 3b1-gas
1703: AT&T 3b1 using the GNU assembler.
1.1.1.4 root 1704: @item sequent-ns32k
1705: Sequent containing ns32000 processors.
1706: @item encore
1707: Encore ns32000 system.
1708: @item genix
1709: National Semiconductor ns32000 system.
1710: @item 88000
1711: Motorola 88000 processor. This port is not finished.
1712: @end table
1.1.1.2 root 1713:
1.1.1.4 root 1714: Here we spell out what files need to be set up:
1.1 root 1715:
1716: @itemize @bullet
1717: @item
1718: Make a symbolic link named @file{config.h} to the top-level
1719: config file for the machine you are using (@pxref{Config}). This
1720: file is responsible for defining information about the host
1721: machine. It includes @file{tm.h}.
1722:
1.1.1.7 root 1723: The file is located in the subdirectory @file{config}. Its name
1724: should be @file{xm-@var{machine}.h}, with these exceptions:
1.1 root 1725:
1726: @table @file
1.1.1.3 root 1727: @item xm-vms.h
1.1 root 1728: for vaxen running VMS.
1.1.1.3 root 1729: @item xm-vaxv.h
1.1 root 1730: for vaxen running system V.
1.1.1.3 root 1731: @item xm-i386v.h
1.1 root 1732: for Intel 80386's running system V.
1.1.1.3 root 1733: @item xm-sun386i.h
1734: for Sun roadrunner running any version of the operating system.
1735: @item xm-hp9k320.h
1.1 root 1736: for the HP 9000 series 300.
1.1.1.4 root 1737: @item xm-genix.h
1.1 root 1738: for the ns32000 running Genix
1739: @end table
1740:
1741: If your system does not support symbolic links, you might want to
1742: set up @file{config.h} to contain a @samp{#include} command which
1743: refers to the appropriate file.
1744:
1745: @item
1746: Make a symbolic link named @file{tm.h} to the machine-description
1.1.1.7 root 1747: macro file for your machine. It should be in the subdirectory
1748: @file{config} and its name should be @file{tm-@var{machine}.h}.
1.1 root 1749:
1750: If your system is a 68000, don't use the file @file{tm-m68k.h}
1751: directly. Instead, use one of these files:
1752:
1753: @table @file
1754: @item tm-sun3.h
1.1.1.5 root 1755: for Sun 3 machines with 68881.
1756: @item tm-sun3-nfp.h
1757: for Sun 3 machines with no hardware floating point.
1.1.1.8 root 1758: @item tm-sun3os3.h
1759: for Sun 3 machines with 68881, running Sunos version 3.
1760: @item tm-sun3os3nf.h
1761: for Sun 3 machines with no hardware floating point, running Sunos
1762: version 3.
1.1 root 1763: @item tm-sun2.h
1764: for Sun 2 machines.
1765: @item tm-3b1.h
1766: for AT&T 3b1 (aka 7300 Unix PC).
1767: @item tm-isi68.h
1.1.1.3 root 1768: for Integrated Solutions systems. This file assumes you
1769: use the GNU assembler.
1.1.1.8 root 1770: @item tm-isi68-nfp.h
1771: for Integrated Solutions systems without a 68881. This file assumes you
1772: use the GNU assembler.
1.1 root 1773: @item tm-news800.h
1.1.1.8 root 1774: for Sony NEWS systems.
1.1 root 1775: @item tm-hp9k320.h
1776: for HPUX systems, if you are using GNU CC with the system's
1777: assembler and linker.
1778: @item tm-hp9k320g.h
1779: for HPUX systems, if you are using the GNU assembler, linker and
1780: other utilities. Not all of the pieces of GNU software needed
1781: for this mode of operation are as yet in distribution; full
1782: instructions will appear here in the future.@refill
1.1.1.10 root 1783: @item tm-tower-as.h
1784: for NCR Tower 32 systems, using the standard system assembler.
1.1 root 1785: @end table
1786:
1787: For the vax, use @file{tm-vax.h} on BSD Unix, @file{tm-vaxv.h} on
1788: system V, or @file{tm-vms.h} on VMS.@refill
1789:
1790: For the Motorola 88000, use @file{tm-m88k.h}. The support for the
1.1.1.9 root 1791: 88000 does not currently work; it requires extensive changes which
1792: we hope to reconcile in version 2.
1.1 root 1793:
1794: For the 80386, don't use @file{tm-i386.h} directly. Use
1795: @file{tm-i386v.h} if the target machine is running system V,
1.1.1.5 root 1796: @file{tm-i386gas.h} if it is running system V but you are using the
1797: GNU assembler and linker, @file{tm-seq386.h} for a Sequent 386 system,
1798: or @file{tm-compaq.h} for a Compaq, or @file{tm-sun386i.h} for a Sun
1799: 386 system.
1.1 root 1800:
1.1.1.8 root 1801: For the Mips computer, there are five choices: @file{tm-mips.h} for the
1802: M series, @file{tm-mips-bsd.h} for the RS series with BSD,
1803: @file{tm-mips-sysv.h} for the RS series with System V, @file{tm-iris.h}
1804: for the Iris version of the machine, and @file{tm-decstatn.h} for the
1805: Decstation.
1806:
1.1 root 1807: For the 32000, use @file{tm-sequent.h} if you are using a Sequent
1808: machine, or @file{tm-encore.h} for an Encore machine, or
1.1.1.4 root 1809: @file{tm-genix.h} if you are using Genix version 3; otherwise, perhaps
1.1 root 1810: @file{tm-ns32k.h} will work for you.
1811:
1812: Note that Genix has bugs in @code{alloca} and @code{malloc}; you must
1813: get the compiled versions of these from GNU Emacs and edit GNU CC's
1814: @file{Makefile} to use them.
1815:
1816: Note that Encore systems are supported only under BSD.
1817:
1.1.1.6 root 1818: For Sparc (Sun 4) machines, use @file{tm-sparc.h} with operating system
1819: version 4, and @file{tm-sun4os3.h} with system version 3.
1820:
1.1.1.10 root 1821: For Convex systems before version 8.1, use @file{tm-conv1os7.h} or
1822: @file{tm-conv2os7.h}. For versions 8.1 and greater, use @file{tm-convex1.h}
1823: or @file{tm-convex2.h}. You should also bootstrap GCC with @code{pcc}
1824: rather than @code{cc}; one way to do this is with the following commands.
1825:
1826: @example
1827: ln -s /bin/pcc ./cc
1828: set path = (. $path)
1829: @end example
1830:
1.1 root 1831: @item
1832: Make a symbolic link named @file{md} to the machine description
1.1.1.7 root 1833: pattern file. It should be in the @file{config} subdirectory and its
1834: name should be @file{@var{machine}.md}; but @var{machine} is often not
1835: the same as the name used in the @file{tm.h} file because the
1836: @file{md} files are more general.
1.1 root 1837:
1838: @item
1839: Make a symbolic link named @file{aux-output.c} to the output
1.1.1.7 root 1840: subroutine file for your machine. It should be in the @file{config}
1841: subdirectory and its name should be @file{out-@var{machine}.c}.
1.1 root 1842: @end itemize
1843:
1844: @item
1845: Make sure the Bison parser generator is installed. (This is
1846: unnecessary if the Bison output files @file{c-parse.tab.c} and
1847: @file{cexp.c} are more recent than @file{c-parse.y} and @file{cexp.y}
1848: and you do not plan to change the @samp{.y} files.)
1849:
1.1.1.9 root 1850: Bison versions older than Sept 8, 1988 will produce incorrect output
1.1 root 1851: for @file{c-parse.tab.c}.
1852:
1853: @item
1.1.1.10 root 1854: If you have a previous version of GCC installed, then chances are
1855: you can compile the new version with that. Do the following:
1856:
1857: @example
1858: make CC="gcc -O"
1859: @end example
1860:
1861: @noindent
1862: Since this produces an optimized executable right away, there is no need
1863: to bootstrap the result with itself except to test it. Therefore, you can
1864: skip directly to the @samp{make install} step below.
1865:
1866: @item
1.1 root 1867: Build the compiler. Just type @samp{make} in the compiler directory.
1868:
1.1.1.2 root 1869: Ignore any warnings you may see about ``statement not reached'' in the
1870: @file{insn-emit.c}; they are normal. Any other compilation errors may
1871: represent bugs in the port to your machine or operating system, and
1872: should be investigated and reported (@pxref{Bugs}).
1873:
1.1.1.9 root 1874: Some commercial compilers fail to compile GNU CC because they have bugs
1875: or limitations. For example, the Microsoft compiler is said to run out
1876: of macro space. Some Ultrix compilers run out of expression space; then
1877: you need to break up the statement where the problem happens.
1.1.1.7 root 1878:
1879: @item
1.1.1.5 root 1880: If you are using COFF-encapsulation, you must convert @file{gnulib} to
1881: a GNU-format library at this point. See the file @file{README-ENCAP}
1882: in the directory containing the GNU binary file utilities, for
1883: directions.
1884:
1885: @item
1.1 root 1886: Move the first-stage object files and executables into a subdirectory
1887: with this command:
1888:
1889: @example
1890: make stage1
1891: @end example
1892:
1893: The files are moved into a subdirectory named @file{stage1}.
1894: Once installation is complete, you may wish to delete these files
1895: with @code{rm -r stage1}.
1896:
1897: @item
1898: Recompile the compiler with itself, with this command:
1899:
1900: @example
1901: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/"
1902: @end example
1903:
1.1.1.10 root 1904: This is called making the stage 2 compiler.
1905:
1.1 root 1906: On a 68000 or 68020 system lacking floating point hardware,
1907: unless you have selected a @file{tm.h} file that expects by default
1908: that there is no such hardware, do this instead:
1909:
1910: @example
1911: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -msoft-float"
1912: @end example
1913:
1914: @item
1915: If you wish to test the compiler by compiling it with itself one more
1.1.1.7 root 1916: time, do this (in C shell):
1.1 root 1917:
1918: @example
1919: make stage2
1920: make CC=stage2/gcc CFLAGS="-g -O -Bstage2/"
1921: foreach file (*.o)
1922: cmp $file stage2/$file
1923: end
1924: @end example
1925:
1.1.1.7 root 1926: @noindent
1.1.1.10 root 1927: This is called making the stage 3 compiler. Aside from the @samp{-B}
1928: option, the options should be the same as when you made the stage 2
1929: compiler.
1.1 root 1930:
1.1.1.7 root 1931: The @code{foreach} command (written in C shell) will notify you if any of
1932: these stage 3 object files differs from those of stage 2. On BSD systems,
1933: any difference, no matter how innocuous, indicates that the stage 2
1934: compiler has compiled GNU CC incorrectly, and is therefore a potentially
1935: serious bug which you should investigate and report (@pxref{Bugs}).
1936:
1937: On systems that use COFF object files, bytes 5 to 8 will always be
1938: different, since it is a timestamp. On these systems, you can do the
1939: comparison as follows (in Bourne shell):
1940:
1941: @example
1942: for file in *.o; do
1943: echo $file
1.1.1.10 root 1944: tail +10c $file > foo1
1945: tail +10c stage2/$file > foo2
1.1.1.7 root 1946: cmp foo1 foo2
1947: done
1948: @end example
1949:
1.1.1.10 root 1950: On MIPS machines, you should use the shell script @file{ecoff-cmp}
1951: to compare two object files.
1952:
1.1 root 1953: @item
1954: Install the compiler driver, the compiler's passes and run-time support.
1955: You can use the following command:
1956:
1957: @example
1958: make install
1959: @end example
1960:
1961: @noindent
1.1.1.14! root 1962: On some machines, you will find that starts to recompile the @file{.c}
! 1963: files, due to a bug in Make. If that happens, cancel it and try again
! 1964: specifying the same values for Make variables that you used in the last
! 1965: compilation; that may not prevent the spurious recompilation, but will
! 1966: at least do it properly. For example:
! 1967:
! 1968: @example
! 1969: make CC=stage2/gcc CFLAGS="-g -O -Bstage2/" install
! 1970: @end example
! 1971:
! 1972: @noindent
! 1973: The @samp{install} target copies the files @file{cc1}, @file{cpp} and
! 1974: @file{gnulib} to files @file{gcc-cc1}, @file{gcc-cpp} and
! 1975: @file{gcc-gnulib} in directory @file{/usr/local/lib}, which is where the
! 1976: compiler driver program looks for them. It also copies the driver
! 1977: program @file{gcc} into the directory @file{/usr/local/bin}, so that it
! 1978: appears in typical execution search paths.@refill
1.1 root 1979:
1980: @strong{Warning: there is a bug in @code{alloca} in the Sun library.
1981: To avoid this bug, install the binaries of GNU CC that were compiled
1982: by GNU CC. They use @code{alloca} as a built-in function and never
1983: the one in the library.}
1984:
1985: @strong{Warning: the GNU CPP may not work for @file{ioctl.h},
1986: @file{ttychars.h} and other system header files unless the
1987: @samp{-traditional} option is used.} The bug is in the header files:
1988: at least on some machines, they rely on behavior that is incompatible
1989: with ANSI C. This behavior consists of substituting for macro
1990: argument names when they appear inside of character constants. The
1991: @samp{-traditional} option tells GNU CC to behave the way these
1992: headers expect.
1993:
1994: Because of this problem, you might prefer to configure GNU CC to use
1995: the system's own C preprocessor. To do so, make the file
1996: @file{/usr/local/lib/gcc-cpp} a link to @file{/lib/cpp}.
1997:
1998: Alternatively, on Sun systems and 4.3BSD at least, you can correct the
1999: include files by running the shell script @file{fixincludes}. This
2000: installs modified, corrected copies of the files @file{ioctl.h},
2001: @file{ttychars.h} and many others, in a special directory where only
1.1.1.2 root 2002: GNU CC will normally look for them. This script will work on various
1.1.1.6 root 2003: systems because it chooses the files by searching all the system
1.1.1.2 root 2004: headers for the problem cases that we know about.
1.1.1.10 root 2005:
2006: Use the following command to do this:
2007:
2008: @example
2009: make includes
2010: @end example
2011:
2012: @noindent
2013: If you selected a different directory for GNU CC installation when you
2014: installed it, by specifying the Make variable @code{prefix} or
2015: @code{libdir}, specify it the same way in this command.
2016:
2017: Note that some systems are starting to come with ANSI C system header
2018: files. On these systems, don't run @file{fixincludes}; it may not work,
2019: and is certainly not necessary.
1.1.1.12 root 2020:
2021: @strong{Warning:} @file{fixincludes} does not work on many MIPS systems,
2022: because those systems come with circular symbolic links which cause
1.1.1.14! root 2023: @samp{ls -lR} to go into an infinite loop. The same problem may occur
! 2024: on some versions of SunOS. If you encounter this problem, try using
! 2025: @file{fixinc.new} instead opf @code{fixincludes}.
1.1 root 2026: @end enumerate
2027:
2028: If you cannot install the compiler's passes and run-time support in
2029: @file{/usr/local/lib}, you can alternatively use the @samp{-B} option to
2030: specify a prefix by which they may be found. The compiler concatenates
2031: the prefix with the names @file{cpp}, @file{cc1} and @file{gnulib}.
2032: Thus, you can put the files in a directory @file{/usr/foo/gcc} and
2033: specify @samp{-B/usr/foo/gcc/} when you run GNU CC.
2034:
2035: Also, you can specify an alternative default directory for these files
2036: by setting the Make variable @code{libdir} when you make GNU CC.
2037:
1.1.1.8 root 2038: @node Other Dir, Sun Install, Installation, Installation
2039: @section Compilation in a Separate Directory
1.1 root 2040:
1.1.1.8 root 2041: If you wish to build the object files and executables in a directory
2042: other than the one containing the source files, here is what you must
2043: do differently:
2044:
2045: @enumerate
2046: @item
2047: Go to that directory before running @file{config.gcc}:
2048:
2049: @example
2050: mkdir gcc-sun3
2051: cd gcc-sun3
2052: @end example
1.1.1.4 root 2053:
1.1.1.8 root 2054: On systems that do not support symbolic links, this directory must be
2055: on the same file system as the source code directory.
2056:
2057: @item
2058: Specify where to find @file{config.gcc} when you run it:
2059:
2060: @example
2061: ../gcc-1.36/config.gcc @dots{}
2062: @end example
2063:
2064: @item
2065: Specify where to find the sources, as an argument to @file{config.gcc}:
2066:
2067: @example
2068: ../gcc-1.36/config.gcc -srcdir=../gcc-1.36 sun3
2069: @end example
2070:
2071: The @samp{-srcdir=@var{dir}} option is not needed when the source
2072: directory is the parent of the current directory, because
2073: @file{config.gcc} detects that case automatically.
2074: @end enumerate
2075:
2076: Now, you can run @code{make} in that directory. You need not repeat the
2077: configuration steps shown above, when ordinary source files change. You
2078: must, however, run @code{config.gcc} again when the configuration files
2079: change, if your system does not support symbolic links.
2080:
2081: @node Sun Install, 3b1 Install, Other Dir, Installation
2082: @section Installing GNU CC on the Sun
2083:
2084: Make sure the environment variable @code{FLOAT_OPTION} is not set when
2085: you compile @file{gnulib}. If this option were set to @code{f68881}
2086: when @file{gnulib} is compiled, the resulting code would demand to be
2087: linked with a special startup file and would not link properly without
2088: special pains.
2089:
2090: There is a bug in @code{alloca} in certain versions of the Sun library.
2091: To avoid this bug, install the binaries of GNU CC that were compiled by
2092: GNU CC. They use @code{alloca} as a built-in function and never the one
2093: in the library.
2094:
1.1.1.11 root 2095: Some versions of the Sun compiler crash when compiling GNU CC, with a
2096: segmentation fault in cpp. This can sometimes be due to the bulk of
2097: data in the environment variables. You may be able to avoid it by using
2098: the following command to compile GNU CC with Sun CC:
1.1.1.8 root 2099:
2100: @example
2101: make CC="TERMCAP=x OBJS=x LIBFUNCS=x STAGESTUFF=x cc"
2102: @end example
2103:
1.1.1.11 root 2104: Another problem that often happens on Suns is that you get a crash when
2105: building stage 2, when @code{genflags} is run.
2106:
2107: One reason for such as crash is if you configured GNU CC for the wrong
2108: version of SunOS. Starting with version 1.38, configurations @code{sun3}
2109: and @code{sun4} are for SunOS 4, so this problem should no longer happen.
2110:
2111: Another cause of the same symptom is having installed the GNU linker
2112: with an earlier version of SunOS. The version that worked before
2113: stopped working due to a change in the format of executables in SunOS
2114: 4.1. Many sites have installed the GNU linker as
2115: @file{/usr/local/lib/gcc-ld}, often as part of installing GNU C++. So
2116: if you get such crashes and you have used the proper configuration, try
2117: deleting @file{/usr/local/lib/gcc-ld}.
2118:
2119: The current version of the GNU linker, found in the current binutils
2120: release, does work with SunOS 4.1.
2121:
1.1.1.10 root 2122: @node 3b1 Install, SCO Install, Sun Install, Installation
1.1.1.8 root 2123: @section Installing GNU CC on the 3b1
2124:
2125: Installing GNU CC on the 3b1 is difficult if you do not already have
2126: GNU CC running, due to bugs in the installed C compiler. However,
2127: the following procedure might work. We are unable to test it.
1.1 root 2128:
2129: @enumerate
2130: @item
1.1.1.8 root 2131: Comment out the @samp{#include "config.h"} line on line 37 of
2132: @file{cccp.c} and do @samp{make cpp}. This makes a preliminary version
2133: of GNU cpp.
1.1 root 2134:
2135: @item
1.1.1.8 root 2136: Save the old @file{/lib/cpp} and copy the preliminary GNU cpp to that
2137: file name.
1.1.1.5 root 2138:
1.1.1.8 root 2139: @item
2140: Undo your change in @file{cccp.c}, or reinstall the original version,
2141: and do @samp{make cpp} again.
2142:
2143: @item
2144: Copy this final version of GNU cpp into @file{/lib/cpp}.
2145:
2146: @item
1.1.1.9 root 2147: Replace every occurrence of @code{obstack_free} in @file{tree.c}
1.1.1.8 root 2148: with @code{_obstack_free}.
2149:
2150: @item
2151: Run @code{make} to get the first-stage GNU CC.
2152:
2153: @item
2154: Reinstall the original version of @file{/lib/cpp}.
2155:
2156: @item
2157: Now you can compile GNU CC with itself and install it in the normal
2158: fashion.
1.1 root 2159: @end enumerate
2160:
1.1.1.9 root 2161: If you have installed an earlier version of GCC, you can compile the
2162: newer version with that. However, you will run into trouble compiling
2163: @file{gnulib}, since that is normally compiled with CC. To solve the
2164: problem, uncomment this line in @file{Makefile}:
2165:
2166: @example
2167: CCLIBFLAGS = -B/usr/local/lib/gcc- -tp -Wp,-traditional
2168: @end example
2169:
1.1.1.10 root 2170: @node SCO Install, VMS Install, 3B1 Install, Installation
2171: @section Installing GNU CC on SCO System V 3.2
2172: @cindex Installation on SCO systems
2173:
2174: The compiler that comes with this system does not work properly with
2175: @samp{-O}. Therefore, you should redefine the Make variable
2176: @code{CCLIBFLAGS} not to use @samp{-O}.
2177:
1.1.1.11 root 2178: You should also edit @file{Makefile} to enable the lines that set
2179: @code{CLIB} to @code{-lPW}, and the ones specifically labeled as being
2180: for SCO, that set @code{RANLIB}, and that set @code{CC} and @code{OLDCC}
1.1.1.13 root 2181: to @samp{rcc -Di386 -DM_UNIX -DM_I386 -DM_SYSV -DM_COFF}.
1.1.1.10 root 2182:
1.1.1.11 root 2183: Also, edit the definition of @code{USER_H} to remove the file @file{limits.h}.
1.1.1.10 root 2184:
1.1.1.11 root 2185: Then you can run @samp{config.gcc i386-sco} and finish building GNU CC
2186: normally.
1.1.1.10 root 2187:
1.1.1.13 root 2188: Note that the function @code{memmove} is broken in 3.2v2; it clobbers
2189: register @code{%ebx}. See the file @file{sco-memmove.s}.
2190:
1.1.1.11 root 2191: The same recipe should work on ESIX, but use @samp{config.gcc i386-esix}
2192: instead.
1.1.1.10 root 2193:
2194: @node VMS Install, HPUX Install, SCO Install, Installation
1.1.1.8 root 2195: @section Installing GNU CC on VMS
2196:
2197: The VMS version of GNU CC is distributed in a backup saveset containing
2198: both source code and precompiled binaries.
2199:
2200: To install the @file{gcc} command so you can use the compiler easily, in
1.1 root 2201: the same manner as you use the VMS C compiler, you must install the VMS CLD
2202: file for GNU CC as follows:
2203:
2204: @enumerate
2205: @item
2206: Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE}
2207: to point to the directories where the GNU CC executables
1.1.1.8 root 2208: (@file{gcc-cpp}, @file{gcc-cc1}, etc.) and the C include files are
1.1 root 2209: kept. This should be done with the commands:@refill
2210:
2211: @example
1.1.1.8 root 2212: $ assign /super /system disk:[gcc.] gnu_cc
2213: $ assign /super /system disk:[gcc.include.] gnu_cc_include
1.1 root 2214: @end example
2215:
2216: @noindent
2217: with the appropriate disk and directory names. These commands can be
2218: placed in your system startup file so they will be executed whenever
1.1.1.8 root 2219: the machine is rebooted. You may, if you choose, do this via the
2220: @file{GCC_INSTALL.COM} script in the @file{[GCC]} directory.
1.1 root 2221:
2222: @item
1.1.1.8 root 2223: Install the @file{GCC} command with the command line:
1.1 root 2224:
2225: @example
1.1.1.8 root 2226: $ set command /table=sys$library:dcltables gnu_cc:[000000]gcc
1.1 root 2227: @end example
2228:
1.1.1.7 root 2229: @item
2230: To install the help file, do the following:
2231:
2232: @example
2233: $ lib/help sys$library:helplib.hlb gcc.hlp
2234: @end example
2235:
1.1 root 2236: @noindent
2237: Now you can invoke the compiler with a command like @samp{gcc /verbose
2238: file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in
2239: Unix.
2240: @end enumerate
2241:
1.1.1.8 root 2242: We try to put corresponding binaries and sources on the VMS distribution
2243: tape. But sometimes the binaries will be from an older version that the
2244: sources, because we don't always have time to update them. (Use the
2245: @samp{/verbose} option to determine the version number of the binaries and
2246: compare it with the source file @file{version.c} to tell whether this is
2247: so.) In this case, you should use the binaries you get to recompile the
2248: sources. If you must recompile, here is how:
2249:
2250: @enumerate
2251: @item
2252: Copy the file @file{tm-vms.h} to @file{tm.h}, @file{xm-vms.h} to
2253: @file{config.h}, @file{vax.md} to @file{md.} and @file{out-vax.c}
2254: to @file{aux-output.c}. The files to be copied are found in the
2255: subdirectory named @file{config}; they should be copied to the
2256: main directory of GNU CC.@refill
2257:
2258: @item
2259: Setup the logical names and command tables as defined above. In
2260: addition, define the vms logical name @samp{GNU_BISON} to point at the
2261: to the directories where the Bison executable is kept. This should be
2262: done with the command:@refill
2263:
2264: @example
2265: $ assign /super /system disk:[bison.] gnu_bison
2266: @end example
2267:
2268: You may, if you choose, use the @file{INSTALL_BISON.COM} script in the
2269: @file{[BISON]} directory.
2270:
2271: @item
2272: Install the @samp{BISON} command with the command line:@refill
2273:
2274: @example
2275: $ set command /table=sys$library:dcltables gnu_bison:[000000]bison
2276: @end example
2277:
2278: @item
2279: Type @samp{@@make} to do recompile everything.
2280:
2281: If you are compiling with a version of GNU CC older than 1.33, specify
2282: @samp{/DEFINE=("inline=")} as an option in all the compilations. This
2283: requires editing all the @code{gcc} commands in @file{make-cc1.com}.
2284: (The older versions had problems supporting @code{inline}.) Once you
2285: have a working 1.33 or newer GNU CC, you can change this file back.
2286: @end enumerate
2287:
1.1.1.12 root 2288: Due to the differences between the filesystems of Unix and VMS, the
2289: preprocessor attempts to translate the names of include files into
2290: something that VMS will understand. The basic strategy is to prepend a
2291: prefix to the specification of the include file, convert the whole
2292: filename to a VMS filename, and then try to open the file. The
2293: preprocessor tries various prefixes until one of them succeeds.
2294:
2295: The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
2296: where GNU_C header files are traditionally stored. If a header file is
2297: not found there, @samp{SYS$SYSROOT:[SYSLIB.]} is tried next. If the
2298: preprocessor is still unable to locate the file, it then assumes that
2299: the include file specification is a valid VMS filename all by itself,
2300: and it uses this filename to attempt to open the include file. If none
2301: of these strategies succeeds, the preprocessor reports an error.
2302:
2303: If you wish to store header files in non-standard locations, then you
2304: can assign the logical @samp{GNU_CC_INCLUDE} to be a search list, where
2305: each element of the list is suitable for use with a rooted logical.
2306:
1.1.1.10 root 2307: With this version of GNU CC, @code{const} global variables now work
2308: properly. Unless, however, the @code{const} modifier is also specified
2309: in every external declaration of the variable in all of the source files
2310: that use that variable, the linker will issue warnings about conflicting
2311: attributes for the variable, since the linker does not know if the
2312: variable should be read-only. The program will still work, but the
2313: variable will be placed in writable storage.
2314:
1.1.1.12 root 2315: Due to an assembler bug, offsets to static constants are sometimes
2316: incorrectly evaluated. This bug is present in GAS 1.38.1, and should be
2317: fixed in the next version.
2318:
1.1.1.10 root 2319: Under previous versions of GNU CC, the generated code would occasionally
2320: give strange results when linked to the sharable @file{VAXCRTL} library.
2321: Now this should work.
2322:
1.1.1.12 root 2323: Even with this version, however, GNU CC itself should not be linked to the
2324: sharable @file{VAXCRTL}. The @file{qsort} routine supplied with @file{VAXCRTL}
2325: has a bug which can cause a compiler crash.
2326:
2327: Similarly, the preprocessor should not be linked to the sharable
2328: @file{VAXCRTL}. The @code{strncat} routine supplied with @file{VAXCRTL} has a
2329: bug which can cause the preprocessor to go into an infinite loop.
2330:
2331: It should be pointed out that if you attempt to link to the sharable
2332: @file{VAXCRTL}, the VMS linker will strongly resist any effort to force
2333: it to use the @code{qsort} and @code{strncat} routines from
2334: @file{gcclib}. Until the bugs in @file{VAXCRTL} have been fixed,
2335: linking any of the compiler components to the sharable VAXCRTL is not
2336: recommended. (These routines can be bypassed by placing duplicate copies
2337: of @code{qsort} and @code{strncat} in @file{gcclib} under different
2338: names, and patching the compiler sources to use these routines). Both
2339: of the bugs in @file{VAXCRTL} are still present in VMS version 5.4-1,
2340: which is the most recent version as of this writing.
2341:
2342: The executables that are generated by @file{make-cc1.com} and
2343: @file{make-cccp.com} use the non-shared version of @file{VAXCRTL} (and
2344: thus use the @code{qsort} and @code{strncat} routines from
2345: @file{gcclib.olb}).
1.1.1.10 root 2346:
2347: Note that GNU CC on VMS now generates debugging information to describe
2348: the programs symbols to the VMS debugger. However, you need version 1.37
2349: or later of GAS in order to output them properly in the object file.
1.1.1.7 root 2350:
1.1.1.12 root 2351: The VMS linker does not distinguish between upper and lower case letters
2352: in function and variable names. However, usual practice in C is to
2353: distinguish case. Normally GNU C (by means of the assembler GAS)
2354: implements usual C behavior by augmenting each name that is not all
2355: lower-case. A name is augmented by truncating it to at most 23
2356: characters and then adding more characters at the end which encode the
2357: case pattern the rest.
2358:
2359: Name augmentation yields bad results for programs that use precompiled
2360: libraries (such as Xlib) which were generated by another compiler. Use
2361: the compiler option @samp{/NOCASE_HACK} to inhibits augmentation; it
2362: makes external C functions and variables case-independent as is usual on
2363: VMS. Alternatively, you could write all references to the functions and
2364: variables in such libraries using lower case; this will work on VMS, but
2365: is not portable to other systems. In cases where you need to
2366: selectively inhibit augmentation, you can define a macro for each mixed
2367: case symbol for which you wish to inhibit augmentation, where the macro
2368: expands into the lower case equivalent of the name.
2369:
2370: @node HPUX Install, Tower Install, VMS Install, Installation
1.1.1.9 root 2371: @section Installing GNU CC on HPUX
2372:
2373: To install GNU CC on HPUX, you must start by editing the file
2374: @file{Makefile}. Search for the string @samp{HPUX} to find comments
2375: saying what to change. You need to change some variable definitions and
2376: (if you are using GAS) some lines in the rule for the target
2377: @samp{gnulib}.
2378:
1.1.1.10 root 2379: To avoid errors when linking programs with @samp{-g}, create an empty
2380: library named @file{libg.a}. An easy way to do this is:
2381:
2382: @example
2383: ar rc /usr/local/lib/libg.a
2384: @end example
2385:
1.1.1.9 root 2386: To compile with the HPUX C compiler, you must specify get the file
2387: @file{alloca.c} from GNU Emacs. Then, when you run @code{make}, use
2388: this argument:
2389:
2390: @example
2391: make ALLOCA=alloca.o
2392: @end example
2393:
2394: When recompiling GNU CC with itself, do not define @code{ALLOCA}.
2395: Instead, an @samp{-I} option needs to be added to @code{CFLAGS} as
2396: follows:
2397:
2398: @example
2399: make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -I../binutils/hp-include"
2400: @end example
2401:
1.1.1.12 root 2402: @node Tower Install,, HPUX Install, Installation
1.1.1.11 root 2403: @section Installing GNU CC on an NCR Tower
2404:
2405: On an NCR Tower model 4x0 or 6x0, you may have trouble because the
2406: default maximum virtual address size of a process is just 1 Mb. Most
2407: often you will find this problem while compiling GNU CC with itself.
2408:
2409: The only way to solve the problem is to reconfigure the kernel.
2410: Add a line such as this to the configuration file:
2411:
2412: @example
2413: MAXUMEM = 4096
2414: @end example
2415:
2416: @noindent
2417: and then relink the kernel and reboot the machine.
2418:
2419:
1.1.1.10 root 2420: @node Trouble, Service, Installation, Top
2421: @chapter Known Causes of Trouble with GNU CC
1.1 root 2422:
2423: Here are some of the things that have caused trouble for people installing
2424: or using GNU CC.
2425:
2426: @itemize @bullet
2427: @item
2428: On certain systems, defining certain environment variables such as
1.1.1.8 root 2429: @code{CC} can interfere with the functioning of @code{make}.
1.1 root 2430:
2431: @item
2432: Cross compilation can run into trouble for certain machines because
2433: some target machines' assemblers require floating point numbers to be
2434: written as @emph{integer} constants in certain contexts.
2435:
2436: The compiler writes these integer constants by examining the floating
2437: point value as an integer and printing that integer, because this is
2438: simple to write and independent of the details of the floating point
2439: representation. But this does not work if the compiler is running on
2440: a different machine with an incompatible floating point format, or
2441: even a different byte-ordering.
2442:
1.1.1.5 root 2443: In addition, correct constant folding of floating point values
2444: requires representing them in the target machine's format.
2445: (The C standard does not quite require this, but in practice
2446: it is the only way to win.)
2447:
2448: It is now possible to overcome these problems by defining macros such
2449: as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
2450: work for each target machine. @xref{Cross-compilation}.
1.1 root 2451:
2452: @item
1.1.1.2 root 2453: Users often think it is a bug when GNU CC reports an error for code
2454: like this:
2455:
2456: @example
2457: int foo (short);
2458:
2459: int foo (x)
2460: short x;
2461: @{@dots{}@}
2462: @end example
2463:
1.1.1.4 root 2464: The error message is correct: this code really is erroneous, because the
2465: old-style non-prototype definition passes subword integers in their
2466: promoted types. In other words, the argument is really an @code{int},
2467: not a @code{short}. The correct prototype is this:
1.1.1.2 root 2468:
2469: @example
2470: int foo (int);
2471: @end example
2472:
2473: @item
2474: Users often think it is a bug when GNU CC reports an error for code
2475: like this:
2476:
2477: @example
2478: int foo (struct mumble *);
2479:
2480: struct mumble @{ @dots{} @};
2481:
2482: int foo (struct mumble *x)
2483: @{ @dots{} @}
2484: @end example
2485:
2486: This code really is erroneous, because the scope of @code{struct
2487: mumble} the prototype is limited to the argument list containing it.
2488: It does not refer to the @code{struct mumble} defined with file scope
2489: immediately below---they are two unrelated types with similar names in
2490: different scopes.
2491:
2492: But in the definition of @code{foo}, the file-scope type is used
2493: because that is available to be inherited. Thus, the definition and
2494: the prototype do not match, and you get an error.
2495:
2496: This behavior may seem silly, but it's what the ANSI standard
2497: specifies. It is easy enough for you to make your code work by moving
2498: the definition of @code{struct mumble} above the prototype. I don't
2499: think it's worth being incompatible for.
1.1 root 2500: @end itemize
2501:
1.1.1.12 root 2502: Additional problems are described in @ref{Incompatibilities}.
2503:
1.1.1.10 root 2504: @node Service, Incompatibilities, Trouble, Top
2505: @chapter How To Get Help with GNU CC
2506:
2507: If you need help installing, using or changing GNU CC, there are two
2508: ways to find it:
2509:
2510: @itemize @bullet
2511: @item
2512: Send a message to a suitable network mailing list. First try
2513: @code{bug-gcc@@prep.ai.mit.edu}, and if that brings no response, try
1.1.1.12 root 2514: @code{help-gcc@@prep.ai.mit.edu}.
1.1.1.10 root 2515:
2516: @item
2517: Look in the service directory for someone who might help you for a fee.
2518: The service directory is found in the file named @file{SERVICE} in the
2519: GNU CC distribution.
2520: @end itemize
2521:
2522: @node Incompatibilities, Extensions, Service, Top
1.1 root 2523: @chapter Incompatibilities of GNU CC
2524:
2525: There are several noteworthy incompatibilities between GNU C and most
1.1.1.9 root 2526: existing (non-ANSI) versions of C. The @samp{-traditional} option
2527: eliminates most of these incompatibilities, @emph{but not all}, by
2528: telling GNU C to behave like older C compilers.
1.1 root 2529:
2530: @itemize @bullet
2531: @item
2532: GNU CC normally makes string constants read-only. If several
2533: identical-looking string constants are used, GNU CC stores only one
2534: copy of the string.
2535:
2536: One consequence is that you cannot call @code{mktemp} with a string
2537: constant argument. The function @code{mktemp} always alters the
2538: string its argument points to.
2539:
2540: Another consequence is that @code{sscanf} does not work on some
2541: systems when passed a string constant as its format control string.
2542: This is because @code{sscanf} incorrectly tries to write into the
1.1.1.4 root 2543: string constant. Likewise @code{fscanf} and @code{scanf}.
1.1 root 2544:
2545: The best solution to these problems is to change the program to use
2546: @code{char}-array variables with initialization strings for these
2547: purposes instead of string constants. But if this is not possible,
2548: you can use the @samp{-fwritable-strings} flag, which directs GNU CC
2549: to handle string constants the same way most C compilers do.
1.1.1.8 root 2550: @samp{-traditional} also has this effect, among others.
1.1 root 2551:
2552: @item
2553: GNU CC does not substitute macro arguments when they appear inside of
2554: string constants. For example, the following macro in GNU CC
2555:
2556: @example
2557: #define foo(a) "a"
2558: @end example
2559:
2560: @noindent
1.1.1.8 root 2561: will produce output @code{"a"} regardless of what the argument @var{a} is.
1.1 root 2562:
2563: The @samp{-traditional} option directs GNU CC to handle such cases
2564: (among others) in the old-fashioned (non-ANSI) fashion.
2565:
2566: @item
2567: When you use @code{setjmp} and @code{longjmp}, the only automatic
2568: variables guaranteed to remain valid are those declared
2569: @code{volatile}. This is a consequence of automatic register
2570: allocation. Consider this function:
2571:
2572: @example
2573: jmp_buf j;
2574:
2575: foo ()
2576: @{
2577: int a, b;
2578:
2579: a = fun1 ();
2580: if (setjmp (j))
2581: return a;
2582:
2583: a = fun2 ();
2584: /* @r{@code{longjmp (j)} may be occur in @code{fun3}.} */
2585: return a + fun3 ();
2586: @}
2587: @end example
2588:
2589: Here @code{a} may or may not be restored to its first value when the
2590: @code{longjmp} occurs. If @code{a} is allocated in a register, then
2591: its first value is restored; otherwise, it keeps the last value stored
2592: in it.
2593:
2594: If you use the @samp{-W} option with the @samp{-O} option, you will
2595: get a warning when GNU CC thinks such a problem might be possible.
2596:
1.1.1.2 root 2597: The @samp{-traditional} option directs GNU C to put variables in
2598: the stack by default, rather than in registers, in functions that
2599: call @code{setjmp}. This results in the behavior found in
2600: traditional C compilers.
2601:
1.1 root 2602: @item
2603: Declarations of external variables and functions within a block apply
2604: only to the block containing the declaration. In other words, they
2605: have the same scope as any other declaration in the same place.
2606:
2607: In some other C compilers, a @code{extern} declaration affects all the
2608: rest of the file even if it happens within a block.
2609:
2610: The @samp{-traditional} option directs GNU C to treat all @code{extern}
2611: declarations as global, like traditional compilers.
2612:
2613: @item
2614: In traditional C, you can combine @code{long}, etc., with a typedef name,
2615: as shown here:
2616:
2617: @example
2618: typedef int foo;
2619: typedef long foo bar;
2620: @end example
2621:
2622: In ANSI C, this is not allowed: @code{long} and other type modifiers
2623: require an explicit @code{int}. Because this criterion is expressed
2624: by Bison grammar rules rather than C code, the @samp{-traditional}
2625: flag cannot alter it.
2626:
2627: @item
2628: PCC allows typedef names to be used as function parameters. The
2629: difficulty described immediately above applies here too.
2630:
2631: @item
2632: PCC allows whitespace in the middle of compound assignment operators
2633: such as @samp{+=}. GNU CC, following the ANSI standard, does not
2634: allow this. The difficulty described immediately above applies here
2635: too.
2636:
2637: @item
2638: GNU CC will flag unterminated character constants inside of preprocessor
2639: conditionals that fail. Some programs have English comments enclosed in
2640: conditionals that are guaranteed to fail; if these comments contain
2641: apostrophes, GNU CC will probably report an error. For example,
2642: this code would produce an error:
2643:
2644: @example
2645: #if 0
2646: You can't expect this to work.
2647: #endif
2648: @end example
2649:
2650: The best solution to such a problem is to put the text into an actual
2651: C comment delimited by @samp{/*@dots{}*/}. However,
2652: @samp{-traditional} suppresses these error messages.
2653:
2654: @item
2655: When compiling functions that return @code{float}, PCC converts it to
2656: a double. GNU CC actually returns a @code{float}. If you are concerned
2657: with PCC compatibility, you should declare your functions to return
2658: @code{double}; you might as well say what you mean.
2659:
2660: @item
2661: When compiling functions that return structures or unions, GNU CC
1.1.1.6 root 2662: output code normally uses a method different from that used on most
2663: versions of Unix. As a result, code compiled with GNU CC cannot call
2664: a structure-returning function compiled with PCC, and vice versa.
1.1 root 2665:
1.1.1.6 root 2666: The method used by GNU CC is as follows: a structure or union which is 1,
1.1 root 2667: 2, 4 or 8 bytes long is returned like a scalar. A structure or union
2668: with any other size is stored into an address supplied by the caller
2669: in a special, fixed register.
2670:
2671: PCC usually handles all sizes of structures and unions by returning
2672: the address of a block of static storage containing the value. This
1.1.1.6 root 2673: method is not used in GNU CC because it is slower and nonreentrant.
1.1.1.5 root 2674:
1.1.1.6 root 2675: You can tell GNU CC to use the PCC convention with the option
2676: @samp{-fpcc-struct-return}.
1.1.1.12 root 2677: @end itemize
1.1.1.8 root 2678:
1.1.1.12 root 2679: There are also system-specific incompatibilities.
2680:
2681: @itemize @bullet
1.1.1.8 root 2682: @item
2683: On the Sparc, GNU CC uses an incompatible calling convention for
1.1.1.13 root 2684: structures and unions. It passes them by including their contents in
2685: the argument list, whereas the standard compiler passes them effectively
2686: by reference.
2687:
2688: This is hard to fix in GCC version 1. GNU CC version 2 will use a
2689: compatible calling convention.
2690:
2691: The convention for structure or union returning is also incompatible,
2692: and @samp{-fpcc-struct-return} does not help.
2693:
2694: System functions which can't be called properly from code compiled with
2695: GCC include @code{fetch}, @code{store}, @code{delete}, @code{firstkey},
2696: @code{nextkey}, @code{inet_makeaddr}, @code{inet_lnaof},
2697: @code{inet_netof}, @code{inet_ntoa}, @code{mallinfo},
2698: @code{pmap_rmtcall}, @code{clnt_call}, @code{clntudp_bufcreate} and
2699: @code{clntudp_create}.
1.1.1.8 root 2700:
1.1.1.13 root 2701: @item
2702: One consequence of the unusual calling convention used on the Sparc
2703: is that structures with less than word alignment do not work right
2704: when passed as arguments to varargs functions.
2705:
2706: It's not easy to fix this problem. In any case, it will be gone in
2707: version 2 as a result of the changed calling convention.
1.1.1.10 root 2708:
1.1.1.12 root 2709: @item
2710: The Sparc version of @code{setjmp} interacts badly with unexpected stack
2711: adjustments. With rare exceptions, you cannot use @code{setjmp} in a
2712: function which moves the stack pointer.
2713:
2714: In the current version of GNU CC, there are three ways that the stack
2715: pointer can change value: (1) calls to @code{alloca}, (2) use of
2716: variable-sized objects, and (3) calls to functions with parameters that
2717: do not all fit in the argument-passing registers (e.g., more than 6
2718: parameters). You should avoid all three in functions that call
2719: @code{setjmp}.
2720:
2721: The cause of the problem is the way that Sun implemented register
2722: windows. The 64 bytes at addresses @code{%sp} through @code{%sp+63}
2723: correspond to the register window save area. When a register window
2724: must be spilled, its stack pointer is located, and the registers are
2725: dumped starting at that address. Similarly, when a register window must
2726: be restored, its stack pointer is located, and the registers are
2727: restored from that address.
2728:
2729: When @code{setjmp} is called, the current register window's registers
2730: are saved into the register save area, and when @code{longjmp} is
2731: called, they are restored (actually, @emph{all} register windows are
2732: restored from all valid register windows at the time @code{longjmp} is
2733: called). If there is a change in the value of the stack pointer bewteen
2734: the @code{setjmp} and @code{longjmp} calls, when the registers are
2735: restored, they are restored with random values.
2736:
1.1.1.10 root 2737: @item
2738: On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
1.1.1.13 root 2739: by function calls. However, the C compiler uses conventions compatible
2740: with BSD Unix: registers 2 through 5 may be clobbered by function calls.
2741:
2742: GNU CC uses the same convention as the Ultrix C compiler. You can use
2743: these options to produce code compatible with the Fortran compiler:
1.1.1.10 root 2744:
2745: @example
2746: -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
2747: @end example
1.1.1.12 root 2748:
2749: @item
2750: DBX rejects some files produced by GNU CC, though it accepts similar
2751: constructs in output from PCC. Until someone can supply a coherent
2752: description of what is valid DBX input and what is not, there is
2753: nothing I can do about these problems. You are on your own.
1.1 root 2754: @end itemize
2755:
2756: @node Extensions, Bugs, Incompatibilities, Top
2757: @chapter GNU Extensions to the C Language
2758:
2759: GNU C provides several language features not found in ANSI standard C.
2760: (The @samp{-pedantic} option directs GNU CC to print a warning message if
2761: any of these features is used.) To test for the availability of these
2762: features in conditional compilation, check for a predefined macro
2763: @code{__GNUC__}, which is always defined under GNU CC.
2764:
2765: @menu
2766: * Statement Exprs:: Putting statements and declarations inside expressions.
2767: * Naming Types:: Giving a name to the type of some expression.
1.1.1.9 root 2768: * Typeof:: @code{typeof}: referring to the type of an expression.
2769: * Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues.
2770: * Conditionals:: Omitting the middle operand of a @samp{?:} expression.
2771: * Zero-Length:: Zero-length arrays.
2772: * Variable-Length:: Arrays whose length is computed at run time.
2773: * Subscripting:: Any array can be subscripted, even if not an lvalue.
2774: * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
2775: * Initializers:: Non-constant initializers.
2776: * Constructors:: Constructor expressions give structures, unions
2777: or arrays as values.
1.1.1.5 root 2778: * Function Attributes:: Declaring that functions have no side effects,
1.1.1.9 root 2779: or that they can never return.
1.1 root 2780: * Dollar Signs:: Dollar sign is allowed in identifiers.
2781: * Alignment:: Inquiring about the alignment of a type or variable.
2782: * Inline:: Defining inline functions (as fast as macros).
1.1.1.9 root 2783: * Extended Asm:: Assembler instructions with C expressions as operands.
2784: (With them you can define ``built-in'' functions.)
2785: * Asm Labels:: Specifying the assembler name to use for a C symbol.
1.1.1.8 root 2786: * Explicit Reg Vars:: Defining variables residing in specified registers.
2787: * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
1.1 root 2788: @end menu
2789:
2790: @node Statement Exprs, Naming Types, Extensions, Extensions
2791: @section Statements and Declarations inside of Expressions
2792:
2793: A compound statement in parentheses may appear inside an expression in GNU
2794: C. This allows you to declare variables within an expression. For
2795: example:
2796:
2797: @example
2798: (@{ int y = foo (); int z;
2799: if (y > 0) z = y;
2800: else z = - y;
2801: z; @})
2802: @end example
2803:
2804: @noindent
2805: is a valid (though slightly more complex than necessary) expression
2806: for the absolute value of @code{foo ()}.
2807:
2808: This feature is especially useful in making macro definitions ``safe'' (so
2809: that they evaluate each operand exactly once). For example, the
2810: ``maximum'' function is commonly defined as a macro in standard C as
2811: follows:
2812:
2813: @example
2814: #define max(a,b) ((a) > (b) ? (a) : (b))
2815: @end example
2816:
2817: @noindent
2818: But this definition computes either @var{a} or @var{b} twice, with bad
2819: results if the operand has side effects. In GNU C, if you know the
2820: type of the operands (here let's assume @code{int}), you can define
2821: the macro safely as follows:
2822:
2823: @example
2824: #define maxint(a,b) \
2825: (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
2826: @end example
2827:
2828: Embedded statements are not allowed in constant expressions, such as
2829: the value of an enumeration constant, the width of a bit field, or
2830: the initial value of a static variable.
2831:
2832: If you don't know the type of the operand, you can still do this, but you
2833: must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming
2834: Types}).
2835:
2836: @node Naming Types, Typeof, Statement Exprs, Extensions
2837: @section Naming an Expression's Type
2838:
2839: You can give a name to the type of an expression using a @code{typedef}
2840: declaration with an initializer. Here is how to define @var{name} as a
2841: type name for the type of @var{exp}:
2842:
2843: @example
2844: typedef @var{name} = @var{exp};
2845: @end example
2846:
2847: This is useful in conjunction with the statements-within-expressions
2848: feature. Here is how the two together can be used to define a safe
2849: ``maximum'' macro that operates on any arithmetic type:
2850:
2851: @example
2852: #define max(a,b) \
2853: (@{typedef _ta = (a), _tb = (b); \
2854: _ta _a = (a); _tb _b = (b); \
2855: _a > _b ? _a : _b; @})
2856: @end example
2857:
2858: The reason for using names that start with underscores for the local
2859: variables is to avoid conflicts with variable names that occur within the
2860: expressions that are substituted for @code{a} and @code{b}. Eventually we
2861: hope to design a new form of declaration syntax that allows you to declare
2862: variables whose scopes start only after their initializers; this will be a
2863: more reliable way to prevent such conflicts.
2864:
2865: @node Typeof, Lvalues, Naming Types, Extensions
2866: @section Referring to a Type with @code{typeof}
2867:
2868: Another way to refer to the type of an expression is with @code{typeof}.
2869: The syntax of using of this keyword looks like @code{sizeof}, but the
2870: construct acts semantically like a type name defined with @code{typedef}.
2871:
2872: There are two ways of writing the argument to @code{typeof}: with an
2873: expression or with a type. Here is an example with an expression:
2874:
2875: @example
2876: typeof (x[0](1))
2877: @end example
2878:
2879: @noindent
2880: This assumes that @code{x} is an array of functions; the type described
2881: is that of the values of the functions.
2882:
2883: Here is an example with a typename as the argument:
2884:
2885: @example
2886: typeof (int *)
2887: @end example
2888:
2889: @noindent
2890: Here the type described is that of pointers to @code{int}.
2891:
1.1.1.7 root 2892: If you are writing a header file that must work when included in ANSI C
1.1.1.8 root 2893: programs, write @code{__typeof__} instead of @code{typeof}.
1.1.1.7 root 2894: @xref{Alternate Keywords}.
2895:
1.1 root 2896: A @code{typeof}-construct can be used anywhere a typedef name could be
2897: used. For example, you can use it in a declaration, in a cast, or inside
2898: of @code{sizeof} or @code{typeof}.
2899:
2900: @itemize @bullet
2901: @item
2902: This declares @code{y} with the type of what @code{x} points to.
2903:
2904: @example
2905: typeof (*x) y;
2906: @end example
2907:
2908: @item
2909: This declares @code{y} as an array of such values.
2910:
2911: @example
2912: typeof (*x) y[4];
2913: @end example
2914:
2915: @item
2916: This declares @code{y} as an array of pointers to characters:
2917:
2918: @example
2919: typeof (typeof (char *)[4]) y;
2920: @end example
2921:
2922: @noindent
2923: It is equivalent to the following traditional C declaration:
2924:
2925: @example
2926: char *y[4];
2927: @end example
2928:
2929: To see the meaning of the declaration using @code{typeof}, and why it
2930: might be a useful way to write, let's rewrite it with these macros:
2931:
2932: @example
2933: #define pointer(T) typeof(T *)
2934: #define array(T, N) typeof(T [N])
2935: @end example
2936:
2937: @noindent
2938: Now the declaration can be rewritten this way:
2939:
2940: @example
2941: array (pointer (char), 4) y;
2942: @end example
2943:
2944: @noindent
1.1.1.8 root 2945: Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
1.1 root 2946: pointers to @code{char}.
2947: @end itemize
2948:
2949: @node Lvalues, Conditionals, Typeof, Extensions
2950: @section Generalized Lvalues
2951:
2952: Compound expressions, conditional expressions and casts are allowed as
2953: lvalues provided their operands are lvalues. This means that you can take
2954: their addresses or store values into them.
2955:
2956: For example, a compound expression can be assigned, provided the last
2957: expression in the sequence is an lvalue. These two expressions are
2958: equivalent:
2959:
2960: @example
2961: (a, b) += 5
2962: a, (b += 5)
2963: @end example
2964:
2965: Similarly, the address of the compound expression can be taken. These two
2966: expressions are equivalent:
2967:
2968: @example
2969: &(a, b)
2970: a, &b
2971: @end example
2972:
2973: A conditional expression is a valid lvalue if its type is not void and the
2974: true and false branches are both valid lvalues. For example, these two
2975: expressions are equivalent:
2976:
2977: @example
2978: (a ? b : c) = 5
2979: (a ? b = 5 : (c = 5))
2980: @end example
2981:
1.1.1.13 root 2982: A cast is a valid lvalue if its operand is an lvalue. A simple
2983: assignment whose left-hand side is a cast works by converting the
2984: right-hand side first to the specified type, then to the type of the
2985: inner left-hand side expression. After this is stored, the value is
2986: converted back to the specified type to become the value of the
2987: assignment. Thus, if @code{a} has type @code{char *}, the following two
2988: expressions are equivalent:
1.1 root 2989:
2990: @example
2991: (int)a = 5
1.1.1.13 root 2992: (int)(a = (char *)(int)5)
1.1 root 2993: @end example
2994:
2995: An assignment-with-arithmetic operation such as @samp{+=} applied to a cast
2996: performs the arithmetic using the type resulting from the cast, and then
2997: continues as in the previous case. Therefore, these two expressions are
2998: equivalent:
2999:
3000: @example
3001: (int)a += 5
1.1.1.13 root 3002: (int)(a = (char *)(int) ((int)a + 5))
3003: @end example
3004:
3005: You cannot take the address of an lvalue cast, because the use of its
3006: address would not work out coherently. Suppose that @code{&(int)f} were
3007: permitted, where @code{f} has type @code{float}. Then the following
3008: statement would try to store an integer bit-pattern where a floating
3009: point number belongs:
3010:
3011: @example
3012: *&(int)f = 1;
1.1 root 3013: @end example
3014:
1.1.1.13 root 3015: This is quite different from what @code{(int)f = 1} would do---that
3016: would convert 1 to floating point and store it. Rather than cause this
3017: inconsistancy, we think it is better to prohibit use of @samp{&} on a cast.
3018:
3019: If you really do want an @code{int *} pointer with the address of
3020: @code{f}, you can simply write @code{(int *)&f}.
3021:
1.1 root 3022: @node Conditionals, Zero-Length, Lvalues, Extensions
3023: @section Conditional Expressions with Omitted Middle-Operands
3024:
3025: The middle operand in a conditional expression may be omitted. Then
3026: if the first operand is nonzero, its value is the value of the conditional
3027: expression.
3028:
3029: Therefore, the expression
3030:
3031: @example
3032: x ? : y
3033: @end example
3034:
3035: @noindent
3036: has the value of @code{x} if that is nonzero; otherwise, the value of
3037: @code{y}.
3038:
3039: This example is perfectly equivalent to
3040:
3041: @example
3042: x ? x : y
3043: @end example
3044:
3045: @noindent
3046: In this simple case, the ability to omit the middle operand is not
3047: especially useful. When it becomes useful is when the first operand does,
3048: or may (if it is a macro argument), contain a side effect. Then repeating
3049: the operand in the middle would perform the side effect twice. Omitting
3050: the middle operand uses the value already computed without the undesirable
3051: effects of recomputing it.
3052:
3053: @node Zero-Length, Variable-Length, Conditionals, Extensions
3054: @section Arrays of Length Zero
3055:
3056: Zero-length arrays are allowed in GNU C. They are very useful as the last
3057: element of a structure which is really a header for a variable-length
3058: object:
3059:
3060: @example
3061: struct line @{
3062: int length;
3063: char contents[0];
3064: @};
3065:
3066: @{
3067: struct line *thisline
3068: = (struct line *) malloc (sizeof (struct line) + this_length);
3069: thisline->length = this_length;
3070: @}
3071: @end example
3072:
3073: In standard C, you would have to give @code{contents} a length of 1, which
3074: means either you waste space or complicate the argument to @code{malloc}.
3075:
3076: @node Variable-Length, Subscripting, Zero-Length, Extensions
3077: @section Arrays of Variable Length
3078:
3079: Variable-length automatic arrays are allowed in GNU C. These arrays are
3080: declared like any other automatic arrays, but with a length that is not a
3081: constant expression. The storage is allocated at that time and
3082: deallocated when the brace-level is exited. For example:
3083:
3084: @example
3085: FILE *concat_fopen (char *s1, char *s2, char *mode)
3086: @{
3087: char str[strlen (s1) + strlen (s2) + 1];
3088: strcpy (str, s1);
3089: strcat (str, s2);
3090: return fopen (str, mode);
3091: @}
3092: @end example
3093:
1.1.1.7 root 3094: You can also use variable-length arrays as arguments to functions:
1.1 root 3095:
3096: @example
3097: struct entry
1.1.1.7 root 3098: tester (int len, char data[len])
1.1 root 3099: @{
1.1.1.7 root 3100: @dots{}
1.1 root 3101: @}
3102: @end example
3103:
3104: The length of an array is computed on entry to the brace-level where the
3105: array is declared and is remembered for the scope of the array in case you
3106: access it with @code{sizeof}.
3107:
3108: Jumping or breaking out of the scope of the array name will also deallocate
3109: the storage. Jumping into the scope is not allowed; you will get an error
3110: message for it.
3111:
3112: You can use the function @code{alloca} to get an effect much like
3113: variable-length arrays. The function @code{alloca} is available in
3114: many other C implementations (but not in all). On the other hand,
3115: variable-length arrays are more elegant.
3116:
3117: There are other differences between these two methods. Space allocated
3118: with @code{alloca} exists until the containing @emph{function} returns.
3119: The space for a variable-length array is deallocated as soon as the array
3120: name's scope ends. (If you use both variable-length arrays and
3121: @code{alloca} in the same function, deallocation of a variable-length array
3122: will also deallocate anything more recently allocated with @code{alloca}.)
3123:
3124: @node Subscripting, Pointer Arith, Variable-Length, Extensions
3125: @section Non-Lvalue Arrays May Have Subscripts
3126:
3127: Subscripting is allowed on arrays that are not lvalues, even though the
3128: unary @samp{&} operator is not. For example, this is valid in GNU C though
3129: not valid in other C dialects:
3130:
3131: @example
3132: struct foo @{int a[4];@};
3133:
3134: struct foo f();
3135:
3136: bar (int index)
3137: @{
3138: return f().a[index];
3139: @}
3140: @end example
3141:
3142: @node Pointer Arith, Initializers, Subscripting, Extensions
3143: @section Arithmetic on @code{void}-Pointers and Function Pointers
3144:
3145: In GNU C, addition and subtraction operations are supported on pointers to
3146: @code{void} and on pointers to functions. This is done by treating the
3147: size of a @code{void} or of a function as 1.
3148:
3149: A consequence of this is that @code{sizeof} is also allowed on @code{void}
3150: and on function types, and returns 1.
3151:
1.1.1.8 root 3152: The option @samp{-Wpointer-arith} requests a warning if these extensions
3153: are used.
3154:
1.1 root 3155: @node Initializers, Constructors, Pointer Arith, Extensions
3156: @section Non-Constant Initializers
3157:
1.1.1.8 root 3158: The elements of an aggregate initializer for an automatic variable are
3159: not required to be constant expressions in GNU C. Here is an example of
3160: an initializer with run-time varying elements:
1.1 root 3161:
3162: @example
3163: foo (float f, float g)
3164: @{
3165: float beat_freqs[2] = @{ f-g, f+g @};
3166: @dots{}
3167: @}
3168: @end example
3169:
1.1.1.5 root 3170: @node Constructors, Function Attributes, Initializers, Extensions
1.1 root 3171: @section Constructor Expressions
3172:
3173: GNU C supports constructor expressions. A constructor looks like a cast
3174: containing an initializer. Its value is an object of the type specified in
3175: the cast, containing the elements specified in the initializer. The type
3176: must be a structure, union or array type.
3177:
3178: Assume that @code{struct foo} and @code{structure} are declared as shown:
3179:
3180: @example
3181: struct foo @{int a; char b[2];@} structure;
3182: @end example
3183:
3184: @noindent
1.1.1.8 root 3185: Here is an example of constructing a @code{struct foo} with a constructor:
1.1 root 3186:
3187: @example
3188: structure = ((struct foo) @{x + y, 'a', 0@});
3189: @end example
3190:
3191: @noindent
3192: This is equivalent to writing the following:
3193:
3194: @example
3195: @{
3196: struct foo temp = @{x + y, 'a', 0@};
3197: structure = temp;
3198: @}
3199: @end example
3200:
3201: You can also construct an array. If all the elements of the constructor
3202: are (made up of) simple constant expressions, suitable for use in
3203: initializers, then the constructor is an lvalue and can be coerced to a
3204: pointer to its first element, as shown here:
3205:
3206: @example
3207: char **foo = (char *[]) @{ "x", "y", "z" @};
3208: @end example
3209:
3210: Array constructors whose elements are not simple constants are not very
3211: useful, because the constructor is not an lvalue. There are only two valid
3212: ways to use it: to subscript it, or initialize an array variable with it.
3213: The former is probably slower than a @code{switch} statement, while the
3214: latter does the same thing an ordinary C initializer would do.
3215:
3216: @example
3217: output = ((int[]) @{ 2, x, 28 @}) [input];
3218: @end example
3219:
1.1.1.8 root 3220: @node Function Attributes, Dollar Signs, Constructors, Extensions
1.1.1.5 root 3221: @section Declaring Attributes of Functions
3222:
3223: In GNU C, you declare certain things about functions called in your program
3224: which help the compiler optimize function calls.
3225:
3226: A few functions, such as @code{abort} and @code{exit}, cannot return.
3227: These functions should be declared @code{volatile}. For example,
3228:
3229: @example
3230: extern volatile void abort ();
3231: @end example
3232:
3233: @noindent
3234: tells the compiler that it can assume that @code{abort} will not return.
3235: This makes slightly better code, but more importantly it helps avoid
3236: spurious warnings of uninitialized variables.
3237:
3238: Many functions do not examine any values except their arguments, and
3239: have no effects except the return value. Such a function can be subject
3240: to common subexpression elimination and loop optimization just as an
3241: arithmetic operator would be. These functions should be declared
3242: @code{const}. For example,
3243:
3244: @example
1.1.1.13 root 3245: extern const int square ();
1.1.1.5 root 3246: @end example
3247:
3248: @noindent
3249: says that the hypothetical function @code{square} is safe to call
3250: fewer times than the program says.
3251:
3252: Note that a function that has pointer arguments and examines the data
3253: pointed to must @emph{not} be declared @code{const}. Likewise, a
1.1.1.10 root 3254: function that calls a non-@code{const} function usually must not be
1.1.1.5 root 3255: @code{const}.
3256:
3257: Some people object to this feature, claiming that ANSI C's @code{#pragma}
3258: should be used instead. There are two reasons I did not do this.
3259:
3260: @enumerate
3261: @item
3262: It is impossible to generate @code{#pragma} commands from a macro.
3263:
3264: @item
3265: The @code{#pragma} command is just as likely as these keywords to mean
3266: something else in another compiler.
3267: @end enumerate
3268:
3269: These two reasons apply to @emph{any} application whatever: as far as
3270: I can see, @code{#pragma} is never useful.
3271:
3272: @node Dollar Signs, Alignment, Function Attributes, Extensions
1.1 root 3273: @section Dollar Signs in Identifier Names
3274:
3275: In GNU C, you may use dollar signs in identifier names. This is because
3276: many traditional C implementations allow such identifiers.
3277:
1.1.1.9 root 3278: Dollar signs are allowed if you specify @samp{-traditional}; they are
3279: not allowed if you specify @samp{-ansi}. Whether they are allowed by
3280: default depends on the target machine; usually, they are not.
3281:
1.1 root 3282: @node Alignment, Inline, Dollar Signs, Extensions
3283: @section Inquiring about the Alignment of a Type or Variable
3284:
1.1.1.8 root 3285: The keyword @code{__alignof__} allows you to inquire about how an object
1.1 root 3286: is aligned, or the minimum alignment usually required by a type. Its
3287: syntax is just like @code{sizeof}.
3288:
3289: For example, if the target machine requires a @code{double} value to be
1.1.1.8 root 3290: aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
3291: This is true on many RISC machines. On more traditional machine
3292: designs, @code{__alignof__ (double)} is 4 or even 2.
1.1 root 3293:
3294: Some machines never actually require alignment; they allow reference to any
1.1.1.8 root 3295: data type even at an odd addresses. For these machines, @code{__alignof__}
1.1 root 3296: reports the @emph{recommended} alignment of a type.
3297:
1.1.1.8 root 3298: When the operand of @code{__alignof__} is an lvalue rather than a type, the
1.1 root 3299: value is the largest alignment that the lvalue is known to have. It may
3300: have this alignment as a result of its data type, or because it is part of
3301: a structure and inherits alignment from that structure. For example, after
3302: this declaration:
3303:
3304: @example
3305: struct foo @{ int x; char y; @} foo1;
3306: @end example
3307:
3308: @noindent
1.1.1.8 root 3309: the value of @code{__alignof__ (foo1.y)} is probably 2 or 4, the same as
3310: @code{__alignof__ (int)}, even though the data type of @code{foo1.y}
3311: does not itself demand any alignment.@refill
1.1 root 3312:
3313: @node Inline, Extended Asm, Alignment, Extensions
3314: @section An Inline Function is As Fast As a Macro
3315:
3316: By declaring a function @code{inline}, you can direct GNU CC to integrate
3317: that function's code into the code for its callers. This makes execution
3318: faster by eliminating the function-call overhead; in addition, if any of
3319: the actual argument values are constant, their known values may permit
3320: simplifications at compile time so that not all of the inline function's
3321: code needs to be included.
3322:
3323: To declare a function inline, use the @code{inline} keyword in its
3324: declaration, like this:
3325:
3326: @example
3327: inline int
3328: inc (int *a)
3329: @{
3330: (*a)++;
3331: @}
3332: @end example
3333:
1.1.1.7 root 3334: (If you are writing a header file to be included in ANSI C programs, write
1.1.1.8 root 3335: @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.)
1.1.1.7 root 3336:
3337: You can also make all ``simple enough'' functions inline with the option
3338: @samp{-finline-functions}. Note that certain usages in a function
3339: definition can make it unsuitable for inline substitution.
1.1 root 3340:
3341: When a function is both inline and @code{static}, if all calls to the
1.1.1.8 root 3342: function are integrated into the caller, and the function's address is
3343: never used, then the function's own assembler code is never referenced.
3344: In this case, GNU CC does not actually output assembler code for the
3345: function, unless you specify the option @samp{-fkeep-inline-functions}.
3346: Some calls cannot be integrated for various reasons (in particular,
3347: calls that precede the function's definition cannot be integrated, and
3348: neither can recursive calls within the definition). If there is a
3349: nonintegrated call, then the function is compiled to assembler code as
3350: usual. The function must also be compiled as usual if the program
3351: refers to its address, because that can't be inlined.
1.1 root 3352:
3353: When an inline function is not @code{static}, then the compiler must assume
3354: that there may be calls from other source files; since a global symbol can
3355: be defined only once in any program, the function must not be defined in
3356: the other source files, so the calls therein cannot be integrated.
3357: Therefore, a non-@code{static} inline function is always compiled on its
3358: own in the usual fashion.
3359:
1.1.1.8 root 3360: If you specify both @code{inline} and @code{extern} in the function
3361: definition, then the definition is used only for inlining. In no case
3362: is the function compiled on its own, not even if you refer to its
3363: address explicitly. Such an address becomes an external reference, as
3364: if you had only declared the function, and had not defined it.
3365:
3366: This combination of @code{inline} and @code{extern} has almost the
3367: effect of a macro. The way to use it is to put a function definition in
3368: a header file with these keywords, and put another copy of the
3369: definition (lacking @code{inline} and @code{extern}) in a library file.
3370: The definition in the header file will cause most calls to the function
3371: to be inlined. If any uses of the function remain, they will refer to
3372: the single copy in the library.
3373:
1.1 root 3374: @node Extended Asm, Asm Labels, Inline, Extensions
3375: @section Assembler Instructions with C Expression Operands
3376:
3377: In an assembler instruction using @code{asm}, you can now specify the
3378: operands of the instruction using C expressions. This means no more
3379: guessing which registers or memory locations will contain the data you want
3380: to use.
3381:
3382: You must specify an assembler instruction template much like what appears
3383: in a machine description, plus an operand constraint string for each
3384: operand.
3385:
3386: For example, here is how to use the 68881's @code{fsinx} instruction:
3387:
3388: @example
3389: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
3390: @end example
3391:
3392: @noindent
3393: Here @code{angle} is the C expression for the input operand while
3394: @code{result} is that of the output operand. Each has @samp{"f"} as its
3395: operand constraint, saying that a floating-point register is required. The
1.1.1.5 root 3396: @samp{=} in @samp{=f} indicates that the operand is an output; all output
1.1.1.4 root 3397: operands' constraints must use @samp{=}. The constraints use the same
3398: language used in the machine description (@pxref{Constraints}).
1.1 root 3399:
3400: Each operand is described by an operand-constraint string followed by the C
3401: expression in parentheses. A colon separates the assembler template from
3402: the first output operand, and another separates the last output operand
3403: from the first input, if any. Commas separate output operands and separate
1.1.1.4 root 3404: inputs. The total number of operands is limited to the maximum number of
1.1 root 3405: operands in any instruction pattern in the machine description.
3406:
1.1.1.4 root 3407: If there are no output operands, and there are input operands, then there
3408: must be two consecutive colons surrounding the place where the output
3409: operands would go.
3410:
1.1 root 3411: Output operand expressions must be lvalues; the compiler can check this.
3412: The input operands need not be lvalues. The compiler cannot check whether
3413: the operands have data types that are reasonable for the instruction being
3414: executed. It does not parse the assembler instruction template and does
3415: not know what it means, or whether it is valid assembler input. The
3416: extended @code{asm} feature is most often used for machine instructions
3417: that the compiler itself does not know exist.
3418:
3419: The output operands must be write-only; GNU CC will assume that the values
3420: in these operands before the instruction are dead and need not be
1.1.1.8 root 3421: generated. Extended asm does not support input-output or read-write
3422: operands. For this reason, the constraint character @samp{+}, which
3423: indicates such an operand, may not be used.
3424:
3425: When the assembler instruction has a read-write operand, or an operand
3426: in which only some of the bits are to be changed, you must logically
1.1 root 3427: split its function into two separate operands, one input operand and one
3428: write-only output operand. The connection between them is expressed by
3429: constraints which say they need to be in the same location when the
1.1.1.8 root 3430: instruction executes. You can use the same C expression for both
3431: operands, or different expressions. For example, here we write the
3432: (fictitious) @samp{combine} instruction with @code{bar} as its read-only
3433: source operand and @code{foo} as its read-write destination:
1.1 root 3434:
3435: @example
3436: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
3437: @end example
3438:
3439: @noindent
3440: The constraint @samp{"0"} for operand 1 says that it must occupy the same
1.1.1.5 root 3441: location as operand 0. A digit in constraint is allowed only in an input
3442: operand, and it must refer to an output operand.
1.1 root 3443:
3444: Only a digit in the constraint can guarantee that one operand will be in
3445: the same place as another. The mere fact that @code{foo} is the value of
3446: both operands is not enough to guarantee that they will be in the same
3447: place in the generated assembler code. The following would not work:
3448:
3449: @example
3450: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
3451: @end example
3452:
3453: Various optimizations or reloading could cause operands 0 and 1 to be in
3454: different registers; GNU CC knows no reason not to do so. For example, the
3455: compiler might find a copy of the value of @code{foo} in one register and
3456: use it for operand 1, but generate the output operand 0 in a different
3457: register (copying it afterward to @code{foo}'s own address). Of course,
3458: since the register for operand 1 is not even mentioned in the assembler
3459: code, the result will not work, but GNU CC can't tell that.
3460:
3461: Unless an output operand has the @samp{&} constraint modifier, GNU CC may
3462: allocate it in the same register as an unrelated input operand, on the
3463: assumption that the inputs are consumed before the outputs are produced.
3464: This assumption may be false if the assembler code actually consists of
3465: more than one instruction. In such a case, use @samp{&} for each output
3466: operand that may not overlap an input. @xref{Modifiers}.
3467:
1.1.1.4 root 3468: Some instructions clobber specific hard registers. To describe this, write
3469: a third colon after the input operands, followed by the names of the
3470: clobbered hard registers (given as strings). Here is a realistic example
3471: for the vax:
1.1 root 3472:
3473: @example
3474: asm volatile ("movc3 %0,%1,%2"
3475: : /* no outputs */
3476: : "g" (from), "g" (to), "g" (count)
3477: : "r0", "r1", "r2", "r3", "r4", "r5");
3478: @end example
3479:
1.1.1.4 root 3480: You can put multiple assembler instructions together in a single @code{asm}
1.1.1.7 root 3481: template, separated either with newlines (written as @samp{\n}) or with
3482: semicolons if the assembler allows such semicolons. The GNU assembler
3483: allows semicolons and all Unix assemblers seem to do so. The input
3484: operands are guaranteed not to use any of the clobbered registers, and
3485: neither will the output operands' addresses, so you can read and write the
3486: clobbered registers as many times as you like. Here is an example of
3487: multiple instructions in a template; it assumes that the subroutine
3488: @code{_foo} accepts arguments in registers 9 and 10:
1.1.1.4 root 3489:
3490: @example
3491: asm ("movl %0,r9;movl %1,r10;call _foo"
3492: : /* no outputs */
3493: : "g" (from), "g" (to)
3494: : "r9", "r10");
3495: @end example
3496:
1.1.1.7 root 3497: If you want to test the condition code produced by an assembler instruction,
3498: you must include a branch and a label in the @code{asm} construct, as follows:
3499:
3500: @example
3501: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
3502: : "g" (result)
3503: : "g" (input));
3504: @end example
3505:
3506: @noindent
3507: This assumes your assembler supports local labels, as the GNU assembler
3508: and most Unix assemblers do.
3509:
1.1 root 3510: Usually the most convenient way to use these @code{asm} instructions is to
3511: encapsulate them in macros that look like functions. For example,
3512:
3513: @example
3514: #define sin(x) \
3515: (@{ double __value, __arg = (x); \
3516: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
3517: __value; @})
3518: @end example
3519:
3520: @noindent
3521: Here the variable @code{__arg} is used to make sure that the instruction
3522: operates on a proper @code{double} value, and to accept only those
3523: arguments @code{x} which can convert automatically to a @code{double}.
3524:
3525: Another way to make sure the instruction operates on the correct data type
3526: is to use a cast in the @code{asm}. This is different from using a
3527: variable @code{__arg} in that it converts more different types. For
3528: example, if the desired type were @code{int}, casting the argument to
3529: @code{int} would accept a pointer with no complaint, while assigning the
3530: argument to an @code{int} variable named @code{__arg} would warn about
3531: using a pointer unless the caller explicitly casts it.
3532:
1.1.1.4 root 3533: If an @code{asm} has output operands, GNU CC assumes for optimization
3534: purposes that the instruction has no side effects except to change the
3535: output operands. This does not mean that instructions with a side effect
3536: cannot be used, but you must be careful, because the compiler may eliminate
3537: them if the output operands aren't used, or move them out of loops, or
3538: replace two with one if they constitute a common subexpression. Also, if
3539: your instruction does have a side effect on a variable that otherwise
3540: appears not to change, the old value of the variable may be reused later if
3541: it happens to be found in a register.
1.1 root 3542:
3543: You can prevent an @code{asm} instruction from being deleted, moved or
3544: combined by writing the keyword @code{volatile} after the @code{asm}. For
3545: example:
3546:
3547: @example
3548: #define set_priority(x) \
3549: asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
3550: @end example
3551:
1.1.1.7 root 3552: @noindent
3553: (However, an instruction without output operands will not be deleted
3554: or moved, regardless, unless it is unreachable.)
1.1.1.4 root 3555:
1.1 root 3556: It is a natural idea to look for a way to give access to the condition
3557: code left by the assembler instruction. However, when we attempted to
3558: implement this, we found no way to make it work reliably. The problem
3559: is that output operands might need reloading, which would result in
3560: additional following ``store'' instructions. On most machines, these
3561: instructions would alter the condition code before there was time to
3562: test it. This problem doesn't arise for ordinary ``test'' and
3563: ``compare'' instructions because they don't have any output operands.
3564:
1.1.1.7 root 3565: If you are writing a header file that should be includable in ANSI C
1.1.1.8 root 3566: programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate
1.1.1.7 root 3567: Keywords}.
3568:
1.1.1.8 root 3569: @node Asm Labels, Explicit Reg Vars, Extended Asm, Extensions
1.1 root 3570: @section Controlling Names Used in Assembler Code
3571:
1.1.1.8 root 3572: You can specify the name to be used in the assembler code for a C
3573: function or variable by writing the @code{asm} (or @code{__asm__})
3574: keyword after the declarator as follows:
1.1 root 3575:
3576: @example
3577: int foo asm ("myfoo") = 2;
3578: @end example
3579:
3580: @noindent
3581: This specifies that the name to be used for the variable @code{foo} in
3582: the assembler code should be @samp{myfoo} rather than the usual
3583: @samp{_foo}.
3584:
3585: On systems where an underscore is normally prepended to the name of a C
3586: function or variable, this feature allows you to define names for the
3587: linker that do not start with an underscore.
3588:
3589: You cannot use @code{asm} in this way in a function @emph{definition}; but
3590: you can get the same effect by writing a declaration for the function
3591: before its definition and putting @code{asm} there, like this:
3592:
3593: @example
3594: extern func () asm ("FUNC");
3595:
3596: func (x, y)
3597: int x, y;
3598: @dots{}
3599: @end example
3600:
3601: It is up to you to make sure that the assembler names you choose do not
3602: conflict with any other assembler symbols. Also, you must not use a
3603: register name; that would produce completely invalid assembler code. GNU
3604: CC does not as yet have the ability to store static variables in registers.
3605: Perhaps that will be added.
3606:
1.1.1.8 root 3607: @node Explicit Reg Vars, Alternate Keywords, Asm Labels, Extensions
3608: @section Variables in Specified Registers
3609:
3610: GNU C allows you to put a few global variables into specified hardware
3611: registers. You can also specify the register in which an ordinary
3612: register variable should be allocated.
3613:
3614: @itemize @bullet
3615: @item
3616: Global register variables reserve registers throughout the program.
3617: This may be useful in programs such as programming language
3618: interpreters which have a couple of global variables that are accessed
3619: very often.
3620:
3621: @item
3622: Local register variables in specific registers do not reserve the
3623: registers. The compiler's data flow analysis is capable of
3624: determining where the specified registers contain live values, and
3625: where they are available for other uses. These local variables are
3626: sometimes convenient for use with the extended @code{asm} feature
3627: (@pxref{Extended Asm}).
3628: @end itemize
3629:
3630: @menu
3631: * Global Reg Vars::
3632: * Local Reg Vars::
3633: @end menu
1.1.1.5 root 3634:
1.1.1.8 root 3635: @node Global Reg Vars, Local Reg Vars, Explicit Reg Vars, Explicit Reg Vars
3636: @subsection Defining Global Register Variables
1.1.1.5 root 3637:
3638: You can define a global register variable in GNU C like this:
3639:
3640: @example
3641: register int *foo asm ("a5");
3642: @end example
3643:
3644: @noindent
3645: Here @code{a5} is the name of the register which should be used. Choose a
3646: register which is normally saved and restored by function calls on your
3647: machine, so that library routines will not clobber it.
3648:
3649: Naturally the register name is cpu-dependent, so you would need to
3650: conditionalize your program according to cpu type. The register
3651: @code{a5} would be a good choice on a 68000 for a variable of pointer
3652: type. On machines with register windows, be sure to choose a ``global''
1.1.1.8 root 3653: register that is not affected magically by the function call mechanism.
1.1.1.5 root 3654:
3655: In addition, operating systems on one type of cpu may differ in how they
3656: name the registers; then you would need additional conditionals. For
3657: example, some 68000 operating systems call this register @code{%a5}.
3658:
3659: Eventually there may be a way of asking the compiler to choose a register
3660: automatically, but first we need to figure out how it should choose and
1.1.1.6 root 3661: how to enable you to guide the choice. No solution is evident.
1.1.1.5 root 3662:
3663: Defining a global register variable in a certain register reserves that
3664: register entirely for this use, at least within the current compilation.
3665: The register will not be allocated for any other purpose in the functions
3666: in the current compilation. The register will not be saved and restored by
3667: these functions. Stores into this register are never deleted even if they
3668: would appear to be dead, but references may be deleted or moved or
3669: simplified.
3670:
3671: It is not safe to access the global register variables from signal
3672: handlers, or from more than one thread of control, because the system
3673: library routines may temporarily use the register for other things (unless
3674: you recompile them specially for the task at hand).
3675:
3676: It is not safe for one function that uses a global register variable to
3677: call another such function @code{foo} by way of a third function
3678: @code{lose} that was compiled without knowledge of this variable (i.e. in a
3679: different source file in which the variable wasn't declared). This is
3680: because @code{lose} might save the register and put some other value there.
3681: For example, you can't expect a global register variable to be available in
3682: the comparison-function that you pass to @code{qsort}, since @code{qsort}
3683: might have put something else in that register. (If you are prepared to
3684: recompile @code{qsort} with the same global register variable, you can
3685: solve this problem.)
3686:
3687: If you want to recompile @code{qsort} or other source files which do not
3688: actually use your global register variable, so that they will not use that
3689: register for any other purpose, then it suffices to specify the compiler
3690: option @samp{-ffixed-@var{reg}}. You need not actually add a global
3691: register declaration to their source code.
3692:
3693: A function which can alter the value of a global register variable cannot
3694: safely be called from a function compiled without this variable, because it
3695: could clobber the value the caller expects to find there on return.
3696: Therefore, the function which is the entry point into the part of the
3697: program that uses the global register variable must explicitly save and
3698: restore the value which belongs to its caller.
3699:
3700: On most machines, @code{longjmp} will restore to each global register
3701: variable the value it had at the time of the @code{setjmp}. On some
3702: machines, however, @code{longjmp} will not change the value of global
3703: register variables. To be portable, the function that called @code{setjmp}
3704: should make other arrangements to save the values of the global register
1.1.1.10 root 3705: variables, and to restore them in a @code{longjmp}. This way, the same
1.1.1.5 root 3706: thing will happen regardless of what @code{longjmp} does.
3707:
3708: All global register variable declarations must precede all function
3709: definitions. If such a declaration could appear after function
3710: definitions, the declaration would be too late to prevent the register from
3711: being used for other purposes in the preceding functions.
3712:
1.1.1.6 root 3713: Global register variables may not have initial values, because an
3714: executable file has no means to supply initial contents for a register.
3715:
1.1.1.9 root 3716: @node Local Reg Vars,, Global Reg Vars, Explicit Reg Vars
1.1.1.8 root 3717: @subsection Specifying Registers for Local Variables
3718:
3719: You can define a local register variable with a specified register
3720: like this:
3721:
3722: @example
3723: register int *foo asm ("a5");
3724: @end example
3725:
3726: @noindent
3727: Here @code{a5} is the name of the register which should be used. Note
3728: that this is the same syntax used for defining global register
3729: variables, but for a local variable it would appear within a function.
3730:
3731: Naturally the register name is cpu-dependent, but this is not a
3732: problem, since specific registers are most often useful with explicit
3733: assembler instructions (@pxref{Extended Asm}). Both of these things
3734: generally require that you conditionalize your program according to
3735: cpu type.
3736:
3737: In addition, operating systems on one type of cpu may differ in how they
3738: name the registers; then you would need additional conditionals. For
3739: example, some 68000 operating systems call this register @code{%a5}.
3740:
3741: Eventually there may be a way of asking the compiler to choose a register
3742: automatically, but first we need to figure out how it should choose and
3743: how to enable you to guide the choice. No solution is evident.
3744:
3745: Defining such a register variable does not reserve the register; it
1.1.1.10 root 3746: remains available for other uses in places where flow control determines
3747: the variable's value is not live. However, these registers are made
3748: unavailable for use in the reload pass. I would not be surprised if
3749: excessive use of this feature leaves the compiler too few available
1.1.1.8 root 3750: registers to compile certain functions.
3751:
3752: @node Alternate Keywords,, Explicit Reg Vars, Extensions
1.1.1.7 root 3753: @section Alternate Keywords
3754:
3755: The option @samp{-traditional} disables certain keywords; @samp{-ansi}
3756: disables certain others. This causes trouble when you want to use GNU C
3757: extensions, or ANSI C features, in a general-purpose header file that
3758: should be usable by all programs, including ANSI C programs and traditional
3759: ones. The keywords @code{asm}, @code{typeof} and @code{inline} cannot be
3760: used since they won't work in a program compiled with @samp{-ansi}, while
3761: the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof}
3762: and @code{inline} won't work in a program compiled with
3763: @samp{-traditional}.@refill
3764:
1.1.1.8 root 3765: The way to solve these problems is to put @samp{__} at the beginning and
3766: end of each problematical keyword. For example, use @code{__asm__}
3767: instead of @code{asm}, @code{__const__} instead of @code{const}, and
3768: @code{__inline__} instead of @code{inline}.
1.1.1.7 root 3769:
3770: Other C compilers won't accept these alternative keywords; if you want to
3771: compile with another compiler, you can define the alternate keywords as
3772: macros to replace them with the customary keywords. It looks like this:
3773:
3774: @example
3775: #ifndef __GNUC__
1.1.1.8 root 3776: #define __asm__ asm
1.1.1.7 root 3777: #endif
3778: @end example
3779:
1.1 root 3780: @node Bugs, Portability, Extensions, Top
3781: @chapter Reporting Bugs
3782:
3783: Your bug reports play an essential role in making GNU CC reliable.
3784:
1.1.1.11 root 3785: When you encounter a problem, the first thing to do is to see if it is
3786: already known. @xref{Trouble}. Also look in @ref{Incompatibilities}.
3787: If it isn't known, then you should report the problem.
3788:
3789: Reporting a bug may help you by bringing a solution to your problem, or
3790: it may not. (If it does not, look in the service directory; see
3791: @ref{Service}.) In any case, the principal function of a bug report
3792: is to help the entire community by making the next version of GNU CC
3793: work better. Bug reports are your contribution to the maintenance of
3794: GNU CC.
1.1 root 3795:
3796: In order for a bug report to serve its purpose, you must include the
3797: information that makes for fixing the bug.
3798:
3799: @menu
3800: * Criteria: Bug Criteria. Have you really found a bug?
3801: * Reporting: Bug Reporting. How to report a bug effectively.
3802: @end menu
3803:
3804: @node Bug Criteria, Bug Reporting, Bugs, Bugs
3805: @section Have You Found a Bug?
3806:
3807: If you are not sure whether you have found a bug, here are some guidelines:
3808:
3809: @itemize @bullet
3810: @item
3811: If the compiler gets a fatal signal, for any input whatever, that is a
3812: compiler bug. Reliable compilers never crash.
3813:
3814: @item
3815: If the compiler produces invalid assembly code, for any input whatever
3816: (except an @code{asm} statement), that is a compiler bug, unless the
3817: compiler reports errors (not just warnings) which would ordinarily
3818: prevent the assembler from being run.
3819:
3820: @item
3821: If the compiler produces valid assembly code that does not correctly
3822: execute the input source code, that is a compiler bug.
3823:
3824: However, you must double-check to make sure, because you may have run
3825: into an incompatibility between GNU C and traditional C
3826: (@pxref{Incompatibilities}). These incompatibilities might be considered
3827: bugs, but they are inescapable consequences of valuable features.
3828:
3829: Or you may have a program whose behavior is undefined, which happened
3830: by chance to give the desired results with another C compiler.
3831:
3832: For example, in many nonoptimizing compilers, you can write @samp{x;}
3833: at the end of a function instead of @samp{return x;}, with the same
1.1.1.8 root 3834: results. But the value of the function is undefined if @code{return}
1.1 root 3835: is omitted; it is not a bug when GNU CC produces different results.
3836:
3837: Problems often result from expressions with two increment operators,
1.1.1.8 root 3838: as in @code{f (*p++, *p++)}. Your previous compiler might have
1.1 root 3839: interpreted that expression the way you intended; GNU CC might
1.1.1.8 root 3840: interpret it another way. Neither compiler is wrong. The bug is
3841: in your code.
1.1 root 3842:
3843: After you have localized the error to a single source line, it should
3844: be easy to check for these things. If your program is correct and
3845: well defined, you have found a compiler bug.
3846:
3847: @item
3848: If the compiler produces an error message for valid input, that is a
3849: compiler bug.
3850:
3851: Note that the following is not valid input, and the error message for
3852: it is not a bug:
3853:
3854: @example
3855: int foo (char);
3856:
3857: int
3858: foo (x)
3859: char x;
3860: @{ @dots{} @}
3861: @end example
3862:
3863: @noindent
3864: The prototype says to pass a @code{char}, while the definition says to
3865: pass an @code{int} and treat the value as a @code{char}. This is what
3866: the ANSI standard says, and it makes sense.
3867:
3868: @item
3869: If the compiler does not produce an error message for invalid input,
3870: that is a compiler bug. However, you should note that your idea of
3871: ``invalid input'' might be my idea of ``an extension'' or ``support
3872: for traditional practice''.
3873:
3874: @item
3875: If you are an experienced user of C compilers, your suggestions
3876: for improvement of GNU CC are welcome in any case.
3877: @end itemize
3878:
3879: @node Bug Reporting,, Bug Criteria, Bugs
3880: @section How to Report Bugs
3881:
3882: Send bug reports for GNU C to one of these addresses:
3883:
3884: @example
3885: bug-gcc@@prep.ai.mit.edu
3886: @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gcc
3887: @end example
3888:
1.1.1.12 root 3889: @strong{Do not send bug reports to @samp{help-gcc}, or to the newsgroup
3890: @samp{gnu.gcc.help}.} Most users of GNU CC do not want to receive bug
1.1.1.8 root 3891: reports. Those that do, have asked to be on @samp{bug-gcc}.
3892:
3893: The mailing list @samp{bug-gcc} has a newsgroup which serves as a
3894: repeater. The mailing list and the newsgroup carry exactly the same
3895: messages. Often people think of posting bug reports to the newsgroup
3896: instead of mailing them. This appears to work, but it has one problem
3897: which can be crucial: a newsgroup posting does not contain a mail path
3898: back to the sender. Thus, if I need to ask for more information, I
3899: may be unable to reach you. For this reason, it is better to send bug
3900: reports to the mailing list.
3901:
3902: As a last resort, send bug reports on paper to:
1.1 root 3903:
3904: @example
3905: GNU Compiler Bugs
1.1.1.12 root 3906: Free Software Foundation
3907: 675 Mass Ave
1.1 root 3908: Cambridge, MA 02139
3909: @end example
3910:
3911: The fundamental principle of reporting bugs usefully is this:
1.1.1.8 root 3912: @strong{report all the facts}. If you are not sure whether to state a
3913: fact or leave it out, state it!
1.1 root 3914:
3915: Often people omit facts because they think they know what causes the
3916: problem and they conclude that some details don't matter. Thus, you might
3917: assume that the name of the variable you use in an example does not matter.
3918: Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
3919: stray memory reference which happens to fetch from the location where that
3920: name is stored in memory; perhaps, if the name were different, the contents
3921: of that location would fool the compiler into doing the right thing despite
1.1.1.8 root 3922: the bug. Play it safe and give a specific, complete example. That is the
3923: easiest thing for you to do, and the most helpful.
1.1 root 3924:
1.1.1.8 root 3925: Keep in mind that the purpose of a bug report is to enable me to fix
3926: the bug if it is not known. It isn't very important what happens if
3927: the bug is already known. Therefore, always write your bug reports on
3928: the assumption that the bug is not known.
3929:
3930: Sometimes people give a few sketchy facts and ask, ``Does this ring a
3931: bell?'' Those bug reports are useless, and I urge everyone to
3932: @emph{refuse to respond to them} except to chide the sender to report
3933: bugs properly.
3934:
3935: To enable me to fix the bug, you should include all these things:
1.1 root 3936:
3937: @itemize @bullet
3938: @item
3939: The version of GNU CC. You can get this by running it with the
3940: @samp{-v} option.
3941:
3942: Without this, I won't know whether there is any point in looking for
3943: the bug in the current version of GNU CC.
3944:
3945: @item
3946: A complete input file that will reproduce the bug. If the bug is in
3947: the C preprocessor, send me a source file and any header files that it
3948: requires. If the bug is in the compiler proper (@file{cc1}), run your
3949: source file through the C preprocessor by doing @samp{gcc -E
3950: @var{sourcefile} > @var{outfile}}, then include the contents of
3951: @var{outfile} in the bug report. (Any @samp{-I}, @samp{-D} or
3952: @samp{-U} options that you used in actual compilation should also be
3953: used when doing this.)
3954:
3955: A single statement is not enough of an example. In order to compile
3956: it, it must be embedded in a function definition; and the bug might
3957: depend on the details of how this is done.
3958:
3959: Without a real example I can compile, all I can do about your bug
3960: report is wish you luck. It would be futile to try to guess how to
3961: provoke the bug. For example, bugs in register allocation and
3962: reloading frequently depend on every little detail of the function
3963: they happen in.
3964:
3965: @item
3966: The command arguments you gave GNU CC to compile that example and
3967: observe the bug. For example, did you use @samp{-O}? To guarantee
3968: you won't omit something important, list them all.
3969:
3970: If I were to try to guess the arguments, I would probably guess wrong
3971: and then I would not encounter the bug.
3972:
3973: @item
3974: The names of the files that you used for @file{tm.h} and @file{md}
3975: when you installed the compiler.
3976:
3977: @item
3978: The type of machine you are using, and the operating system name and
3979: version number.
3980:
3981: @item
3982: A description of what behavior you observe that you believe is
3983: incorrect. For example, ``It gets a fatal signal,'' or, ``There is an
3984: incorrect assembler instruction in the output.''
3985:
3986: Of course, if the bug is that the compiler gets a fatal signal, then I
3987: will certainly notice it. But if the bug is incorrect output, I might
3988: not notice unless it is glaringly wrong. I won't study all the
3989: assembler code from a 50-line C program just on the off chance that it
3990: might be wrong.
3991:
3992: Even if the problem you experience is a fatal signal, you should still
3993: say so explicitly. Suppose something strange is going on, such as,
3994: your copy of the compiler is out of synch, or you have encountered a
3995: bug in the C library on your system. (This has happened!) Your copy
3996: might crash and mine would not. If you @i{told} me to expect a crash,
3997: then when mine fails to crash, I would know that the bug was not
3998: happening for me. If you had not told me to expect a crash, then I
3999: would not be able to draw any conclusion from my observations.
4000:
1.1.1.8 root 4001: Often the observed symptom is incorrect output when your program is run.
4002: Sad to say, this is not enough information for me unless the program is
4003: short and simple. If you send me a large program, I don't have time to
4004: figure out how it would work if compiled correctly, much less which line
4005: of it was compiled wrong. So you will have to do that. Tell me which
4006: source line it is, and what incorrect result happens when that line is
4007: executed. A person who understands the test program can find this as
4008: easily as a bug in the program itself.
1.1 root 4009:
4010: @item
4011: If you send me examples of output from GNU CC, please use @samp{-g}
4012: when you make them. The debugging information includes source line
4013: numbers which are essential for correlating the output with the input.
4014:
4015: @item
4016: If you wish to suggest changes to the GNU CC source, send me context
4017: diffs. If you even discuss something in the GNU CC source, refer to
4018: it by context, not by line number.
4019:
4020: The line numbers in my development sources don't match those in your
4021: sources. Your line numbers would convey no useful information to me.
4022:
4023: @item
4024: Additional information from a debugger might enable me to find
4025: a problem on a machine which I do not have available myself.
4026: However, you need to think when you collect this information if
4027: you want it to have any chance of being useful.
4028:
4029: For example, many people send just a backtrace, but that is never
4030: useful by itself. A simple backtrace with arguments conveys little
4031: about GNU CC because the compiler is largely data-driven; the same
4032: functions are called over and over for different RTL insns, doing
4033: different things depending on the details of the insn.
4034:
4035: Most of the arguments listed in the backtrace are useless because they
4036: are pointers to RTL list structure. The numeric values of the
4037: pointers, which the debugger prints in the backtrace, have no
4038: significance whatever; all that matters is the contents of the objects
4039: they point to (and most of the contents are other such pointers).
4040:
4041: In addition, most compiler passes consist of one or more loops that
4042: scan the RTL insn sequence. The most vital piece of information about
1.1.1.8 root 4043: such a loop---which insn it has reached---is usually in a local variable,
1.1 root 4044: not in an argument.
4045:
4046: What you need to provide in addition to a backtrace are the values of
4047: the local variables for several stack frames up. When a local
4048: variable or an argument is an RTX, first print its value and then use
4049: the GDB command @code{pr} to print the RTL expression that it points
4050: to. (If GDB doesn't run on your machine, use your debugger to call
4051: the function @code{debug_rtx} with the RTX as an argument.) In
4052: general, whenever a variable is a pointer, its value is no use
4053: without the data it points to.
4054:
4055: In addition, include a debugging dump from just before the pass
4056: in which the crash happens. Most bugs involve a series of insns,
4057: not just one.
4058: @end itemize
4059:
4060: Here are some things that are not necessary:
4061:
4062: @itemize @bullet
4063: @item
4064: A description of the envelope of the bug.
4065:
4066: Often people who encounter a bug spend a lot of time investigating
4067: which changes to the input file will make the bug go away and which
4068: changes will not affect it.
4069:
4070: This is often time consuming and not very useful, because the way I
4071: will find the bug is by running a single example under the debugger
4072: with breakpoints, not by pure deduction from a series of examples.
1.1.1.8 root 4073: I recommend that you save your time for something else.
1.1 root 4074:
4075: Of course, if you can find a simpler example to report @emph{instead}
4076: of the original one, that is a convenience for me. Errors in the
4077: output will be easier to spot, running under the debugger will take
4078: less time, etc. Most GNU CC bugs involve just one function, so the
4079: most straightforward way to simplify an example is to delete all the
4080: function definitions except the one where the bug occurs. Those
4081: earlier in the file may be replaced by external declarations if the
1.1.1.8 root 4082: crucial function depends on them. (Exception: inline functions may
4083: affect compilation of functions defined later in the file.)
1.1 root 4084:
4085: However, simplification is not vital; if you don't want to do this,
1.1.1.8 root 4086: report the bug anyway and send me the entire test case you used.
1.1 root 4087:
4088: @item
4089: A patch for the bug.
4090:
4091: A patch for the bug does help me if it is a good one. But don't omit
1.1.1.8 root 4092: the necessary information, such as the test case, on the assumption that
4093: a patch is all I need. I might see problems with your patch and decide
4094: to fix the problem another way, or I might not understand it at all.
1.1 root 4095:
4096: Sometimes with a program as complicated as GNU CC it is very hard to
4097: construct an example that will make the program follow a certain path
4098: through the code. If you don't send me the example, I won't be able
4099: to construct one, so I won't be able to verify that the bug is fixed.
4100:
1.1.1.8 root 4101: And if I can't understand what bug you are trying to fix, or why your
4102: patch should be an improvement, I won't install it. A test case will
4103: help me to understand.
4104:
1.1 root 4105: @item
4106: A guess about what the bug is or what it depends on.
4107:
4108: Such guesses are usually wrong. Even I can't guess right about such
1.1.1.8 root 4109: things without first using the debugger to find the facts.
1.1 root 4110: @end itemize
4111:
4112: @node Portability, Interface, Bugs, Top
4113: @chapter GNU CC and Portability
4114:
4115: The main goal of GNU CC was to make a good, fast compiler for machines in
4116: the class that the GNU system aims to run on: 32-bit machines that address
4117: 8-bit bytes and have several general registers. Elegance, theoretical
4118: power and simplicity are only secondary.
4119:
4120: GNU CC gets most of the information about the target machine from a machine
4121: description which gives an algebraic formula for each of the machine's
4122: instructions. This is a very clean way to describe the target. But when
4123: the compiler needs information that is difficult to express in this
4124: fashion, I have not hesitated to define an ad-hoc parameter to the machine
4125: description. The purpose of portability is to reduce the total work needed
4126: on the compiler; it was not of interest for its own sake.
4127:
4128: GNU CC does not contain machine dependent code, but it does contain code
4129: that depends on machine parameters such as endianness (whether the most
4130: significant byte has the highest or lowest address of the bytes in a word)
4131: and the availability of autoincrement addressing. In the RTL-generation
4132: pass, it is often necessary to have multiple strategies for generating code
4133: for a particular kind of syntax tree, strategies that are usable for different
4134: combinations of parameters. Often I have not tried to address all possible
4135: cases, but only the common ones or only the ones that I have encountered.
4136: As a result, a new target may require additional strategies. You will know
4137: if this happens because the compiler will call @code{abort}. Fortunately,
4138: the new strategies can be added in a machine-independent fashion, and will
4139: affect only the target machines that need them.
4140:
4141: @node Interface, Passes, Portability, Top
4142: @chapter Interfacing to GNU CC Output
4143:
4144: GNU CC is normally configured to use the same function calling convention
4145: normally in use on the target system. This is done with the
4146: machine-description macros described (@pxref{Machine Macros}).
4147:
4148: However, returning of structure and union values is done differently on
4149: some target machines. As a result, functions compiled with PCC
4150: returning such types cannot be called from code compiled with GNU CC,
4151: and vice versa. This does not cause trouble often because few Unix
4152: library routines return structures or unions.
4153:
4154: GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes
4155: long in the same registers used for @code{int} or @code{double} return
4156: values. (GNU CC typically allocates variables of such types in
4157: registers also.) Structures and unions of other sizes are returned by
4158: storing them into an address passed by the caller (usually in a
4159: register). The machine-description macros @code{STRUCT_VALUE} and
4160: @code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address.
4161:
4162: By contrast, PCC on most target machines returns structures and unions
4163: of any size by copying the data into an area of static storage, and then
4164: returning the address of that storage as if it were a pointer value.
4165: The caller must copy the data from that memory area to the place where
4166: the value is wanted. This is slower than the method used by GNU CC, and
4167: fails to be reentrant.
4168:
4169: On some target machines, such as RISC machines and the 80386, the
4170: standard system convention is to pass to the subroutine the address of
4171: where to return the value. On these machines, GNU CC has been
4172: configured to be compatible with the standard compiler, when this method
4173: is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
4174:
4175: GNU CC uses the system's standard convention for passing arguments. On
4176: some machines, the first few arguments are passed in registers; in
4177: others, all are passed on the stack. It would be possible to use
4178: registers for argument passing on any machine, and this would probably
4179: result in a significant speedup. But the result would be complete
4180: incompatibility with code that follows the standard convention. So this
4181: change is practical only if you are switching to GNU CC as the sole C
4182: compiler for the system. We may implement register argument passing on
4183: certain machines once we have a complete GNU system so that we can
4184: compile the libraries with GNU CC.
4185:
4186: If you use @code{longjmp}, beware of automatic variables. ANSI C says that
4187: automatic variables that are not declared @code{volatile} have undefined
4188: values after a @code{longjmp}. And this is all GNU CC promises to do,
4189: because it is very difficult to restore register variables correctly, and
4190: one of GNU CC's features is that it can put variables in registers without
4191: your asking it to.
4192:
4193: If you want a variable to be unaltered by @code{longjmp}, and you don't
4194: want to write @code{volatile} because old C compilers don't accept it,
4195: just take the address of the variable. If a variable's address is ever
4196: taken, even if just to compute it and ignore it, then the variable cannot
4197: go in a register:
4198:
4199: @example
4200: @{
4201: int careful;
4202: &careful;
4203: @dots{}
4204: @}
4205: @end example
4206:
4207: Code compiled with GNU CC may call certain library routines. Most of
4208: them handle arithmetic for which there are no instructions. This
4209: includes multiply and divide on some machines, and floating point
4210: operations on any machine for which floating point support is disabled
4211: with @samp{-msoft-float}. Some standard parts of the C library, such as
4212: @code{bcopy} or @code{memcpy}, are also called automatically. The usual
4213: function call interface is used for calling the library routines.
4214:
4215: These library routines should be defined in the library @file{gnulib},
4216: which GNU CC automatically searches whenever it links a program. On
4217: machines that have multiply and divide instructions, if hardware
4218: floating point is in use, normally @file{gnulib} is not needed, but it
4219: is searched just in case.
4220:
4221: Each arithmetic function is defined in @file{gnulib.c} to use the
4222: corresponding C arithmetic operator. As long as the file is compiled
4223: with another C compiler, which supports all the C arithmetic operators,
4224: this file will work portably. However, @file{gnulib.c} does not work if
4225: compiled with GNU CC, because each arithmetic function would compile
4226: into a call to itself!
4227:
4228: @node Passes, RTL, Interface, Top
4229: @chapter Passes and Files of the Compiler
4230:
4231: The overall control structure of the compiler is in @file{toplev.c}. This
4232: file is responsible for initialization, decoding arguments, opening and
4233: closing files, and sequencing the passes.
4234:
4235: The parsing pass is invoked only once, to parse the entire input. The RTL
4236: intermediate code for a function is generated as the function is parsed, a
4237: statement at a time. Each statement is read in as a syntax tree and then
4238: converted to RTL; then the storage for the tree for the statement is
4239: reclaimed. Storage for types (and the expressions for their sizes),
4240: declarations, and a representation of the binding contours and how they nest,
4241: remains until the function is finished being compiled; these are all needed
4242: to output the debugging information.
4243:
4244: Each time the parsing pass reads a complete function definition or
4245: top-level declaration, it calls the function
4246: @code{rest_of_compilation} or @code{rest_of_decl_compilation} in
4247: @file{toplev.c}, which are responsible for all further processing
4248: necessary, ending with output of the assembler language. All other
4249: compiler passes run, in sequence, within @code{rest_of_compilation}.
4250: When that function returns from compiling a function definition, the
4251: storage used for that function definition's compilation is entirely
4252: freed, unless it is an inline function (@pxref{Inline}).
4253:
4254: Here is a list of all the passes of the compiler and their source files.
4255: Also included is a description of where debugging dumps can be requested
4256: with @samp{-d} options.
4257:
4258: @itemize @bullet
4259: @item
4260: Parsing. This pass reads the entire text of a function definition,
4261: constructing partial syntax trees. This and RTL generation are no longer
4262: truly separate passes (formerly they were), but it is easier to think
4263: of them as separate.
4264:
4265: The tree representation does not entirely follow C syntax, because it is
4266: intended to support other languages as well.
4267:
4268: C data type analysis is also done in this pass, and every tree node
4269: that represents an expression has a data type attached. Variables are
4270: represented as declaration nodes.
4271:
4272: Constant folding and associative-law simplifications are also done
4273: during this pass.
4274:
4275: The source files for parsing are @file{c-parse.y}, @file{c-decl.c},
4276: @file{c-typeck.c}, @file{c-convert.c}, @file{stor-layout.c},
4277: @file{fold-const.c}, and @file{tree.c}. The last three files are
4278: intended to be language-independent. There are also header files
4279: @file{c-parse.h}, @file{c-tree.h}, @file{tree.h} and @file{tree.def}.
4280: The last two define the format of the tree representation.@refill
4281:
4282: @item
4283: RTL generation. This is the conversion of syntax tree into RTL code.
4284: It is actually done statement-by-statement during parsing, but for
4285: most purposes it can be thought of as a separate pass.
4286:
4287: This is where the bulk of target-parameter-dependent code is found,
4288: since often it is necessary for strategies to apply only when certain
4289: standard kinds of instructions are available. The purpose of named
4290: instruction patterns is to provide this information to the RTL
4291: generation pass.
4292:
4293: Optimization is done in this pass for @code{if}-conditions that are
4294: comparisons, boolean operations or conditional expressions. Tail
4295: recursion is detected at this time also. Decisions are made about how
4296: best to arrange loops and how to output @code{switch} statements.
4297:
4298: The source files for RTL generation are @file{stmt.c}, @file{expr.c},
4299: @file{explow.c}, @file{expmed.c}, @file{optabs.c} and @file{emit-rtl.c}.
4300: Also, the file @file{insn-emit.c}, generated from the machine description
4301: by the program @code{genemit}, is used in this pass. The header files
4302: @file{expr.h} is used for communication within this pass.@refill
4303:
4304: The header files @file{insn-flags.h} and @file{insn-codes.h},
4305: generated from the machine description by the programs @code{genflags}
4306: and @code{gencodes}, tell this pass which standard names are available
4307: for use and which patterns correspond to them.@refill
4308:
4309: Aside from debugging information output, none of the following passes
4310: refers to the tree structure representation of the function (only
4311: part of which is saved).
4312:
4313: The decision of whether the function can and should be expanded inline
4314: in its subsequent callers is made at the end of rtl generation. The
4315: function must meet certain criteria, currently related to the size of
4316: the function and the types and number of parameters it has. Note that
4317: this function may contain loops, recursive calls to itself
4318: (tail-recursive functions can be inlined!), gotos, in short, all
4319: constructs supported by GNU CC.
4320:
4321: The option @samp{-dr} causes a debugging dump of the RTL code after
4322: this pass. This dump file's name is made by appending @samp{.rtl} to
4323: the input file name.
4324:
4325: @item
4326: Jump optimization. This pass simplifies jumps to the following
4327: instruction, jumps across jumps, and jumps to jumps. It deletes
4328: unreferenced labels and unreachable code, except that unreachable code
4329: that contains a loop is not recognized as unreachable in this pass.
4330: (Such loops are deleted later in the basic block analysis.)
4331:
4332: Jump optimization is performed two or three times. The first time is
4333: immediately following RTL generation. The second time is after CSE,
4334: but only if CSE says repeated jump optimization is needed. The
4335: last time is right before the final pass. That time, cross-jumping
4336: and deletion of no-op move instructions are done together with the
4337: optimizations described above.
4338:
4339: The source file of this pass is @file{jump.c}.
4340:
4341: The option @samp{-dj} causes a debugging dump of the RTL code after
4342: this pass is run for the first time. This dump file's name is made by
4343: appending @samp{.jump} to the input file name.
4344:
4345: @item
4346: Register scan. This pass finds the first and last use of each
4347: register, as a guide for common subexpression elimination. Its source
4348: is in @file{regclass.c}.
4349:
4350: @item
4351: Common subexpression elimination. This pass also does constant
4352: propagation. Its source file is @file{cse.c}. If constant
4353: propagation causes conditional jumps to become unconditional or to
4354: become no-ops, jump optimization is run again when CSE is finished.
4355:
4356: The option @samp{-ds} causes a debugging dump of the RTL code after
4357: this pass. This dump file's name is made by appending @samp{.cse} to
4358: the input file name.
4359:
4360: @item
1.1.1.8 root 4361: Loop optimization. This pass moves constant expressions out of loops,
4362: and optionally does strength-reduction as well. Its source file is
4363: @file{loop.c}.
1.1 root 4364:
4365: The option @samp{-dL} causes a debugging dump of the RTL code after
4366: this pass. This dump file's name is made by appending @samp{.loop} to
4367: the input file name.
4368:
4369: @item
4370: Stupid register allocation is performed at this point in a
4371: nonoptimizing compilation. It does a little data flow analysis as
4372: well. When stupid register allocation is in use, the next pass
4373: executed is the reloading pass; the others in between are skipped.
4374: The source file is @file{stupid.c}.
4375:
4376: @item
4377: Data flow analysis (@file{flow.c}). This pass divides the program
4378: into basic blocks (and in the process deletes unreachable loops); then
4379: it computes which pseudo-registers are live at each point in the
4380: program, and makes the first instruction that uses a value point at
4381: the instruction that computed the value.
4382:
4383: This pass also deletes computations whose results are never used, and
4384: combines memory references with add or subtract instructions to make
4385: autoincrement or autodecrement addressing.
4386:
4387: The option @samp{-df} causes a debugging dump of the RTL code after
4388: this pass. This dump file's name is made by appending @samp{.flow} to
4389: the input file name. If stupid register allocation is in use, this
4390: dump file reflects the full results of such allocation.
4391:
4392: @item
4393: Instruction combination (@file{combine.c}). This pass attempts to
4394: combine groups of two or three instructions that are related by data
4395: flow into single instructions. It combines the RTL expressions for
4396: the instructions by substitution, simplifies the result using algebra,
4397: and then attempts to match the result against the machine description.
4398:
4399: The option @samp{-dc} causes a debugging dump of the RTL code after
4400: this pass. This dump file's name is made by appending @samp{.combine}
4401: to the input file name.
4402:
4403: @item
4404: Register class preferencing. The RTL code is scanned to find out
4405: which register class is best for each pseudo register. The source
4406: file is @file{regclass.c}.
4407:
4408: @item
4409: Local register allocation (@file{local-alloc.c}). This pass allocates
4410: hard registers to pseudo registers that are used only within one basic
4411: block. Because the basic block is linear, it can use fast and
4412: powerful techniques to do a very good job.
4413:
4414: The option @samp{-dl} causes a debugging dump of the RTL code after
4415: this pass. This dump file's name is made by appending @samp{.lreg} to
4416: the input file name.
4417:
4418: @item
4419: Global register allocation (@file{global-alloc.c}). This pass
4420: allocates hard registers for the remaining pseudo registers (those
4421: whose life spans are not contained in one basic block).
4422:
4423: @item
4424: Reloading. This pass renumbers pseudo registers with the hardware
4425: registers numbers they were allocated. Pseudo registers that did not
4426: get hard registers are replaced with stack slots. Then it finds
4427: instructions that are invalid because a value has failed to end up in
4428: a register, or has ended up in a register of the wrong kind. It fixes
4429: up these instructions by reloading the problematical values
4430: temporarily into registers. Additional instructions are generated to
4431: do the copying.
4432:
4433: Source files are @file{reload.c} and @file{reload1.c}, plus the header
4434: @file{reload.h} used for communication between them.
4435:
4436: The option @samp{-dg} causes a debugging dump of the RTL code after
4437: this pass. This dump file's name is made by appending @samp{.greg} to
4438: the input file name.
4439:
4440: @item
4441: Jump optimization is repeated, this time including cross-jumping
1.1.1.5 root 4442: and deletion of no-op move instructions.
1.1 root 4443:
4444: The option @samp{-dJ} causes a debugging dump of the RTL code after
4445: this pass. This dump file's name is made by appending @samp{.jump2}
4446: to the input file name.
4447:
4448: @item
1.1.1.8 root 4449: Delayed branch scheduling may be done at this point. The source file
4450: name is @file{dbranch.c}.
4451:
4452: The option @samp{-dd} causes a debugging dump of the RTL code after
4453: this pass. This dump file's name is made by appending @samp{.dbr}
4454: to the input file name.
4455:
4456: @item
1.1 root 4457: Final. This pass outputs the assembler code for the function. It is
4458: also responsible for identifying spurious test and compare
1.1.1.5 root 4459: instructions. Machine-specific peephole optimizations are performed
4460: at the same time. The function entry and exit sequences are generated
1.1 root 4461: directly as assembler code in this pass; they never exist as RTL.
4462:
4463: The source files are @file{final.c} plus @file{insn-output.c}; the
4464: latter is generated automatically from the machine description by the
4465: tool @file{genoutput}. The header file @file{conditions.h} is used
4466: for communication between these files.
4467:
4468: @item
4469: Debugging information output. This is run after final because it must
4470: output the stack slot offsets for pseudo registers that did not get
4471: hard registers. Source files are @file{dbxout.c} for DBX symbol table
4472: format and @file{symout.c} for GDB's own symbol table format.
4473: @end itemize
4474:
4475: Some additional files are used by all or many passes:
4476:
4477: @itemize @bullet
4478: @item
4479: Every pass uses @file{machmode.def}, which defines the machine modes.
4480:
4481: @item
4482: All the passes that work with RTL use the header files @file{rtl.h}
4483: and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
4484: @code{gen*} also use these files to read and work with the machine
4485: description RTL.
4486:
4487: @item
4488: Several passes refer to the header file @file{insn-config.h} which
4489: contains a few parameters (C macro definitions) generated
4490: automatically from the machine description RTL by the tool
4491: @code{genconfig}.
4492:
4493: @item
4494: Several passes use the instruction recognizer, which consists of
4495: @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
4496: and @file{insn-extract.c} that are generated automatically from the
4497: machine description by the tools @file{genrecog} and
4498: @file{genextract}.@refill
4499:
4500: @item
4501: Several passes use the header files @file{regs.h} which defines the
4502: information recorded about pseudo register usage, and @file{basic-block.h}
4503: which defines the information recorded about basic blocks.
4504:
4505: @item
4506: @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
4507: with a bit for each hard register, and some macros to manipulate it.
4508: This type is just @code{int} if the machine has few enough hard registers;
4509: otherwise it is an array of @code{int} and some of the macros expand
4510: into loops.
4511: @end itemize
4512:
4513: @node RTL, Machine Desc, Passes, Top
4514: @chapter RTL Representation
4515:
4516: Most of the work of the compiler is done on an intermediate representation
4517: called register transfer language. In this language, the instructions to be
4518: output are described, pretty much one by one, in an algebraic form that
4519: describes what the instruction does.
4520:
4521: RTL is inspired by Lisp lists. It has both an internal form, made up of
4522: structures that point at other structures, and a textual form that is used
4523: in the machine description and in printed debugging dumps. The textual
4524: form uses nested parentheses to indicate the pointers in the internal form.
4525:
4526: @menu
4527: * RTL Objects:: Expressions vs vectors vs strings vs integers.
4528: * Accessors:: Macros to access expression operands or vector elts.
4529: * Flags:: Other flags in an RTL expression.
4530: * Machine Modes:: Describing the size and format of a datum.
4531: * Constants:: Expressions with constant values.
4532: * Regs and Memory:: Expressions representing register contents or memory.
4533: * Arithmetic:: Expressions representing arithmetic on other expressions.
4534: * Comparisons:: Expressions representing comparison of expressions.
4535: * Bit Fields:: Expressions representing bit-fields in memory or reg.
4536: * Conversions:: Extending, truncating, floating or fixing.
4537: * RTL Declarations:: Declaring volatility, constancy, etc.
4538: * Side Effects:: Expressions for storing in registers, etc.
4539: * Incdec:: Embedded side-effects for autoincrement addressing.
1.1.1.9 root 4540: * Assembler:: Representing @code{asm} with operands.
1.1 root 4541: * Insns:: Expression types for entire insns.
1.1.1.9 root 4542: * Calls:: RTL representation of function call insns.
1.1 root 4543: * Sharing:: Some expressions are unique; others *must* be copied.
4544: @end menu
4545:
4546: @node RTL Objects, Accessors, RTL, RTL
4547: @section RTL Object Types
4548:
4549: RTL uses four kinds of objects: expressions, integers, strings and vectors.
4550: Expressions are the most important ones. An RTL expression (``RTX'', for
4551: short) is a C structure, but it is usually referred to with a pointer; a
4552: type that is given the typedef name @code{rtx}.
4553:
4554: An integer is simply an @code{int}, and a string is a @code{char *}.
1.1.1.8 root 4555: Within RTL code, strings appear only inside @code{symbol_ref} expressions,
1.1 root 4556: but they appear in other contexts in the RTL expressions that make up
4557: machine descriptions. Their written form uses decimal digits.
4558:
4559: A string is a sequence of characters. In core it is represented as a
4560: @code{char *} in usual C fashion, and it is written in C syntax as well.
4561: However, strings in RTL may never be null. If you write an empty string in
4562: a machine description, it is represented in core as a null pointer rather
4563: than as a pointer to a null character. In certain contexts, these null
4564: pointers instead of strings are valid.
4565:
4566: A vector contains an arbitrary, specified number of pointers to
4567: expressions. The number of elements in the vector is explicitly present in
4568: the vector. The written form of a vector consists of square brackets
4569: (@samp{[@dots{}]}) surrounding the elements, in sequence and with
4570: whitespace separating them. Vectors of length zero are not created; null
4571: pointers are used instead.
4572:
4573: Expressions are classified by @dfn{expression codes} (also called RTX
4574: codes). The expression code is a name defined in @file{rtl.def}, which is
4575: also (in upper case) a C enumeration constant. The possible expression
4576: codes and their meanings are machine-independent. The code of an RTX can
4577: be extracted with the macro @code{GET_CODE (@var{x})} and altered with
4578: @code{PUT_CODE (@var{x}, @var{newcode})}.
4579:
4580: The expression code determines how many operands the expression contains,
4581: and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
4582: by looking at an operand what kind of object it is. Instead, you must know
4583: from its context---from the expression code of the containing expression.
1.1.1.8 root 4584: For example, in an expression of code @code{subreg}, the first operand is
1.1 root 4585: to be regarded as an expression and the second operand as an integer. In
1.1.1.8 root 4586: an expression of code @code{plus}, there are two operands, both of which
4587: are to be regarded as expressions. In a @code{symbol_ref} expression,
1.1 root 4588: there is one operand, which is to be regarded as a string.
4589:
4590: Expressions are written as parentheses containing the name of the
4591: expression type, its flags and machine mode if any, and then the operands
4592: of the expression (separated by spaces).
4593:
4594: Expression code names in the @samp{md} file are written in lower case,
4595: but when they appear in C code they are written in upper case. In this
1.1.1.8 root 4596: manual, they are shown as follows: @code{const_int}.
1.1 root 4597:
4598: In a few contexts a null pointer is valid where an expression is normally
1.1.1.4 root 4599: wanted. The written form of this is @code{(nil)}.
1.1 root 4600:
4601: @node Accessors, Flags, RTL Objects, RTL
4602: @section Access to Operands
4603:
4604: For each expression type @file{rtl.def} specifies the number of contained
4605: objects and their kinds, with four possibilities: @samp{e} for expression
4606: (actually a pointer to an expression), @samp{i} for integer, @samp{s} for
4607: string, and @samp{E} for vector of expressions. The sequence of letters
4608: for an expression code is called its @dfn{format}. Thus, the format of
1.1.1.8 root 4609: @code{subreg} is @samp{ei}.@refill
1.1 root 4610:
4611: Two other format characters are used occasionally: @samp{u} and @samp{0}.
4612: @samp{u} is equivalent to @samp{e} except that it is printed differently in
4613: debugging dumps, and @samp{0} means a slot whose contents do not fit any
4614: normal category. @samp{0} slots are not printed at all in dumps, and are
4615: often used in special ways by small parts of the compiler.@refill
4616:
4617: There are macros to get the number of operands and the format of an
4618: expression code:
4619:
4620: @table @code
4621: @item GET_RTX_LENGTH (@var{code})
4622: Number of operands of an RTX of code @var{code}.
4623:
4624: @item GET_RTX_FORMAT (@var{code})
4625: The format of an RTX of code @var{code}, as a C string.
4626: @end table
4627:
4628: Operands of expressions are accessed using the macros @code{XEXP},
4629: @code{XINT} and @code{XSTR}. Each of these macros takes two arguments: an
4630: expression-pointer (RTX) and an operand number (counting from zero).
4631: Thus,@refill
4632:
4633: @example
4634: XEXP (@var{x}, 2)
4635: @end example
4636:
4637: @noindent
4638: accesses operand 2 of expression @var{x}, as an expression.
4639:
4640: @example
4641: XINT (@var{x}, 2)
4642: @end example
4643:
4644: @noindent
4645: accesses the same operand as an integer. @code{XSTR}, used in the same
4646: fashion, would access it as a string.
4647:
4648: Any operand can be accessed as an integer, as an expression or as a string.
4649: You must choose the correct method of access for the kind of value actually
4650: stored in the operand. You would do this based on the expression code of
4651: the containing expression. That is also how you would know how many
4652: operands there are.
4653:
1.1.1.8 root 4654: For example, if @var{x} is a @code{subreg} expression, you know that it has
1.1 root 4655: two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
4656: and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
4657: would get the address of the expression operand but cast as an integer;
4658: that might occasionally be useful, but it would be cleaner to write
4659: @code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
4660: compile without error, and would return the second, integer operand cast as
4661: an expression pointer, which would probably result in a crash when
4662: accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
4663: but this will access memory past the end of the expression with
4664: unpredictable results.@refill
4665:
4666: Access to operands which are vectors is more complicated. You can use the
4667: macro @code{XVEC} to get the vector-pointer itself, or the macros
4668: @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
4669: vector.
4670:
4671: @table @code
4672: @item XVEC (@var{exp}, @var{idx})
4673: Access the vector-pointer which is operand number @var{idx} in @var{exp}.
4674:
4675: @item XVECLEN (@var{exp}, @var{idx})
4676: Access the length (number of elements) in the vector which is
4677: in operand number @var{idx} in @var{exp}. This value is an @code{int}.
4678:
4679: @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
4680: Access element number @var{eltnum} in the vector which is
4681: in operand number @var{idx} in @var{exp}. This value is an RTX.
4682:
4683: It is up to you to make sure that @var{eltnum} is not negative
4684: and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
4685: @end table
4686:
4687: All the macros defined in this section expand into lvalues and therefore
4688: can be used to assign the operands, lengths and vector elements as well as
4689: to access them.
4690:
4691: @node Flags, Machine Modes, Accessors, RTL
4692: @section Flags in an RTL Expression
4693:
4694: RTL expressions contain several flags (one-bit bit-fields) that are used
4695: in certain types of expression. Most often they are accessed with the
4696: following macros:
4697:
4698: @table @code
1.1.1.10 root 4699: @item EXTERNAL_SYMBOL_P (@var{x})
4700: In a @code{symbol_ref} expression, nonzero if it corresponds to a variable
4701: declared extern in the users code. Zero for all other variables. Stored in
4702: the @code{volatil} field and printed as @samp{/v}.
4703:
1.1 root 4704: @item MEM_VOLATILE_P (@var{x})
1.1.1.8 root 4705: In @code{mem} expressions, nonzero for volatile memory references.
1.1 root 4706: Stored in the @code{volatil} field and printed as @samp{/v}.
4707:
4708: @item MEM_IN_STRUCT_P (@var{x})
1.1.1.8 root 4709: In @code{mem} expressions, nonzero for reference to an entire
1.1 root 4710: structure, union or array, or to a component of one. Zero for
4711: references to a scalar variable or through a pointer to a scalar.
4712: Stored in the @code{in_struct} field and printed as @samp{/s}.
4713:
4714: @item REG_USER_VAR_P (@var{x})
1.1.1.8 root 4715: In a @code{reg}, nonzero if it corresponds to a variable present in
1.1 root 4716: the user's source code. Zero for temporaries generated internally by
4717: the compiler. Stored in the @code{volatil} field and printed as
4718: @samp{/v}.
4719:
4720: @item REG_FUNCTION_VALUE_P (@var{x})
1.1.1.8 root 4721: Nonzero in a @code{reg} if it is the place in which this function's
1.1 root 4722: value is going to be returned. (This happens only in a hard
4723: register.) Stored in the @code{integrated} field and printed as
4724: @samp{/i}.
4725:
4726: The same hard register may be used also for collecting the values of
4727: functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
4728: in this kind of use.
4729:
4730: @item RTX_UNCHANGING_P (@var{x})
1.1.1.8 root 4731: Nonzero in a @code{reg} or @code{mem} if the value is not changed
1.1 root 4732: explicitly by the current function. (If it is a memory reference then
4733: it may be changed by other functions or by aliasing.) Stored in the
4734: @code{unchanging} field and printed as @samp{/u}.
4735:
4736: @item RTX_INTEGRATED_P (@var{insn})
4737: Nonzero in an insn if it resulted from an in-line function call.
4738: Stored in the @code{integrated} field and printed as @samp{/i}. This
4739: may be deleted; nothing currently depends on it.
4740:
4741: @item INSN_DELETED_P (@var{insn})
4742: In an insn, nonzero if the insn has been deleted. Stored in the
4743: @code{volatil} field and printed as @samp{/v}.
4744:
4745: @item CONSTANT_POOL_ADDRESS_P (@var{x})
1.1.1.8 root 4746: Nonzero in a @code{symbol_ref} if it refers to part of the current
1.1 root 4747: function's ``constants pool''. These are addresses close to the
4748: beginning of the function, and GNU CC assumes they can be addressed
4749: directly (perhaps with the help of base registers). Stored in the
4750: @code{unchanging} field and printed as @samp{/u}.
4751: @end table
4752:
4753: These are the fields which the above macros refer to:
4754:
4755: @table @code
4756: @item used
4757: This flag is used only momentarily, at the end of RTL generation for a
4758: function, to count the number of times an expression appears in insns.
4759: Expressions that appear more than once are copied, according to the
4760: rules for shared structure (@pxref{Sharing}).
4761:
4762: @item volatil
1.1.1.10 root 4763: This flag is used in @code{mem},@code{symbol_ref} and @code{reg} expressions
4764: and in insns. In RTL dump files, it is printed as @samp{/v}.
1.1 root 4765:
1.1.1.8 root 4766: In a @code{mem} expression, it is 1 if the memory reference is volatile.
1.1 root 4767: Volatile memory references may not be deleted, reordered or combined.
4768:
1.1.1.8 root 4769: In a @code{reg} expression, it is 1 if the value is a user-level variable.
1.1 root 4770: 0 indicates an internal compiler temporary.
4771:
1.1.1.10 root 4772: In a @code{symbol_ref} expression, it is 1 if the symbol is declared
4773: @code{extern}.
4774:
1.1 root 4775: In an insn, 1 means the insn has been deleted.
4776:
4777: @item in_struct
1.1.1.8 root 4778: This flag is used in @code{mem} expressions. It is 1 if the memory
1.1 root 4779: datum referred to is all or part of a structure or array; 0 if it is (or
4780: might be) a scalar variable. A reference through a C pointer has 0
4781: because the pointer might point to a scalar variable.
4782:
4783: This information allows the compiler to determine something about possible
4784: cases of aliasing.
4785:
4786: In an RTL dump, this flag is represented as @samp{/s}.
4787:
4788: @item unchanging
1.1.1.8 root 4789: This flag is used in @code{reg} and @code{mem} expressions. 1 means
1.1 root 4790: that the value of the expression never changes (at least within the
4791: current function).
4792:
4793: In an RTL dump, this flag is represented as @samp{/u}.
4794:
4795: @item integrated
4796: In some kinds of expressions, including insns, this flag means the
4797: rtl was produced by procedure integration.
4798:
1.1.1.8 root 4799: In a @code{reg} expression, this flag indicates the register
1.1 root 4800: containing the value to be returned by the current function. On
4801: machines that pass parameters in registers, the same register number
4802: may be used for parameters as well, but this flag is not set on such
4803: uses.
4804: @end table
4805:
4806: @node Machine Modes, Constants, Flags, RTL
4807: @section Machine Modes
4808:
4809: A machine mode describes a size of data object and the representation used
4810: for it. In the C code, machine modes are represented by an enumeration
4811: type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
4812: expression has room for a machine mode and so do certain kinds of tree
4813: expressions (declarations and types, to be precise).
4814:
4815: In debugging dumps and machine descriptions, the machine mode of an RTL
4816: expression is written after the expression code with a colon to separate
4817: them. The letters @samp{mode} which appear at the end of each machine mode
1.1.1.8 root 4818: name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
1.1 root 4819: expression with machine mode @code{SImode}. If the mode is
4820: @code{VOIDmode}, it is not written at all.
4821:
4822: Here is a table of machine modes.
4823:
4824: @table @code
4825: @item QImode
4826: ``Quarter-Integer'' mode represents a single byte treated as an integer.
4827:
4828: @item HImode
4829: ``Half-Integer'' mode represents a two-byte integer.
4830:
1.1.1.7 root 4831: @item PSImode
4832: ``Partial Single Integer'' mode represents an integer which occupies
4833: four bytes but which doesn't really use all four. On some machines,
4834: this is the right mode to use for pointers.
4835:
1.1 root 4836: @item SImode
4837: ``Single Integer'' mode represents a four-byte integer.
4838:
1.1.1.7 root 4839: @item PDImode
4840: ``Partial Double Integer'' mode represents an integer which occupies
4841: eight bytes but which doesn't really use all eight. On some machines,
4842: this is the right mode to use for certain pointers.
4843:
1.1 root 4844: @item DImode
4845: ``Double Integer'' mode represents an eight-byte integer.
4846:
4847: @item TImode
4848: ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
4849:
4850: @item SFmode
4851: ``Single Floating'' mode represents a single-precision (four byte) floating
4852: point number.
4853:
4854: @item DFmode
4855: ``Double Floating'' mode represents a double-precision (eight byte) floating
4856: point number.
4857:
1.1.1.7 root 4858: @item XFmode
4859: ``Extended Floating'' mode represents a triple-precision (twelve byte)
4860: floating point number. This mode is used for IEEE extended floating
4861: point.
4862:
1.1 root 4863: @item TFmode
4864: ``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
4865: floating point number.
4866:
4867: @item BLKmode
4868: ``Block'' mode represents values that are aggregates to which none of
4869: the other modes apply. In RTL, only memory references can have this mode,
4870: and only if they appear in string-move or vector instructions. On machines
4871: which have no such instructions, @code{BLKmode} will not appear in RTL.
4872:
4873: @item VOIDmode
4874: Void mode means the absence of a mode or an unspecified mode.
1.1.1.8 root 4875: For example, RTL expressions of code @code{const_int} have mode
1.1 root 4876: @code{VOIDmode} because they can be taken to have whatever mode the context
4877: requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
4878: the absence of any mode.
4879:
4880: @item EPmode
4881: ``Entry Pointer'' mode is intended to be used for function variables in
4882: Pascal and other block structured languages. Such values contain
4883: both a function address and a static chain pointer for access to
4884: automatic variables of outer levels. This mode is only partially
4885: implemented since C does not use it.
4886:
4887: @item CSImode@r{, @dots{}}
4888: ``Complex Single Integer'' mode stands for a complex number represented
4889: as a pair of @code{SImode} integers. Any of the integer and floating modes
4890: may have @samp{C} prefixed to its name to obtain a complex number mode.
4891: For example, there are @code{CQImode}, @code{CSFmode}, and @code{CDFmode}.
4892: Since C does not support complex numbers, these machine modes are only
4893: partially implemented.
4894:
4895: @item BImode
4896: This is the machine mode of a bit-field in a structure. It is used
4897: only in the syntax tree, never in RTL, and in the syntax tree it appears
4898: only in declaration nodes. In C, it appears only in @code{FIELD_DECL}
4899: nodes for structure fields defined with a bit size.
4900: @end table
4901:
4902: The machine description defines @code{Pmode} as a C macro which expands
4903: into the machine mode used for addresses. Normally this is @code{SImode}.
4904:
4905: The only modes which a machine description @i{must} support are
4906: @code{QImode}, @code{SImode}, @code{SFmode} and @code{DFmode}. The
4907: compiler will attempt to use @code{DImode} for two-word structures and
1.1.1.7 root 4908: unions, but this can be prevented by overriding the definition of
4909: @code{MAX_FIXED_MODE_SIZE}. Likewise, you can arrange for the C type
4910: @code{short int} to avoid using @code{HImode}. In the long term it
4911: might be desirable to make the set of available machine modes
4912: machine-dependent and eliminate all assumptions about specific machine
4913: modes or their uses from the machine-independent code of the compiler.
1.1 root 4914:
1.1.1.4 root 4915: To help begin this process, the machine modes are divided into mode
4916: classes. These are represented by the enumeration type @code{enum
4917: mode_class} defined in @file{rtl.h}. The possible mode classes are:
4918:
4919: @table @code
4920: @item MODE_INT
4921: Integer modes. By default these are @code{QImode}, @code{HImode},
4922: @code{SImode}, @code{DImode}, @code{TImode}, and also @code{BImode}.
4923:
4924: @item MODE_FLOAT
4925: Floating-point modes. By default these are @code{QFmode},
4926: @code{HFmode}, @code{SFmode}, @code{DFmode} and @code{TFmode}, but the
4927: MC68881 also defines @code{XFmode} to be an 80-bit extended-precision
4928: floating-point mode.
4929:
4930: @item MODE_COMPLEX_INT
4931: Complex integer modes. By default these are @code{CQImode},
4932: @code{CHImode}, @code{CSImode}, @code{CDImode} and @code{CTImode}.
4933:
4934: @item MODE_COMPLEX_FLOAT
4935: Complex floating-point modes. By default these are @code{CQFmode},
4936: @code{CHFmode}, @code{CSFmode}, @code{CDFmode} and @code{CTFmode},
4937:
4938: @item MODE_FUNCTION
4939: Algol or Pascal function variables including a static chain.
4940: (These are not currently implemented).
4941:
4942: @item MODE_RANDOM
4943: This is a catchall mode class for modes which don't fit into the above
4944: classes. Currently @code{VOIDmode}, @code{BLKmode} and @code{EPmode}
4945: are in @code{MODE_RANDOM}.
4946: @end table
4947:
1.1 root 4948: Here are some C macros that relate to machine modes:
4949:
4950: @table @code
4951: @item GET_MODE (@var{x})
4952: Returns the machine mode of the RTX @var{x}.
4953:
4954: @item PUT_MODE (@var{x}, @var{newmode})
4955: Alters the machine mode of the RTX @var{x} to be @var{newmode}.
4956:
1.1.1.4 root 4957: @item NUM_MACHINE_MODES
4958: Stands for the number of machine modes available on the target
4959: machine. This is one greater than the largest numeric value of any
4960: machine mode.
4961:
4962: @item GET_MODE_NAME (@var{m})
4963: Returns the name of mode @var{m} as a string.
4964:
4965: @item GET_MODE_CLASS (@var{m})
4966: Returns the mode class of mode @var{m}.
4967:
1.1 root 4968: @item GET_MODE_SIZE (@var{m})
4969: Returns the size in bytes of a datum of mode @var{m}.
4970:
4971: @item GET_MODE_BITSIZE (@var{m})
4972: Returns the size in bits of a datum of mode @var{m}.
4973:
4974: @item GET_MODE_UNIT_SIZE (@var{m})
4975: Returns the size in bits of the subunits of a datum of mode @var{m}.
4976: This is the same as @code{GET_MODE_SIZE} except in the case of
4977: complex modes and @code{EPmode}. For them, the unit size is the
4978: size of the real or imaginary part, or the size of the function
4979: pointer or the context pointer.
4980: @end table
4981:
4982: @node Constants, Regs and Memory, Machine Modes, RTL
4983: @section Constant Expression Types
4984:
4985: The simplest RTL expressions are those that represent constant values.
4986:
4987: @table @code
4988: @item (const_int @var{i})
4989: This type of expression represents the integer value @var{i}. @var{i}
4990: is customarily accessed with the macro @code{INTVAL} as in
4991: @code{INTVAL (@var{exp})}, which is equivalent to @code{XINT (@var{exp}, 0)}.
4992:
4993: There is only one expression object for the integer value zero;
4994: it is the value of the variable @code{const0_rtx}. Likewise, the
4995: only expression for integer value one is found in @code{const1_rtx}.
1.1.1.8 root 4996: Any attempt to create an expression of code @code{const_int} and
1.1 root 4997: value zero or one will return @code{const0_rtx} or @code{const1_rtx}
4998: as appropriate.
4999:
5000: @item (const_double:@var{m} @var{i0} @var{i1})
1.1.1.6 root 5001: Represents a 64-bit constant of mode @var{m}. All floating point
1.1 root 5002: constants are represented in this way, and so are 64-bit @code{DImode}
5003: integer constants.
5004:
5005: The two integers @var{i0} and @var{i1} together contain the bits of
5006: the value. If the constant is floating point (either single or double
5007: precision), then they represent a @code{double}. To convert them to a
5008: @code{double}, do
5009:
5010: @example
5011: union @{ double d; int i[2];@} u;
1.1.1.8 root 5012: u.i[0] = CONST_DOUBLE_LOW(x);
5013: u.i[1] = CONST_DOUBLE_HIGH(x);
1.1 root 5014: @end example
5015:
5016: @noindent
5017: and then refer to @code{u.d}.
5018:
5019: The global variables @code{dconst0_rtx} and @code{fconst0_rtx} hold
1.1.1.8 root 5020: @code{const_double} expressions with value 0, in modes @code{DFmode}
1.1.1.7 root 5021: and @code{SFmode}, respectively. The macro @code{CONST0_RTX
1.1.1.8 root 5022: (@var{mode})} refers to a @code{const_double} expression with value 0
1.1.1.7 root 5023: in mode @var{mode}. The mode @var{mode} must be of mode class
5024: @code{MODE_FLOAT}.
1.1 root 5025:
5026: @item (symbol_ref @var{symbol})
5027: Represents the value of an assembler label for data. @var{symbol} is
5028: a string that describes the name of the assembler label. If it starts
5029: with a @samp{*}, the label is the rest of @var{symbol} not including
5030: the @samp{*}. Otherwise, the label is @var{symbol}, prefixed with
5031: @samp{_}.
5032:
5033: @item (label_ref @var{label})
5034: Represents the value of an assembler label for code. It contains one
1.1.1.8 root 5035: operand, an expression, which must be a @code{code_label} that appears
1.1 root 5036: in the instruction sequence to identify the place where the label
5037: should go.
5038:
5039: The reason for using a distinct expression type for code label
5040: references is so that jump optimization can distinguish them.
5041:
5042: @item (const @var{exp})
5043: Represents a constant that is the result of an assembly-time
5044: arithmetic computation. The operand, @var{exp}, is an expression that
1.1.1.8 root 5045: contains only constants (@code{const_int}, @code{symbol_ref} and
5046: @code{label_ref} expressions) combined with @code{plus} and
5047: @code{minus}. However, not all combinations are valid, since the
1.1 root 5048: assembler cannot do arbitrary arithmetic on relocatable symbols.
5049: @end table
5050:
5051: @node Regs and Memory, Arithmetic, Constants, RTL
5052: @section Registers and Memory
5053:
5054: Here are the RTL expression types for describing access to machine
5055: registers and to main memory.
5056:
5057: @table @code
5058: @item (reg:@var{m} @var{n})
5059: For small values of the integer @var{n} (less than
5060: @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
5061: register number @var{n}: a @dfn{hard register}. For larger values of
5062: @var{n}, it stands for a temporary value or @dfn{pseudo register}.
5063: The compiler's strategy is to generate code assuming an unlimited
5064: number of such pseudo registers, and later convert them into hard
5065: registers or into memory references.
5066:
5067: The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
5068: description, since the number of hard registers on the machine is an
5069: invariant characteristic of the machine. Note, however, that not
5070: all of the machine registers must be general registers. All the
5071: machine registers that can be used for storage of data are given
5072: hard register numbers, even those that can be used only in certain
5073: instructions or can hold only certain types of data.
5074:
5075: Each pseudo register number used in a function's RTL code is
1.1.1.8 root 5076: represented by a unique @code{reg} expression.
1.1 root 5077:
5078: @var{m} is the machine mode of the reference. It is necessary because
5079: machines can generally refer to each register in more than one mode.
5080: For example, a register may contain a full word but there may be
5081: instructions to refer to it as a half word or as a single byte, as
5082: well as instructions to refer to it as a floating point number of
5083: various precisions.
5084:
5085: Even for a register that the machine can access in only one mode,
5086: the mode must always be specified.
5087:
5088: A hard register may be accessed in various modes throughout one
5089: function, but each pseudo register is given a natural mode
5090: and is accessed only in that mode. When it is necessary to describe
1.1.1.8 root 5091: an access to a pseudo register using a nonnatural mode, a @code{subreg}
1.1 root 5092: expression is used.
5093:
1.1.1.8 root 5094: A @code{reg} expression with a machine mode that specifies more than
1.1 root 5095: one word of data may actually stand for several consecutive registers.
5096: If in addition the register number specifies a hardware register, then
5097: it actually represents several consecutive hardware registers starting
5098: with the specified one.
5099:
1.1.1.8 root 5100: Such multi-word hardware register @code{reg} expressions must not be live
1.1 root 5101: across the boundary of a basic block. The lifetime analysis pass does not
5102: know how to record properly that several consecutive registers are
5103: actually live there, and therefore register allocation would be confused.
5104: The CSE pass must go out of its way to make sure the situation does
5105: not arise.
5106:
5107: @item (subreg:@var{m} @var{reg} @var{wordnum})
1.1.1.8 root 5108: @code{subreg} expressions are used to refer to a register in a machine
1.1 root 5109: mode other than its natural one, or to refer to one register of
1.1.1.8 root 5110: a multi-word @code{reg} that actually refers to several registers.
1.1 root 5111:
5112: Each pseudo-register has a natural mode. If it is necessary to
5113: operate on it in a different mode---for example, to perform a fullword
1.1.1.8 root 5114: move instruction on a pseudo-register that contains a single
5115: byte---the pseudo-register must be enclosed in a @code{subreg}. In
5116: such a case, @var{wordnum} is zero.
1.1 root 5117:
1.1.1.8 root 5118: The other use of @code{subreg} is to extract the individual registers
1.1 root 5119: of a multi-register value. Machine modes such as @code{DImode} and
5120: @code{EPmode} indicate values longer than a word, values which usually
5121: require two consecutive registers. To access one of the registers,
1.1.1.8 root 5122: use a @code{subreg} with mode @code{SImode} and a @var{wordnum} that
1.1 root 5123: says which register.
5124:
5125: The compilation parameter @code{WORDS_BIG_ENDIAN}, if defined, says
5126: that word number zero is the most significant part; otherwise, it is
5127: the least significant part.
5128:
5129: Between the combiner pass and the reload pass, it is possible to have
1.1.1.8 root 5130: a @code{subreg} which contains a @code{mem} instead of a @code{reg} as
1.1 root 5131: its first operand. The reload pass eliminates these cases by
1.1.1.8 root 5132: reloading the @code{mem} into a suitable register.
1.1 root 5133:
5134: Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
1.1.1.8 root 5135: using a @code{subreg}. On some machines the most significant part of a
1.1 root 5136: @code{DFmode} value does not have the same format as a single-precision
5137: floating value.
5138:
5139: @item (cc0)
5140: This refers to the machine's condition code register. It has no
1.1.1.10 root 5141: operands and may not have a machine mode. There are two ways to use it:
5142:
5143: @itemize @bullet
5144: @item
5145: To stand for a complete set of condition code flags. This is best on
5146: most machines, where each comparison sets the entire series of flags.
5147:
5148: With this technique, @code{(cc0)} may be validly used in only two
5149: contexts: as the destination of an assignment (in test and compare
5150: instructions) and in comparison operators comparing against zero
5151: (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
5152:
5153: @item
5154: To stand for a single flag that is the result of a single condition.
5155: This is useful on machines that have only a single flag bit, and in
5156: which comparison instructions must specify the condition to test.
5157:
5158: With this technique, @code{(cc0)} may be validly used in only two
5159: contexts: as the destination of an assignment (in test and compare
5160: instructions) where the source is a comparison operator, and as the
5161: first operand of @code{if_then_else} (in a conditional branch).
5162: @end itemize
1.1 root 5163:
1.1.1.8 root 5164: There is only one expression object of code @code{cc0}; it is the
1.1 root 5165: value of the variable @code{cc0_rtx}. Any attempt to create an
1.1.1.8 root 5166: expression of code @code{cc0} will return @code{cc0_rtx}.
1.1 root 5167:
5168: One special thing about the condition code register is that
5169: instructions can set it implicitly. On many machines, nearly all
5170: instructions set the condition code based on the value that they
5171: compute or store. It is not necessary to record these actions
5172: explicitly in the RTL because the machine description includes a
5173: prescription for recognizing the instructions that do so (by means of
5174: the macro @code{NOTICE_UPDATE_CC}). Only instructions whose sole
5175: purpose is to set the condition code, and instructions that use the
5176: condition code, need mention @code{(cc0)}.
5177:
1.1.1.10 root 5178: In some cases, better code may result from recognizing combinations or
5179: peepholes that include instructions that set the condition codes, even
5180: in cases where some reloading is inevitable. For examples, search for
5181: @samp{addcc} and @samp{andcc} in @file{sparc.md}.
5182:
1.1 root 5183: @item (pc)
5184: This represents the machine's program counter. It has no operands and
5185: may not have a machine mode. @code{(pc)} may be validly used only in
5186: certain specific contexts in jump instructions.
5187:
1.1.1.8 root 5188: There is only one expression object of code @code{pc}; it is the value
1.1 root 5189: of the variable @code{pc_rtx}. Any attempt to create an expression of
1.1.1.8 root 5190: code @code{pc} will return @code{pc_rtx}.
1.1 root 5191:
5192: All instructions that do not jump alter the program counter implicitly
5193: by incrementing it, but there is no need to mention this in the RTL.
5194:
5195: @item (mem:@var{m} @var{addr})
5196: This RTX represents a reference to main memory at an address
5197: represented by the expression @var{addr}. @var{m} specifies how large
5198: a unit of memory is accessed.
5199: @end table
5200:
5201: @node Arithmetic, Comparisons, Regs and Memory, RTL
5202: @section RTL Expressions for Arithmetic
5203:
5204: @table @code
5205: @item (plus:@var{m} @var{x} @var{y})
5206: Represents the sum of the values represented by @var{x} and @var{y}
5207: carried out in machine mode @var{m}. This is valid only if
5208: @var{x} and @var{y} both are valid for mode @var{m}.
5209:
5210: @item (minus:@var{m} @var{x} @var{y})
1.1.1.8 root 5211: Like @code{plus} but represents subtraction.
1.1 root 5212:
1.1.1.6 root 5213: @item (compare @var{x} @var{y})
1.1 root 5214: Represents the result of subtracting @var{y} from @var{x}
5215: for purposes of comparison. The absence of a machine mode
1.1.1.8 root 5216: in the @code{compare} expression indicates that the result is
1.1 root 5217: computed without overflow, as if with infinite precision.
5218:
5219: Of course, machines can't really subtract with infinite precision.
5220: However, they can pretend to do so when only the sign of the
5221: result will be used, which is the case when the result is stored
5222: in @code{(cc0)}. And that is the only way this kind of expression
5223: may validly be used: as a value to be stored in the condition codes.
5224:
5225: @item (neg:@var{m} @var{x})
5226: Represents the negation (subtraction from zero) of the value
5227: represented by @var{x}, carried out in mode @var{m}. @var{x} must be
5228: valid for mode @var{m}.
5229:
5230: @item (mult:@var{m} @var{x} @var{y})
5231: Represents the signed product of the values represented by @var{x} and
5232: @var{y} carried out in machine mode @var{m}. If
5233: @var{x} and @var{y} are both valid for mode @var{m}, this is ordinary
5234: size-preserving multiplication. Alternatively, both @var{x} and @var{y}
5235: may be valid for a different, narrower mode. This represents the
5236: kind of multiplication that generates a product wider than the operands.
5237: Widening multiplication and same-size multiplication are completely
5238: distinct and supported by different machine instructions; machines may
5239: support one but not the other.@refill
5240:
1.1.1.8 root 5241: @code{mult} may be used for floating point multiplication as well.
1.1 root 5242: Then @var{m} is a floating point machine mode.
5243:
5244: @item (umult:@var{m} @var{x} @var{y})
1.1.1.8 root 5245: Like @code{mult} but represents unsigned multiplication. It may be
5246: used in both same-size and widening forms, like @code{mult}.
5247: @code{umult} is used only for fixed-point multiplication.
1.1 root 5248:
5249: @item (div:@var{m} @var{x} @var{y})
5250: Represents the quotient in signed division of @var{x} by @var{y},
5251: carried out in machine mode @var{m}. If @var{m} is a floating-point
5252: mode, it represents the exact quotient; otherwise, the integerized
5253: quotient. If @var{x} and @var{y} are both valid for mode @var{m},
5254: this is ordinary size-preserving division. Some machines have
5255: division instructions in which the operands and quotient widths are
1.1.1.8 root 5256: not all the same; such instructions are represented by @code{div}
1.1 root 5257: expressions in which the machine modes are not all the same.
5258:
5259: @item (udiv:@var{m} @var{x} @var{y})
1.1.1.8 root 5260: Like @code{div} but represents unsigned division.
1.1 root 5261:
5262: @item (mod:@var{m} @var{x} @var{y})
5263: @itemx (umod:@var{m} @var{x} @var{y})
1.1.1.8 root 5264: Like @code{div} and @code{udiv} but represent the remainder instead of
1.1 root 5265: the quotient.
5266:
5267: @item (not:@var{m} @var{x})
5268: Represents the bitwise complement of the value represented by @var{x},
5269: carried out in mode @var{m}, which must be a fixed-point machine mode.
5270: @var{x} must be valid for mode @var{m}, which must be a fixed-point mode.
5271:
5272: @item (and:@var{m} @var{x} @var{y})
5273: Represents the bitwise logical-and of the values represented by
5274: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
5275: valid only if @var{x} and @var{y} both are valid for mode @var{m},
5276: which must be a fixed-point mode.
5277:
5278: @item (ior:@var{m} @var{x} @var{y})
5279: Represents the bitwise inclusive-or of the values represented by
5280: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
5281: valid only if @var{x} and @var{y} both are valid for mode @var{m},
5282: which must be a fixed-point mode.
5283:
5284: @item (xor:@var{m} @var{x} @var{y})
5285: Represents the bitwise exclusive-or of the values represented by
5286: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
5287: valid only if @var{x} and @var{y} both are valid for mode @var{m},
5288: which must be a fixed-point mode.
5289:
5290: @item (lshift:@var{m} @var{x} @var{c})
5291: Represents the result of logically shifting @var{x} left by @var{c}
5292: places. @var{x} must be valid for the mode @var{m}, a fixed-point
5293: machine mode. @var{c} must be valid for a fixed-point mode;
5294: which mode is determined by the mode called for in the machine
5295: description entry for the left-shift instruction. For example,
5296: on the Vax, the mode of @var{c} is @code{QImode} regardless of @var{m}.
5297:
5298: On some machines, negative values of @var{c} may be meaningful; this
5299: is why logical left shift and arithmetic left shift are distinguished.
5300: For example, Vaxes have no right-shift instructions, and right shifts
5301: are represented as left-shift instructions whose counts happen
5302: to be negative constants or else computed (in a previous instruction)
5303: by negation.
5304:
5305: @item (ashift:@var{m} @var{x} @var{c})
1.1.1.8 root 5306: Like @code{lshift} but for arithmetic left shift.
1.1 root 5307:
5308: @item (lshiftrt:@var{m} @var{x} @var{c})
5309: @itemx (ashiftrt:@var{m} @var{x} @var{c})
1.1.1.8 root 5310: Like @code{lshift} and @code{ashift} but for right shift.
1.1 root 5311:
5312: @item (rotate:@var{m} @var{x} @var{c})
5313: @itemx (rotatert:@var{m} @var{x} @var{c})
5314: Similar but represent left and right rotate.
5315:
5316: @item (abs:@var{m} @var{x})
5317: Represents the absolute value of @var{x}, computed in mode @var{m}.
5318: @var{x} must be valid for @var{m}.
5319:
5320: @item (sqrt:@var{m} @var{x})
5321: Represents the square root of @var{x}, computed in mode @var{m}.
5322: @var{x} must be valid for @var{m}. Most often @var{m} will be
5323: a floating point mode.
5324:
5325: @item (ffs:@var{m} @var{x})
1.1.1.10 root 5326: Represents one plus the index of the least significant 1-bit in
1.1 root 5327: @var{x}, represented as an integer of mode @var{m}. (The value is
5328: zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
5329: depending on the target machine, various mode combinations may be
5330: valid.
5331: @end table
5332:
5333: @node Comparisons, Bit Fields, Arithmetic, RTL
5334: @section Comparison Operations
5335:
1.1.1.10 root 5336: Comparison operators test a relation on two operands and are considered
5337: to represent a machine-dependent nonzero value (@code{STORE_FLAG_VALUE})
5338: if the relation holds, or zero if it does not. The mode of the
5339: comparison is determined by the operands; they must both be valid for a
5340: common machine mode. A comparison with both operands constant would be
5341: invalid as the machine mode could not be deduced from it, but such a
5342: comparison should never exist in RTL due to constant folding.
1.1 root 5343:
5344: Inequality comparisons come in two flavors, signed and unsigned. Thus,
1.1.1.8 root 5345: there are distinct expression codes @code{gt} and @code{gtu} for signed and
1.1 root 5346: unsigned greater-than. These can produce different results for the same
5347: pair of integer values: for example, 1 is signed greater-than -1 but not
5348: unsigned greater-than, because -1 when regarded as unsigned is actually
5349: @code{0xffffffff} which is greater than 1.
5350:
5351: The signed comparisons are also used for floating point values. Floating
5352: point comparisons are distinguished by the machine modes of the operands.
5353:
5354: The comparison operators may be used to compare the condition codes
5355: @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such a
5356: construct actually refers to the result of the preceding instruction in
5357: which the condition codes were set. The above example stands for 1 if the
5358: condition codes were set to say ``zero'' or ``equal'', 0 otherwise.
5359: Although the same comparison operators are used for this as may be used in
5360: other contexts on actual data, no confusion can result since the machine
5361: description would never allow both kinds of uses in the same context.
5362:
5363: @table @code
5364: @item (eq @var{x} @var{y})
5365: 1 if the values represented by @var{x} and @var{y} are equal,
5366: otherwise 0.
5367:
5368: @item (ne @var{x} @var{y})
5369: 1 if the values represented by @var{x} and @var{y} are not equal,
5370: otherwise 0.
5371:
5372: @item (gt @var{x} @var{y})
5373: 1 if the @var{x} is greater than @var{y}. If they are fixed-point,
5374: the comparison is done in a signed sense.
5375:
5376: @item (gtu @var{x} @var{y})
1.1.1.8 root 5377: Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
1.1 root 5378:
5379: @item (lt @var{x} @var{y})
5380: @item (ltu @var{x} @var{y})
1.1.1.8 root 5381: Like @code{gt} and @code{gtu} but test for ``less than''.
1.1 root 5382:
5383: @item (ge @var{x} @var{y})
5384: @item (geu @var{x} @var{y})
1.1.1.8 root 5385: Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
1.1 root 5386:
5387: @item (le @var{x} @var{y})
5388: @item (leu @var{x} @var{y})
1.1.1.8 root 5389: Like @code{gt} and @code{gtu} but test for ``less than or equal''.
1.1 root 5390:
5391: @item (if_then_else @var{cond} @var{then} @var{else})
5392: This is not a comparison operation but is listed here because it is
5393: always used in conjunction with a comparison operation. To be
5394: precise, @var{cond} is a comparison expression. This expression
5395: represents a choice, according to @var{cond}, between the value
5396: represented by @var{then} and the one represented by @var{else}.
5397:
1.1.1.8 root 5398: On most machines, @code{if_then_else} expressions are valid only
1.1 root 5399: to express conditional jumps.
5400: @end table
5401:
5402: @node Bit Fields, Conversions, Comparisons, RTL
5403: @section Bit-fields
5404:
5405: Special expression codes exist to represent bit-field instructions.
5406: These types of expressions are lvalues in RTL; they may appear
1.1.1.10 root 5407: on the left side of an assignment, indicating insertion of a value
1.1 root 5408: into the specified bit field.
5409:
5410: @table @code
5411: @item (sign_extract:SI @var{loc} @var{size} @var{pos})
5412: This represents a reference to a sign-extended bit-field contained or
5413: starting in @var{loc} (a memory or register reference). The bit field
5414: is @var{size} bits wide and starts at bit @var{pos}. The compilation
5415: option @code{BITS_BIG_ENDIAN} says which end of the memory unit
5416: @var{pos} counts from.
5417:
5418: Which machine modes are valid for @var{loc} depends on the machine,
5419: but typically @var{loc} should be a single byte when in memory
5420: or a full word in a register.
5421:
5422: @item (zero_extract:SI @var{loc} @var{size} @var{pos})
1.1.1.8 root 5423: Like @code{sign_extract} but refers to an unsigned or zero-extended
1.1 root 5424: bit field. The same sequence of bits are extracted, but they
5425: are filled to an entire word with zeros instead of by sign-extension.
5426: @end table
5427:
5428: @node Conversions, RTL Declarations, Bit Fields, RTL
5429: @section Conversions
5430:
5431: All conversions between machine modes must be represented by
5432: explicit conversion operations. For example, an expression
5433: which is the sum of a byte and a full word cannot be written as
1.1.1.8 root 5434: @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
1.1 root 5435: operation requires two operands of the same machine mode.
5436: Therefore, the byte-sized operand is enclosed in a conversion
5437: operation, as in
5438:
5439: @example
5440: (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
5441: @end example
5442:
5443: The conversion operation is not a mere placeholder, because there
5444: may be more than one way of converting from a given starting mode
5445: to the desired final mode. The conversion operation code says how
5446: to do it.
5447:
5448: @table @code
5449: @item (sign_extend:@var{m} @var{x})
5450: Represents the result of sign-extending the value @var{x}
5451: to machine mode @var{m}. @var{m} must be a fixed-point mode
5452: and @var{x} a fixed-point value of a mode narrower than @var{m}.
5453:
5454: @item (zero_extend:@var{m} @var{x})
5455: Represents the result of zero-extending the value @var{x}
5456: to machine mode @var{m}. @var{m} must be a fixed-point mode
5457: and @var{x} a fixed-point value of a mode narrower than @var{m}.
5458:
5459: @item (float_extend:@var{m} @var{x})
5460: Represents the result of extending the value @var{x}
5461: to machine mode @var{m}. @var{m} must be a floating point mode
5462: and @var{x} a floating point value of a mode narrower than @var{m}.
5463:
5464: @item (truncate:@var{m} @var{x})
5465: Represents the result of truncating the value @var{x}
5466: to machine mode @var{m}. @var{m} must be a fixed-point mode
5467: and @var{x} a fixed-point value of a mode wider than @var{m}.
5468:
5469: @item (float_truncate:@var{m} @var{x})
5470: Represents the result of truncating the value @var{x}
5471: to machine mode @var{m}. @var{m} must be a floating point mode
5472: and @var{x} a floating point value of a mode wider than @var{m}.
5473:
5474: @item (float:@var{m} @var{x})
5475: Represents the result of converting fixed point value @var{x},
5476: regarded as signed, to floating point mode @var{m}.
5477:
5478: @item (unsigned_float:@var{m} @var{x})
5479: Represents the result of converting fixed point value @var{x},
5480: regarded as unsigned, to floating point mode @var{m}.
5481:
5482: @item (fix:@var{m} @var{x})
5483: When @var{m} is a fixed point mode, represents the result of
5484: converting floating point value @var{x} to mode @var{m}, regarded as
5485: signed. How rounding is done is not specified, so this operation may
5486: be used validly in compiling C code only for integer-valued operands.
5487:
5488: @item (unsigned_fix:@var{m} @var{x})
5489: Represents the result of converting floating point value @var{x} to
5490: fixed point mode @var{m}, regarded as unsigned. How rounding is done
5491: is not specified.
5492:
5493: @item (fix:@var{m} @var{x})
5494: When @var{m} is a floating point mode, represents the result of
5495: converting floating point value @var{x} (valid for mode @var{m}) to an
5496: integer, still represented in floating point mode @var{m}, by rounding
5497: towards zero.
5498: @end table
5499:
5500: @node RTL Declarations, Side Effects, Conversions, RTL
5501: @section Declarations
5502:
5503: Declaration expression codes do not represent arithmetic operations
5504: but rather state assertions about their operands.
5505:
5506: @table @code
5507: @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
5508: This expression code is used in only one context: operand 0 of a
1.1.1.8 root 5509: @code{set} expression. In addition, the operand of this expression
5510: must be a @code{subreg} expression.
1.1 root 5511:
1.1.1.8 root 5512: The presence of @code{strict_low_part} says that the part of the
1.1 root 5513: register which is meaningful in mode @var{n}, but is not part of
5514: mode @var{m}, is not to be altered. Normally, an assignment to such
5515: a subreg is allowed to have undefined effects on the rest of the
5516: register when @var{m} is less than a word.
5517: @end table
5518:
5519: @node Side Effects, Incdec, RTL Declarations, RTL
5520: @section Side Effect Expressions
5521:
5522: The expression codes described so far represent values, not actions.
5523: But machine instructions never produce values; they are meaningful
5524: only for their side effects on the state of the machine. Special
5525: expression codes are used to represent side effects.
5526:
5527: The body of an instruction is always one of these side effect codes;
5528: the codes described above, which represent values, appear only as
5529: the operands of these.
5530:
5531: @table @code
5532: @item (set @var{lval} @var{x})
5533: Represents the action of storing the value of @var{x} into the place
5534: represented by @var{lval}. @var{lval} must be an expression
1.1.1.8 root 5535: representing a place that can be stored in: @code{reg} (or
5536: @code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or
5537: @code{cc0}.@refill
1.1 root 5538:
1.1.1.8 root 5539: If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
1.1 root 5540: machine mode; then @var{x} must be valid for that mode.@refill
5541:
1.1.1.8 root 5542: If @var{lval} is a @code{reg} whose machine mode is less than the full
1.1 root 5543: width of the register, then it means that the part of the register
5544: specified by the machine mode is given the specified value and the
5545: rest of the register receives an undefined value. Likewise, if
1.1.1.8 root 5546: @var{lval} is a @code{subreg} whose machine mode is narrower than
1.1 root 5547: @code{SImode}, the rest of the register can be changed in an undefined way.
5548:
1.1.1.8 root 5549: If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the
1.1 root 5550: part of the register specified by the machine mode of the
1.1.1.8 root 5551: @code{subreg} is given the value @var{x} and the rest of the register
1.1 root 5552: is not changed.@refill
5553:
5554: If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
5555: have any mode. This represents a ``test'' or ``compare'' instruction.@refill
5556:
5557: If @var{lval} is @code{(pc)}, we have a jump instruction, and the
5558: possibilities for @var{x} are very limited. It may be a
1.1.1.8 root 5559: @code{label_ref} expression (unconditional jump). It may be an
5560: @code{if_then_else} (conditional jump), in which case either the
1.1 root 5561: second or the third operand must be @code{(pc)} (for the case which
1.1.1.8 root 5562: does not jump) and the other of the two must be a @code{label_ref}
5563: (for the case which does jump). @var{x} may also be a @code{mem} or
5564: @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
5565: @code{mem}; these unusual patterns are used to represent jumps through
1.1 root 5566: branch tables.@refill
5567:
5568: @item (return)
5569: Represents a return from the current function, on machines where this
5570: can be done with one instruction, such as Vaxes. On machines where a
5571: multi-instruction ``epilogue'' must be executed in order to return
5572: from the function, returning is done by jumping to a label which
1.1.1.8 root 5573: precedes the epilogue, and the @code{return} expression code is never
1.1 root 5574: used.
5575:
5576: @item (call @var{function} @var{nargs})
1.1.1.8 root 5577: Represents a function call. @var{function} is a @code{mem} expression
1.1 root 5578: whose address is the address of the function to be called.
5579: @var{nargs} is an expression which can be used for two purposes: on
5580: some machines it represents the number of bytes of stack argument; on
5581: others, it represents the number of argument registers.
5582:
5583: Each machine has a standard machine mode which @var{function} must
5584: have. The machine description defines macro @code{FUNCTION_MODE} to
5585: expand into the requisite mode name. The purpose of this mode is to
5586: specify what kind of addressing is allowed, on machines where the
5587: allowed kinds of addressing depend on the machine mode being
5588: addressed.
5589:
5590: @item (clobber @var{x})
5591: Represents the storing or possible storing of an unpredictable,
1.1.1.8 root 5592: undescribed value into @var{x}, which must be a @code{reg} or
5593: @code{mem} expression.
1.1 root 5594:
5595: One place this is used is in string instructions that store standard
5596: values into particular hard registers. It may not be worth the
5597: trouble to describe the values that are stored, but it is essential to
5598: inform the compiler that the registers will be altered, lest it
5599: attempt to keep data in them across the string instruction.
5600:
5601: @var{x} may also be null---a null C pointer, no expression at all.
5602: Such a @code{(clobber (null))} expression means that all memory
5603: locations must be presumed clobbered.
5604:
5605: Note that the machine description classifies certain hard registers as
5606: ``call-clobbered''. All function call instructions are assumed by
5607: default to clobber these registers, so there is no need to use
1.1.1.8 root 5608: @code{clobber} expressions to indicate this fact. Also, each function
1.1.1.6 root 5609: call is assumed to have the potential to alter any memory location,
5610: unless the function is declared @code{const}.
1.1 root 5611:
1.1.1.8 root 5612: When a @code{clobber} expression for a register appears inside a
5613: @code{parallel} with other side effects, GNU CC guarantees that the
1.1.1.4 root 5614: register is unoccupied both before and after that insn. Therefore, it
5615: is safe for the assembler code produced by the insn to use the
5616: register as a temporary. You can clobber either a specific hard
5617: register or a pseudo register; in the latter case, GNU CC will
5618: allocate a hard register that is available there for use as a
5619: temporary.
5620:
1.1.1.8 root 5621: If you clobber a pseudo register in this way, use a pseudo register
5622: which appears nowhere else---generate a new one each time. Otherwise,
5623: you may confuse CSE.
5624:
5625: There is one other known use for clobbering a pseudo register in a
5626: @code{parallel}: when one of the input operands of the insn is also
5627: clobbered by the insn. In this case, using the same pseudo register in
5628: the clobber and elsewhere in the insn produces the expected results.
5629:
1.1 root 5630: @item (use @var{x})
5631: Represents the use of the value of @var{x}. It indicates that the
5632: value in @var{x} at this point in the program is needed, even though
5633: it may not be apparent why this is so. Therefore, the compiler will
1.1.1.4 root 5634: not attempt to delete previous instructions whose only effect is to
1.1.1.8 root 5635: store a value in @var{x}. @var{x} must be a @code{reg} expression.
1.1 root 5636:
5637: @item (parallel [@var{x0} @var{x1} @dots{}])
5638: Represents several side effects performed in parallel. The square
1.1.1.8 root 5639: brackets stand for a vector; the operand of @code{parallel} is a
1.1 root 5640: vector of expressions. @var{x0}, @var{x1} and so on are individual
1.1.1.8 root 5641: side effect expressions---expressions of code @code{set}, @code{call},
5642: @code{return}, @code{clobber} or @code{use}.@refill
1.1 root 5643:
5644: ``In parallel'' means that first all the values used in the individual
5645: side-effects are computed, and second all the actual side-effects are
5646: performed. For example,
5647:
5648: @example
5649: (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
5650: (set (mem:SI (reg:SI 1)) (reg:SI 1))])
5651: @end example
5652:
5653: @noindent
5654: says unambiguously that the values of hard register 1 and the memory
5655: location addressed by it are interchanged. In both places where
5656: @code{(reg:SI 1)} appears as a memory address it refers to the value
1.1.1.4 root 5657: in register 1 @emph{before} the execution of the insn.
5658:
1.1.1.8 root 5659: It follows that it is @emph{incorrect} to use @code{parallel} and
5660: expect the result of one @code{set} to be available for the next one.
1.1.1.4 root 5661: For example, people sometimes attempt to represent a jump-if-zero
5662: instruction this way:
5663:
5664: @example
5665: (parallel [(set (cc0) (reg:SI 34))
1.1.1.9 root 5666: (set (pc) (if_then_else
5667: (eq (cc0) (const_int 0))
5668: (label_ref @dots{})
5669: (pc)))])
1.1.1.4 root 5670: @end example
5671:
5672: @noindent
5673: But this is incorrect, because it says that the jump condition depends
5674: on the condition code value @emph{before} this instruction, not on the
5675: new value that is set by this instruction.
1.1 root 5676:
1.1.1.5 root 5677: Peephole optimization, which takes place in together with final assembly
1.1.1.8 root 5678: code output, can produce insns whose patterns consist of a @code{parallel}
1.1 root 5679: whose elements are the operands needed to output the resulting
1.1.1.8 root 5680: assembler code---often @code{reg}, @code{mem} or constant expressions.
1.1 root 5681: This would not be well-formed RTL at any other stage in compilation,
5682: but it is ok then because no further optimization remains to be done.
1.1.1.4 root 5683: However, the definition of the macro @code{NOTICE_UPDATE_CC} must
5684: deal with such insns if you define any peephole optimizations.
1.1 root 5685:
5686: @item (sequence [@var{insns} @dots{}])
5687: Represents a sequence of insns. Each of the @var{insns} that appears
5688: in the vector is suitable for appearing in the chain of insns, so it
1.1.1.8 root 5689: must be an @code{insn}, @code{jump_insn}, @code{call_insn},
5690: @code{code_label}, @code{barrier} or @code{note}.
1.1 root 5691:
1.1.1.8 root 5692: A @code{sequence} RTX never appears in an actual insn. It represents
5693: the sequence of insns that result from a @code{define_expand}
1.1 root 5694: @emph{before} those insns are passed to @code{emit_insn} to insert
5695: them in the chain of insns. When actually inserted, the individual
1.1.1.8 root 5696: sub-insns are separated out and the @code{sequence} is forgotten.
1.1 root 5697: @end table
5698:
5699: Three expression codes appear in place of a side effect, as the body of an
5700: insn, though strictly speaking they do not describe side effects as such:
5701:
5702: @table @code
5703: @item (asm_input @var{s})
5704: Represents literal assembler code as described by the string @var{s}.
5705:
5706: @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
5707: Represents a table of jump addresses. The vector elements @var{lr0},
1.1.1.8 root 5708: etc., are @code{label_ref} expressions. The mode @var{m} specifies
1.1 root 5709: how much space is given to each address; normally @var{m} would be
5710: @code{Pmode}.
5711:
5712: @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
5713: Represents a table of jump addresses expressed as offsets from
1.1.1.8 root 5714: @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
1.1 root 5715: expressions and so is @var{base}. The mode @var{m} specifies how much
5716: space is given to each address-difference.@refill
5717: @end table
5718:
5719: @node Incdec, Assembler, Side Effects, RTL
5720: @section Embedded Side-Effects on Addresses
5721:
5722: Four special side-effect expression codes appear as memory addresses.
5723:
5724: @table @code
5725: @item (pre_dec:@var{m} @var{x})
5726: Represents the side effect of decrementing @var{x} by a standard
5727: amount and represents also the value that @var{x} has after being
1.1.1.8 root 5728: decremented. @var{x} must be a @code{reg} or @code{mem}, but most
5729: machines allow only a @code{reg}. @var{m} must be the machine mode
1.1 root 5730: for pointers on the machine in use. The amount @var{x} is decremented
5731: by is the length in bytes of the machine mode of the containing memory
5732: reference of which this expression serves as the address. Here is an
5733: example of its use:@refill
5734:
5735: @example
5736: (mem:DF (pre_dec:SI (reg:SI 39)))
5737: @end example
5738:
5739: @noindent
5740: This says to decrement pseudo register 39 by the length of a @code{DFmode}
5741: value and use the result to address a @code{DFmode} value.
5742:
5743: @item (pre_inc:@var{m} @var{x})
5744: Similar, but specifies incrementing @var{x} instead of decrementing it.
5745:
5746: @item (post_dec:@var{m} @var{x})
1.1.1.8 root 5747: Represents the same side effect as @code{pre_dec} but a different
1.1 root 5748: value. The value represented here is the value @var{x} has @i{before}
5749: being decremented.
5750:
5751: @item (post_inc:@var{m} @var{x})
5752: Similar, but specifies incrementing @var{x} instead of decrementing it.
5753: @end table
5754:
5755: These embedded side effect expressions must be used with care. Instruction
5756: patterns may not use them. Until the @samp{flow} pass of the compiler,
5757: they may occur only to represent pushes onto the stack. The @samp{flow}
5758: pass finds cases where registers are incremented or decremented in one
5759: instruction and used as an address shortly before or after; these cases are
5760: then transformed to use pre- or post-increment or -decrement.
5761:
5762: Explicit popping of the stack could be represented with these embedded
5763: side effect operators, but that would not be safe; the instruction
5764: combination pass could move the popping past pushes, thus changing
5765: the meaning of the code.
5766:
5767: An instruction that can be represented with an embedded side effect
1.1.1.8 root 5768: could also be represented using @code{parallel} containing an additional
5769: @code{set} to describe how the address register is altered. This is not
1.1 root 5770: done because machines that allow these operations at all typically
5771: allow them wherever a memory address is called for. Describing them as
5772: additional parallel stores would require doubling the number of entries
5773: in the machine description.
5774:
5775: @node Assembler, Insns, IncDec, RTL
5776: @section Assembler Instructions as Expressions
5777:
1.1.1.8 root 5778: The RTX code @code{asm_operands} represents a value produced by a
1.1 root 5779: user-specified assembler instruction. It is used to represent
5780: an @code{asm} statement with arguments. An @code{asm} statement with
5781: a single output operand, like this:
5782:
5783: @example
1.1.1.6 root 5784: asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
1.1 root 5785: @end example
5786:
5787: @noindent
1.1.1.8 root 5788: is represented using a single @code{asm_operands} RTX which represents
1.1 root 5789: the value that is stored in @code{outputvar}:
5790:
5791: @example
5792: (set @var{rtx-for-outputvar}
5793: (asm_operands "foo %1,%2,%0" "a" 0
5794: [@var{rtx-for-addition-result} @var{rtx-for-*z}]
5795: [(asm_input:@var{m1} "g")
5796: (asm_input:@var{m2} "di")]))
5797: @end example
5798:
5799: @noindent
1.1.1.8 root 5800: Here the operands of the @code{asm_operands} RTX are the assembler
1.1 root 5801: template string, the output-operand's constraint, the index-number of the
5802: output operand among the output operands specified, a vector of input
5803: operand RTX's, and a vector of input-operand modes and constraints. The
5804: mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
5805: @code{*z}.
5806:
5807: When an @code{asm} statement has multiple output values, its insn has
1.1.1.8 root 5808: several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
5809: contains a @code{asm_operands}; all of these share the same assembler
1.1 root 5810: template and vectors, but each contains the constraint for the respective
5811: output operand. They are also distinguished by the output-operand index
5812: number, which is 0, 1, @dots{} for successive output operands.
5813:
5814: @node Insns, Calls, Assembler, RTL
5815: @section Insns
5816:
5817: The RTL representation of the code for a function is a doubly-linked
5818: chain of objects called @dfn{insns}. Insns are expressions with
5819: special codes that are used for no other purpose. Some insns are
5820: actual instructions; others represent dispatch tables for @code{switch}
5821: statements; others represent labels to jump to or various sorts of
5822: declarative information.
5823:
5824: In addition to its own specific data, each insn must have a unique id-number
5825: that distinguishes it from all other insns in the current function, and
5826: chain pointers to the preceding and following insns. These three fields
5827: occupy the same position in every insn, independent of the expression code
5828: of the insn. They could be accessed with @code{XEXP} and @code{XINT},
5829: but instead three special macros are always used:
5830:
5831: @table @code
5832: @item INSN_UID (@var{i})
5833: Accesses the unique id of insn @var{i}.
5834:
5835: @item PREV_INSN (@var{i})
5836: Accesses the chain pointer to the insn preceding @var{i}.
5837: If @var{i} is the first insn, this is a null pointer.
5838:
5839: @item NEXT_INSN (@var{i})
5840: Accesses the chain pointer to the insn following @var{i}.
5841: If @var{i} is the last insn, this is a null pointer.
5842: @end table
5843:
5844: The @code{NEXT_INSN} and @code{PREV_INSN} pointers must always
1.1.1.6 root 5845: correspond: if @var{insn} is not the first insn,
1.1 root 5846:
5847: @example
5848: NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
5849: @end example
5850:
5851: @noindent
5852: is always true.
5853:
5854: Every insn has one of the following six expression codes:
5855:
1.1.1.8 root 5856: @table @code
1.1 root 5857: @item insn
1.1.1.8 root 5858: The expression code @code{insn} is used for instructions that do not jump
5859: and do not do function calls. Insns with code @code{insn} have four
1.1 root 5860: additional fields beyond the three mandatory ones listed above.
5861: These four are described in a table below.
5862:
5863: @item jump_insn
1.1.1.8 root 5864: The expression code @code{jump_insn} is used for instructions that may jump
5865: (or, more generally, may contain @code{label_ref} expressions).
5866: @code{jump_insn} insns have the same extra fields as @code{insn} insns,
1.1.1.10 root 5867: accessed in the same way. If there is an instruction to return from the
5868: current function, it is recorded as a @code{jump_insn}.
1.1 root 5869:
5870: @item call_insn
1.1.1.8 root 5871: The expression code @code{call_insn} is used for instructions that may do
1.1 root 5872: function calls. It is important to distinguish these instructions because
5873: they imply that certain registers and memory locations may be altered
5874: unpredictably.
5875:
1.1.1.8 root 5876: @code{call_insn} insns have the same extra fields as @code{insn} insns,
1.1 root 5877: accessed in the same way.
5878:
5879: @item code_label
1.1.1.8 root 5880: A @code{code_label} insn represents a label that a jump insn can jump to.
1.1 root 5881: It contains one special field of data in addition to the three standard ones.
5882: It is used to hold the @dfn{label number}, a number that identifies this
5883: label uniquely among all the labels in the compilation (not just in the
5884: current function). Ultimately, the label is represented in the assembler
5885: output as an assembler label @samp{L@var{n}} where @var{n} is the label number.
5886:
5887: @item barrier
5888: Barriers are placed in the instruction stream after unconditional
5889: jump instructions to indicate that the jumps are unconditional.
5890: They contain no information beyond the three standard fields.
5891:
5892: @item note
1.1.1.8 root 5893: @code{note} insns are used to represent additional debugging and
1.1 root 5894: declarative information. They contain two nonstandard fields, an
5895: integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
5896: string accessed with @code{NOTE_SOURCE_FILE}.
5897:
5898: If @code{NOTE_LINE_NUMBER} is positive, the note represents the
5899: position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
5900: that the line came from. These notes control generation of line
5901: number data in the assembler output.
5902:
5903: Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
5904: code with one of the following values (and @code{NOTE_SOURCE_FILE}
5905: must contain a null pointer):
5906:
5907: @table @code
5908: @item NOTE_INSN_DELETED
5909: Such a note is completely ignorable. Some passes of the compiler
5910: delete insns by altering them into notes of this kind.
5911:
5912: @item NOTE_INSN_BLOCK_BEG
5913: @itemx NOTE_INSN_BLOCK_END
5914: These types of notes indicate the position of the beginning and end
5915: of a level of scoping of variable names. They control the output
5916: of debugging information.
5917:
5918: @item NOTE_INSN_LOOP_BEG
5919: @itemx NOTE_INSN_LOOP_END
5920: These types of notes indicate the position of the beginning and end
5921: of a @code{while} or @code{for} loop. They enable the loop optimizer
5922: to find loops quickly.
1.1.1.6 root 5923: @item NOTE_INSN_FUNCTION_END
5924: Appears near the end of the function body, just before the label that
5925: @code{return} statements jump to (on machine where a single instruction
5926: does not suffice for returning). This note may be deleted by jump
5927: optimization.
5928: @item NOTE_INSN_SETJMP
5929: Appears following each call to @code{setjmp} or a related function.
1.1.1.7 root 5930:
1.1.1.10 root 5931: @item NOTE_INSN_LOOP_CONT
1.1.1.7 root 5932: Appears at the place in a loop that @code{continue} statements jump to.
1.1 root 5933: @end table
1.1.1.7 root 5934:
5935: These codes are printed symbolically when they appear in debugging dumps.
1.1 root 5936: @end table
5937:
1.1.1.6 root 5938: The machine mode of an insn is normally zero (@code{VOIDmode}), but the
5939: reload pass sets it to @code{QImode} if the insn needs reloading.
5940:
1.1.1.8 root 5941: Here is a table of the extra fields of @code{insn}, @code{jump_insn}
5942: and @code{call_insn} insns:
1.1 root 5943:
5944: @table @code
5945: @item PATTERN (@var{i})
5946: An expression for the side effect performed by this insn.
5947:
1.1.1.6 root 5948: @item INSN_CODE (@var{i})
5949: An integer that says which pattern in the machine description matches
5950: this insn, or -1 if the matching has not yet been attempted.
5951:
5952: Such matching is never attempted and this field is not used on an insn
1.1.1.8 root 5953: whose pattern consists of a single @code{use}, @code{clobber},
5954: @code{asm}, @code{addr_vec} or @code{addr_diff_vec} expression.
1.1 root 5955:
5956: @item LOG_LINKS (@var{i})
1.1.1.8 root 5957: A list (chain of @code{insn_list} expressions) of previous ``related''
1.1 root 5958: insns: insns which store into registers values that are used for the
5959: first time in this insn. (An additional constraint is that neither a
5960: jump nor a label may come between the related insns). This list is
5961: set up by the flow analysis pass; it is a null pointer until then.
5962:
1.1.1.6 root 5963: @item REG_NOTES (@var{i})
1.1.1.8 root 5964: A list (chain of @code{expr_list} expressions) giving information
1.1.1.6 root 5965: about the usage of registers in this insn. This list is set up by the
5966: flow analysis pass; it is a null pointer until then.
1.1 root 5967: @end table
5968:
1.1.1.8 root 5969: The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
1.1 root 5970: expressions. Each of these has two operands: the first is an insn,
1.1.1.8 root 5971: and the second is another @code{insn_list} expression (the next one in
5972: the chain). The last @code{insn_list} in the chain has a null pointer
1.1 root 5973: as second operand. The significant thing about the chain is which
1.1.1.8 root 5974: insns appear in it (as first operands of @code{insn_list}
1.1 root 5975: expressions). Their order is not significant.
5976:
5977: The @code{REG_NOTES} field of an insn is a similar chain but of
1.1.1.8 root 5978: @code{expr_list} expressions instead of @code{insn_list}. There are
1.1.1.5 root 5979: several kinds of register notes, which are distinguished by the machine
1.1.1.8 root 5980: mode of the @code{expr_list}, which in a register note is really
1.1.1.5 root 5981: understood as being an @code{enum reg_note}. The first operand @var{op}
1.1.1.8 root 5982: of the @code{expr_list} is data whose meaning depends on the kind of
1.1.1.5 root 5983: note. Here are the kinds of register note:
1.1 root 5984:
5985: @table @code
5986: @item REG_DEAD
5987: The register @var{op} dies in this insn; that is to say, altering the
5988: value immediately after this insn would not affect the future behavior
5989: of the program.
5990:
5991: @item REG_INC
5992: The register @var{op} is incremented (or decremented; at this level
5993: there is no distinction) by an embedded side effect inside this insn.
1.1.1.8 root 5994: This means it appears in a @code{post_inc}, @code{pre_inc},
5995: @code{post_dec} or @code{pre_dec} RTX.
1.1 root 5996:
5997: @item REG_EQUIV
5998: The register that is set by this insn will be equal to @var{op} at run
5999: time, and could validly be replaced in all its occurrences by
6000: @var{op}. (``Validly'' here refers to the data flow of the program;
6001: simple replacement may make some insns invalid.)
6002:
6003: The value which the insn explicitly copies into the register may look
6004: different from @var{op}, but they will be equal at run time.
6005:
6006: For example, when a constant is loaded into a register that is never
6007: assigned any other value, this kind of note is used.
6008:
6009: When a parameter is copied into a pseudo-register at entry to a function,
6010: a note of this kind records that the register is equivalent to the stack
6011: slot where the parameter was passed. Although in this case the register
6012: may be set by other insns, it is still valid to replace the register
6013: by the stack slot throughout the function.
6014:
6015: @item REG_EQUAL
6016: The register that is set by this insn will be equal to @var{op} at run
6017: time at the end of this insn (but not necessarily elsewhere in the
6018: function).
6019:
6020: The RTX @var{op} is typically an arithmetic expression. For example,
6021: when a sequence of insns such as a library call is used to perform an
6022: arithmetic operation, this kind of note is attached to the insn that
6023: produces or copies the final value. It tells the CSE pass how to
6024: think of that value.
6025:
6026: @item REG_RETVAL
6027: This insn copies the value of a library call, and @var{op} is the
6028: first insn that was generated to set up the arguments for the library
6029: call.
6030:
6031: Flow analysis uses this note to delete all of a library call whose
6032: result is dead.
6033:
6034: @item REG_WAS_0
6035: The register @var{op} contained zero before this insn. You can rely
6036: on this note if it is present; its absence implies nothing.
6037:
6038: @item REG_LIBCALL
6039: This is the inverse of @code{REG_RETVAL}: it is placed on the first
6040: insn of a library call, and it points to the last one.
6041:
6042: Loop optimization uses this note to move an entire library call out
6043: of a loop when its value is constant.
6044:
6045: @item REG_NONNEG
6046: The register @var{op} is known to have nonnegative value when this
6047: insn is reached.
6048: @end table
6049:
1.1.1.8 root 6050: For convenience, the machine mode in an @code{insn_list} or
6051: @code{expr_list} is printed using these symbolic codes in debugging dumps.
1.1.1.7 root 6052:
1.1.1.8 root 6053: The only difference between the expression codes @code{insn_list} and
6054: @code{expr_list} is that the first operand of an @code{insn_list} is
1.1 root 6055: assumed to be an insn and is printed in debugging dumps as the insn's
1.1.1.8 root 6056: unique id; the first operand of an @code{expr_list} is printed in the
1.1.1.7 root 6057: ordinary way as an expression.
1.1 root 6058:
6059: @node Calls, Sharing, Insns, RTL
6060: @section RTL Representation of Function-Call Insns
6061:
1.1.1.8 root 6062: Insns that call subroutines have the RTL expression code @code{call_insn}.
1.1 root 6063: These insns must satisfy special rules, and their bodies must use a special
1.1.1.8 root 6064: RTL expression code, @code{call}.
1.1 root 6065:
1.1.1.8 root 6066: A @code{call} expression has two operands, as follows:
1.1 root 6067:
6068: @example
1.1.1.6 root 6069: (call (mem:@var{fm} @var{addr}) @var{nbytes})
1.1 root 6070: @end example
6071:
6072: @noindent
6073: Here @var{nbytes} is an operand that represents the number of bytes of
6074: argument data being passed to the subroutine, @var{fm} is a machine mode
6075: (which must equal as the definition of the @code{FUNCTION_MODE} macro in
6076: the machine description) and @var{addr} represents the address of the
6077: subroutine.
6078:
1.1.1.8 root 6079: For a subroutine that returns no value, the @code{call} RTX as shown above
1.1 root 6080: is the entire body of the insn.
6081:
6082: For a subroutine that returns a value whose mode is not @code{BLKmode},
6083: the value is returned in a hard register. If this register's number is
6084: @var{r}, then the body of the call insn looks like this:
6085:
6086: @example
6087: (set (reg:@var{m} @var{r})
1.1.1.9 root 6088: (call (mem:@var{fm} @var{addr}) @var{nbytes}))
1.1 root 6089: @end example
6090:
6091: @noindent
6092: This RTL expression makes it clear (to the optimizer passes) that the
6093: appropriate register receives a useful value in this insn.
6094:
6095: Immediately after RTL generation, if the value of the subroutine is
6096: actually used, this call insn is always followed closely by an insn which
6097: refers to the register @var{r}. This remains true through all the
6098: optimizer passes until cross jumping occurs.
6099:
6100: The following insn has one of two forms. Either it copies the value into a
6101: pseudo-register, like this:
6102:
6103: @example
6104: (set (reg:@var{m} @var{p}) (reg:@var{m} @var{r}))
6105: @end example
6106:
6107: @noindent
6108: or (in the case where the calling function will simply return whatever
6109: value the call produced, and no operation is needed to do this):
6110:
6111: @example
6112: (use (reg:@var{m} @var{r}))
6113: @end example
6114:
6115: @noindent
6116: Between the call insn and this following insn there may intervene only a
1.1.1.8 root 6117: stack-adjustment insn (and perhaps some @code{note} insns).
1.1 root 6118:
6119: When a subroutine returns a @code{BLKmode} value, it is handled by
6120: passing to the subroutine the address of a place to store the value.
6121: So the call insn itself does not ``return'' any value, and it has the
6122: same RTL form as a call that returns nothing.
6123:
6124: @node Sharing,, Calls, RTL
6125: @section Structure Sharing Assumptions
6126:
6127: The compiler assumes that certain kinds of RTL expressions are unique;
6128: there do not exist two distinct objects representing the same value.
6129: In other cases, it makes an opposite assumption: that no RTL expression
6130: object of a certain kind appears in more than one place in the
6131: containing structure.
6132:
6133: These assumptions refer to a single function; except for the RTL
6134: objects that describe global variables and external functions,
6135: no RTL objects are common to two functions.
6136:
6137: @itemize @bullet
6138: @item
1.1.1.8 root 6139: Each pseudo-register has only a single @code{reg} object to represent it,
1.1 root 6140: and therefore only a single machine mode.
6141:
6142: @item
1.1.1.8 root 6143: For any symbolic label, there is only one @code{symbol_ref} object
1.1 root 6144: referring to it.
6145:
6146: @item
1.1.1.8 root 6147: There is only one @code{const_int} expression with value zero,
1.1 root 6148: and only one with value one.
6149:
6150: @item
1.1.1.8 root 6151: There is only one @code{pc} expression.
1.1 root 6152:
6153: @item
1.1.1.8 root 6154: There is only one @code{cc0} expression.
1.1 root 6155:
6156: @item
1.1.1.8 root 6157: There is only one @code{const_double} expression with mode
1.1 root 6158: @code{SFmode} and value zero, and only one with mode @code{DFmode} and
6159: value zero.
6160:
6161: @item
1.1.1.8 root 6162: No @code{label_ref} appears in more than one place in the RTL
1.1 root 6163: structure; in other words, it is safe to do a tree-walk of all the
1.1.1.8 root 6164: insns in the function and assume that each time a @code{label_ref} is
1.1 root 6165: seen it is distinct from all others that are seen.
6166:
6167: @item
1.1.1.8 root 6168: Only one @code{mem} object is normally created for each static
1.1 root 6169: variable or stack slot, so these objects are frequently shared in all
6170: the places they appear. However, separate but equal objects for these
6171: variables are occasionally made.
6172:
6173: @item
1.1.1.5 root 6174: When a single @code{asm} statement has multiple output operands,
6175: a distinct @code{asm_operands} RTX is made for each output operand.
6176: However, these all share the vector which contains the sequence of
6177: input operands. Because this sharing is used later on to test whether
6178: two @code{asm_operands} RTX's come from the same statement, the sharing
6179: must be guaranteed to be preserved.
6180:
6181: @item
1.1 root 6182: No RTL object appears in more than one place in the RTL structure
6183: except as described above. Many passes of the compiler rely on this
6184: by assuming that they can modify RTL objects in place without unwanted
6185: side-effects on other insns.
6186:
6187: @item
6188: During initial RTL generation, shared structure is freely introduced.
6189: After all the RTL for a function has been generated, all shared
6190: structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
6191: after which the above rules are guaranteed to be followed.
6192:
6193: @item
6194: During the combiner pass, shared structure with an insn can exist
6195: temporarily. However, the shared structure is copied before the
6196: combiner is finished with the insn. This is done by
1.1.1.8 root 6197: @code{copy_substitutions} in @file{combine.c}.
1.1 root 6198: @end itemize
6199:
6200: @node Machine Desc, Machine Macros, RTL, Top
6201: @chapter Machine Descriptions
6202:
6203: A machine description has two parts: a file of instruction patterns
6204: (@file{.md} file) and a C header file of macro definitions.
6205:
6206: The @file{.md} file for a target machine contains a pattern for each
6207: instruction that the target machine supports (or at least each instruction
6208: that is worth telling the compiler about). It may also contain comments.
6209: A semicolon causes the rest of the line to be a comment, unless the semicolon
6210: is inside a quoted string.
6211:
6212: See the next chapter for information on the C header file.
6213:
6214: @menu
6215: * Patterns:: How to write instruction patterns.
1.1.1.8 root 6216: * Example:: An explained example of a @code{define_insn} pattern.
1.1 root 6217: * RTL Template:: The RTL template defines what insns match a pattern.
6218: * Output Template:: The output template says how to make assembler code
6219: from such an insn.
6220: * Output Statement:: For more generality, write C code to output
6221: the assembler code.
6222: * Constraints:: When not all operands are general operands.
6223: * Standard Names:: Names mark patterns to use for code generation.
6224: * Pattern Ordering:: When the order of patterns makes a difference.
6225: * Dependent Patterns:: Having one pattern may make you need another.
6226: * Jump Patterns:: Special considerations for patterns for jump insns.
6227: * Peephole Definitions::Defining machine-specific peephole optimizations.
6228: * Expander Definitions::Generating a sequence of several RTL insns
6229: for a standard operation.
6230: @end menu
6231:
6232: @node Patterns, Example, Machine Desc, Machine Desc
6233: @section Everything about Instruction Patterns
6234:
6235: Each instruction pattern contains an incomplete RTL expression, with pieces
6236: to be filled in later, operand constraints that restrict how the pieces can
6237: be filled in, and an output pattern or C code to generate the assembler
1.1.1.8 root 6238: output, all wrapped up in a @code{define_insn} expression.
1.1 root 6239:
1.1.1.8 root 6240: A @code{define_insn} is an RTL expression containing four or five operands:
1.1 root 6241:
6242: @enumerate
6243: @item
6244: An optional name. The presence of a name indicate that this instruction
6245: pattern can perform a certain standard job for the RTL-generation
6246: pass of the compiler. This pass knows certain names and will use
6247: the instruction patterns with those names, if the names are defined
6248: in the machine description.
6249:
6250: The absence of a name is indicated by writing an empty string
6251: where the name should go. Nameless instruction patterns are never
6252: used for generating RTL code, but they may permit several simpler insns
6253: to be combined later on.
6254:
6255: Names that are not thus known and used in RTL-generation have no
6256: effect; they are equivalent to no name at all.
6257:
6258: @item
6259: The @dfn{RTL template} (@pxref{RTL Template}) is a vector of
6260: incomplete RTL expressions which show what the instruction should look
1.1.1.8 root 6261: like. It is incomplete because it may contain @code{match_operand}
6262: and @code{match_dup} expressions that stand for operands of the
1.1 root 6263: instruction.
6264:
1.1.1.10 root 6265: If the vector has only one element, that element is the template for the
6266: instruction pattern. If the vector has multiple elements, then the
6267: instruction pattern is a @code{parallel} expression containing the
6268: elements described.
1.1 root 6269:
6270: @item
6271: A condition. This is a string which contains a C expression that is
6272: the final test to decide whether an insn body matches this pattern.
6273:
6274: For a named pattern, the condition (if present) may not depend on
6275: the data in the insn being matched, but only the target-machine-type
6276: flags. The compiler needs to test these conditions during
6277: initialization in order to learn exactly which named instructions are
6278: available in a particular run.
6279:
6280: For nameless patterns, the condition is applied only when matching an
6281: individual insn, and only after the insn has matched the pattern's
6282: recognition template. The insn's operands may be found in the vector
6283: @code{operands}.
6284:
6285: @item
6286: The @dfn{output template}: a string that says how to output matching
6287: insns as assembler code. @samp{%} in this string specifies where
6288: to substitute the value of an operand. @xref{Output Template}.
6289:
6290: When simple substitution isn't general enough, you can specify a piece
6291: of C code to compute the output. @xref{Output Statement}.
6292:
6293: @item
6294: Optionally, some @dfn{machine-specific information}. The meaning
6295: of this information is defined only by an individual machine description;
6296: typically it might say whether this insn alters the condition codes,
6297: or how many bytes of output it generates.
6298:
6299: This operand is written as a string containing a C initializer
6300: (complete with braces) for the structure type @code{INSN_MACHINE_INFO},
6301: whose definition is up to you (@pxref{Misc}).
6302: @end enumerate
6303:
6304: @node Example, RTL Template, Patterns, Machine Desc
1.1.1.8 root 6305: @section Example of @code{define_insn}
1.1 root 6306:
6307: Here is an actual example of an instruction pattern, for the 68000/68020.
6308:
6309: @example
6310: (define_insn "tstsi"
6311: [(set (cc0)
6312: (match_operand:SI 0 "general_operand" "rm"))]
6313: ""
6314: "*
6315: @{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
6316: return \"tstl %0\";
6317: return \"cmpl #0,%0\"; @}")
6318: @end example
6319:
6320: This is an instruction that sets the condition codes based on the value of
6321: a general operand. It has no condition, so any insn whose RTL description
6322: has the form shown may be handled according to this pattern. The name
6323: @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
6324: pass that, when it is necessary to test such a value, an insn to do so
6325: can be constructed using this pattern.
6326:
6327: The output control string is a piece of C code which chooses which
6328: output template to return based on the kind of operand and the specific
6329: type of CPU for which code is being generated.
6330:
6331: @samp{"rm"} is an operand constraint. Its meaning is explained below.
6332:
6333: @node RTL Template, Output Template, Example, Machine Desc
6334: @section RTL Template for Generating and Recognizing Insns
6335:
6336: The RTL template is used to define which insns match the particular pattern
6337: and how to find their operands. For named patterns, the RTL template also
6338: says how to construct an insn from specified operands.
6339:
6340: Construction involves substituting specified operands into a copy of the
6341: template. Matching involves determining the values that serve as the
6342: operands in the insn being matched. Both of these activities are
6343: controlled by special expression types that direct matching and
6344: substitution of the operands.
6345:
6346: @table @code
1.1.1.8 root 6347: @item (match_operand:@var{m} @var{n} @var{pred} @var{constraint})
1.1 root 6348: This expression is a placeholder for operand number @var{n} of
6349: the insn. When constructing an insn, operand number @var{n}
6350: will be substituted at this point. When matching an insn, whatever
6351: appears at this position in the insn will be taken as operand
1.1.1.8 root 6352: number @var{n}; but it must satisfy @var{pred} or this instruction
1.1 root 6353: pattern will not match at all.
6354:
6355: Operand numbers must be chosen consecutively counting from zero in
1.1.1.8 root 6356: each instruction pattern. There may be only one @code{match_operand}
1.1 root 6357: expression in the pattern for each operand number. Usually operands
1.1.1.8 root 6358: are numbered in the order of appearance in @code{match_operand}
1.1 root 6359: expressions.
6360:
1.1.1.8 root 6361: @var{pred} is a string that is the name of a C function that accepts
6362: two arguments, an expression and a machine mode. During matching, the
6363: function will be called with the putative operand as the expression
6364: and @var{m} as the mode argument. If it returns zero, this
6365: instruction pattern fails to match. @var{pred} may be an empty
6366: string; then it means no test is to be done on the operand,
6367: so anything which occurs in this position is valid.
6368:
6369: @var{constraint} controls reloading and the choice of the best register
6370: class to use for a value, as explained later (@pxref{Constraints}).
6371:
6372: People are often unclear on the difference between the constraint and the
6373: predicate. The predicate helps decide whether a given insn matches the
6374: pattern. The constraint plays no role in this decision; instead, it
6375: controls various decisions in the case of an insn which does match.
6376:
6377: Most often, @var{pred} is @code{"general_operand"}. This function checks
6378: that the putative operand is either a constant, a register or a memory
6379: reference, and that it is valid for mode @var{m}.
1.1 root 6380:
1.1.1.8 root 6381: For an operand that must be a register, @var{pred} should be
1.1 root 6382: @code{"register_operand"}. It would be valid to use
6383: @code{"general_operand"}, since the reload pass would copy any
6384: non-register operands through registers, but this would make GNU CC do
6385: extra work, and it would prevent the register allocator from doing the
6386: best possible job.
6387:
1.1.1.8 root 6388: For an operand that must be a constant, either @var{pred} should be
1.1 root 6389: @code{"immediate_operand"}, or the instruction pattern's extra
6390: condition should check for constants, or both. You cannot expect the
6391: constraints to do this work! If the constraints allow only constants,
6392: but the predicate allows something else, the compiler will crash when
6393: that case arises.
6394:
6395: @item (match_dup @var{n})
6396: This expression is also a placeholder for operand number @var{n}.
6397: It is used when the operand needs to appear more than once in the
6398: insn.
6399:
1.1.1.8 root 6400: In construction, @code{match_dup} behaves exactly like
6401: @code{match_operand}: the operand is substituted into the insn being
6402: constructed. But in matching, @code{match_dup} behaves differently.
1.1 root 6403: It assumes that operand number @var{n} has already been determined by
1.1.1.8 root 6404: a @code{match_operand} appearing earlier in the recognition template,
1.1 root 6405: and it matches only an identical-looking expression.
6406:
1.1.1.4 root 6407: @item (match_operator:@var{m} @var{n} "@var{predicate}" [@var{operands}@dots{}])
6408: This pattern is a kind of placeholder for a variable RTL expression
6409: code.
6410:
6411: When constructing an insn, it stands for an RTL expression whose
6412: expression code is taken from that of operand @var{n}, and whose
6413: operands are constructed from the patterns @var{operands}.
6414:
6415: When matching an expression, it matches an expression if the function
6416: @var{predicate} returns nonzero on that expression @emph{and} the
6417: patterns @var{operands} match the operands of the expression.
6418:
6419: Suppose that the function @code{commutative_operator} is defined as
6420: follows, to match any expression whose operator is one of the six
6421: commutative arithmetic operators of RTL and whose mode is @var{mode}:
6422:
6423: @example
6424: int
6425: commutative_operator (x, mode)
6426: rtx x;
6427: enum machine_mode mode;
6428: @{
6429: enum rtx_code code = GET_CODE (x);
6430: if (GET_MODE (x) != mode)
6431: return 0;
6432: return (code == PLUS || code == MULT || code == UMULT
6433: || code == AND || code == IOR || code == XOR);
6434: @}
6435: @end example
6436:
6437: Then the following pattern will match any RTL expression consisting
6438: of a commutative operator applied to two general operands:
6439:
6440: @example
6441: (match_operator:SI 2 "commutative_operator"
6442: [(match_operand:SI 3 "general_operand" "g")
6443: (match_operand:SI 4 "general_operand" "g")])
6444: @end example
6445:
6446: Here the vector @code{[@var{operands}@dots{}]} contains two patterns
6447: because the expressions to be matched all contain two operands.
6448:
6449: When this pattern does match, the two operands of the commutative
6450: operator are recorded as operands 3 and 4 of the insn. (This is done
1.1.1.8 root 6451: by the two instances of @code{match_operand}.) Operand 2 of the insn
1.1.1.4 root 6452: will be the entire commutative expression: use @code{GET_CODE
6453: (operands[2])} to see which commutative operator was used.
6454:
1.1.1.8 root 6455: The machine mode @var{m} of @code{match_operator} works like that of
6456: @code{match_operand}: it is passed as the second argument to the
1.1.1.4 root 6457: predicate function, and that function is solely responsible for
6458: deciding whether the expression to be matched ``has'' that mode.
6459:
6460: When constructing an insn, argument 2 of the gen-function will specify
6461: the operation (i.e. the expression code) for the expression to be
6462: made. It should be an RTL expression, whose expression code is copied
6463: into a new expression whose operands are arguments 3 and 4 of the
6464: gen-function. The subexpressions of argument 2 are not used;
6465: only its expression code matters.
6466:
1.1.1.8 root 6467: There is no way to specify constraints in @code{match_operator}. The
6468: operand of the insn which corresponds to the @code{match_operator}
1.1.1.4 root 6469: never has any constraints because it is never reloaded as a whole.
6470: However, if parts of its @var{operands} are matched by
1.1.1.8 root 6471: @code{match_operand} patterns, those parts may have constraints of
1.1.1.4 root 6472: their own.
6473:
1.1 root 6474: @item (address (match_operand:@var{m} @var{n} "address_operand" ""))
6475: This complex of expressions is a placeholder for an operand number
6476: @var{n} in a ``load address'' instruction: an operand which specifies
6477: a memory location in the usual way, but for which the actual operand
6478: value used is the address of the location, not the contents of the
6479: location.
6480:
1.1.1.8 root 6481: @code{address} expressions never appear in RTL code, only in machine
1.1 root 6482: descriptions. And they are used only in machine descriptions that do
6483: not use the operand constraint feature. When operand constraints are
6484: in use, the letter @samp{p} in the constraint serves this purpose.
6485:
6486: @var{m} is the machine mode of the @emph{memory location being
6487: addressed}, not the machine mode of the address itself. That mode is
6488: always the same on a given target machine (it is @code{Pmode}, which
6489: normally is @code{SImode}), so there is no point in mentioning it;
1.1.1.8 root 6490: thus, no machine mode is written in the @code{address} expression. If
1.1 root 6491: some day support is added for machines in which addresses of different
6492: kinds of objects appear differently or are used differently (such as
6493: the PDP-10), different formats would perhaps need different machine
1.1.1.8 root 6494: modes and these modes might be written in the @code{address}
1.1 root 6495: expression.
6496: @end table
6497:
6498: @node Output Template, Output Statement, RTL Template, Machine Desc
6499: @section Output Templates and Operand Substitution
6500:
1.1.1.6 root 6501: The @dfn{output template} is a string which specifies how to output the
6502: assembler code for an instruction pattern. Most of the template is a
6503: fixed string which is output literally. The character @samp{%} is used
6504: to specify where to substitute an operand; it can also be used to
6505: identify places where different variants of the assembler require
1.1 root 6506: different syntax.
6507:
6508: In the simplest case, a @samp{%} followed by a digit @var{n} says to output
6509: operand @var{n} at that point in the string.
6510:
6511: @samp{%} followed by a letter and a digit says to output an operand in an
6512: alternate fashion. Four letters have standard, built-in meanings described
6513: below. The machine description macro @code{PRINT_OPERAND} can define
6514: additional letters with nonstandard meanings.
6515:
6516: @samp{%c@var{digit}} can be used to substitute an operand that is a
6517: constant value without the syntax that normally indicates an immediate
6518: operand.
6519:
6520: @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
6521: the constant is negated before printing.
6522:
6523: @samp{%a@var{digit}} can be used to substitute an operand as if it were a
6524: memory reference, with the actual operand treated as the address. This may
6525: be useful when outputting a ``load address'' instruction, because often the
6526: assembler syntax for such an instruction requires you to write the operand
6527: as if it were a memory reference.
6528:
6529: @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
6530: instruction.
6531:
6532: @samp{%} followed by a punctuation character specifies a substitution that
6533: does not use an operand. Only one case is standard: @samp{%%} outputs a
6534: @samp{%} into the assembler code. Other nonstandard cases can be
1.1.1.8 root 6535: defined in the @code{PRINT_OPERAND} macro. You must also define
6536: which punctuation characters are valid with the
6537: @code{PRINT_OPERAND_PUNCT_VALID_P} macro.
1.1 root 6538:
6539: The template may generate multiple assembler instructions. Write the text
6540: for the instructions, with @samp{\;} between them.
6541:
1.1.1.6 root 6542: When the RTL contains two operands which are required by constraint to match
1.1 root 6543: each other, the output template must refer only to the lower-numbered operand.
6544: Matching operands are not always identical, and the rest of the compiler
6545: arranges to put the proper RTL expression for printing into the lower-numbered
6546: operand.
6547:
6548: One use of nonstandard letters or punctuation following @samp{%} is to
6549: distinguish between different assembler languages for the same machine; for
6550: example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax
6551: requires periods in most opcode names, while MIT syntax does not. For
6552: example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
6553: syntax. The same file of patterns is used for both kinds of output syntax,
6554: but the character sequence @samp{%.} is used in each place where Motorola
6555: syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax
6556: defines the sequence to output a period; the macro for MIT syntax defines
6557: it to do nothing.
6558:
6559: @node Output Statement, Constraints, Output Template, Machine Desc
6560: @section C Statements for Generating Assembler Output
6561:
6562: Often a single fixed template string cannot produce correct and efficient
6563: assembler code for all the cases that are recognized by a single
6564: instruction pattern. For example, the opcodes may depend on the kinds of
6565: operands; or some unfortunate combinations of operands may require extra
6566: machine instructions.
6567:
6568: If the output control string starts with a @samp{*}, then it is not an
6569: output template but rather a piece of C program that should compute a
6570: template. It should execute a @code{return} statement to return the
6571: template-string you want. Most such templates use C string literals, which
6572: require doublequote characters to delimit them. To include these
6573: doublequote characters in the string, prefix each one with @samp{\}.
6574:
6575: The operands may be found in the array @code{operands}, whose C data type
6576: is @code{rtx []}.
6577:
6578: It is possible to output an assembler instruction and then go on to output
6579: or compute more of them, using the subroutine @code{output_asm_insn}. This
6580: receives two arguments: a template-string and a vector of operands. The
6581: vector may be @code{operands}, or it may be another array of @code{rtx}
6582: that you declare locally and initialize yourself.
6583:
6584: When an insn pattern has multiple alternatives in its constraints, often
1.1.1.5 root 6585: the appearance of the assembler code is determined mostly by which alternative
1.1 root 6586: was matched. When this is so, the C code can test the variable
6587: @code{which_alternative}, which is the ordinal number of the alternative
6588: that was actually satisfied (0 for the first, 1 for the second alternative,
6589: etc.).
6590:
6591: For example, suppose there are two opcodes for storing zero, @samp{clrreg}
6592: for registers and @samp{clrmem} for memory locations. Here is how
6593: a pattern could use @code{which_alternative} to choose between them:
6594:
6595: @example
6596: (define_insn ""
1.1.1.13 root 6597: [(set (match_operand:SI 0 "general_operand" "=r,m")
1.1 root 6598: (const_int 0))]
6599: ""
6600: "*
6601: return (which_alternative == 0
6602: ? \"clrreg %0\" : \"clrmem %0\");
6603: ")
6604: @end example
6605:
6606: @node Constraints, Standard Names, Output Statement, Machine Desc
6607: @section Operand Constraints
6608:
1.1.1.8 root 6609: Each @code{match_operand} in an instruction pattern can specify a
1.1 root 6610: constraint for the type of operands allowed. Constraints can say whether
6611: an operand may be in a register, and which kinds of register; whether the
6612: operand can be a memory reference, and which kinds of address; whether the
6613: operand may be an immediate constant, and which possible values it may
6614: have. Constraints can also require two operands to match.
6615:
6616: @menu
6617: * Simple Constraints:: Basic use of constraints.
6618: * Multi-Alternative:: When an insn has two alternative constraint-patterns.
6619: * Class Preferences:: Constraints guide which hard register to put things in.
6620: * Modifiers:: More precise control over effects of constraints.
6621: * No Constraints:: Describing a clean machine without constraints.
6622: @end menu
6623:
6624: @node Simple Constraints, Multi-Alternative, Constraints, Constraints
6625: @subsection Simple Constraints
6626:
6627: The simplest kind of constraint is a string full of letters, each of
6628: which describes one kind of operand that is permitted. Here are
6629: the letters that are allowed:
6630:
6631: @table @asis
6632: @item @samp{m}
6633: A memory operand is allowed, with any kind of address that the machine
6634: supports in general.
6635:
6636: @item @samp{o}
6637: A memory operand is allowed, but only if the address is
1.1.1.8 root 6638: @dfn{offsettable}. This means that adding a small integer (actually,
1.1 root 6639: the width in bytes of the operand, as determined by its machine mode)
6640: may be added to the address and the result is also a valid memory
6641: address.
6642:
1.1.1.8 root 6643: For example, an address which is constant is offsettable; so is an
1.1 root 6644: address that is the sum of a register and a constant (as long as a
6645: slightly larger constant is also within the range of address-offsets
6646: supported by the machine); but an autoincrement or autodecrement
1.1.1.8 root 6647: address is not offsettable. More complicated indirect/indexed
6648: addresses may or may not be offsettable depending on the other
1.1 root 6649: addressing modes that the machine supports.
6650:
6651: Note that in an output operand which can be matched by another
6652: operand, the constraint letter @samp{o} is valid only when accompanied
6653: by both @samp{<} (if the target machine has predecrement addressing)
6654: and @samp{>} (if the target machine has preincrement addressing).
6655:
6656: When the constraint letter @samp{o} is used, the reload pass may
1.1.1.8 root 6657: generate instructions which copy a nonoffsettable address into an index
1.1 root 6658: register. The idea is that the register can be used as a replacement
1.1.1.8 root 6659: offsettable address. But this method requires that there be patterns
1.1 root 6660: to copy any kind of address into a register. Auto-increment
6661: and auto-decrement addresses are an exception; there need not be an
6662: instruction that can copy such an address into a register, because
6663: reload handles these cases specially.
6664:
6665: Most older machine designs have ``load address'' instructions which do
6666: just what is needed here. Some RISC machines do not advertise such
6667: instructions, but the possible addresses on these machines are very
6668: limited, so it is easy to fake them.
6669:
6670: @item @samp{<}
6671: A memory operand with autodecrement addressing (either predecrement or
6672: postdecrement) is allowed.
6673:
6674: @item @samp{>}
6675: A memory operand with autoincrement addressing (either preincrement or
6676: postincrement) is allowed.
6677:
6678: @item @samp{r}
6679: A register operand is allowed provided that it is in a general
6680: register.
6681:
6682: @item @samp{d}, @samp{a}, @samp{f}, @dots{}
6683: Other letters can be defined in machine-dependent fashion to stand for
6684: particular classes of registers. @samp{d}, @samp{a} and @samp{f} are
6685: defined on the 68000/68020 to stand for data, address and floating
6686: point registers.
6687:
6688: @item @samp{i}
6689: An immediate integer operand (one with constant value) is allowed.
6690: This includes symbolic constants whose values will be known only at
6691: assembly time.
6692:
6693: @item @samp{n}
6694: An immediate integer operand with a known numeric value is allowed.
6695: Many systems cannot support assembly-time constants for operands less
6696: than a word wide. Constraints for these operands should use @samp{n}
6697: rather than @samp{i}.
6698:
6699: @item @samp{I}, @samp{J}, @samp{K}, @dots{}
6700: Other letters in the range @samp{I} through @samp{M} may be defined in
6701: a machine-dependent fashion to permit immediate integer operands with
6702: explicit integer values in specified ranges. For example, on the
6703: 68000, @samp{I} is defined to stand for the range of values 1 to 8.
6704: This is the range permitted as a shift count in the shift
6705: instructions.
6706:
6707: @item @samp{F}
1.1.1.8 root 6708: An immediate floating operand (expression code @code{const_double}) is
1.1 root 6709: allowed.
6710:
6711: @item @samp{G}, @samp{H}
6712: @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
6713: permit immediate floating operands in particular ranges of values.
6714:
6715: @item @samp{s}
6716: An immediate integer operand whose value is not an explicit integer is
6717: allowed.
6718:
6719: This might appear strange; if an insn allows a constant operand with a
6720: value not known at compile time, it certainly must allow any known
6721: value. So why use @samp{s} instead of @samp{i}? Sometimes it allows
6722: better code to be generated.
6723:
6724: For example, on the 68000 in a fullword instruction it is possible to
1.1.1.9 root 6725: use an immediate operand; but if the immediate value is between -128
6726: and 127, better code results from loading the value into a register and
1.1 root 6727: using the register. This is because the load into the register can be
6728: done with a @samp{moveq} instruction. We arrange for this to happen
6729: by defining the letter @samp{K} to mean ``any integer outside the
1.1.1.9 root 6730: range -128 to 127'', and then specifying @samp{Ks} in the operand
1.1 root 6731: constraints.
6732:
6733: @item @samp{g}
6734: Any register, memory or immediate integer operand is allowed, except for
6735: registers that are not general registers.
6736:
6737: @item @samp{@var{n}} (a digit)
6738: An operand that matches operand number @var{n} is allowed.
6739: If a digit is used together with letters, the digit should come last.
6740:
6741: This is called a @dfn{matching constraint} and what it really means is
6742: that the assembler has only a single operand that fills two roles
6743: considered separate in the RTL insn. For example, an add insn has two
6744: input operands and one output operand in the RTL, but on most machines
6745: an add instruction really has only two operands, one of them an
6746: input-output operand.
6747:
6748: Matching constraints work only in circumstances like that add insn.
6749: More precisely, the matching constraint must appear in an input-only
6750: operand and the operand that it matches must be an output-only operand
1.1.1.5 root 6751: with a lower number. Thus, operand @var{n} must have @samp{=} in its
6752: constraint.
1.1 root 6753:
6754: For operands to match in a particular case usually means that they
6755: are identical-looking RTL expressions. But in a few special cases
6756: specific kinds of dissimilarity are allowed. For example, @code{*x}
6757: as an input operand will match @code{*x++} as an output operand.
6758: For proper results in such cases, the output template should always
6759: use the output-operand's number when printing the operand.
6760:
6761: @item @samp{p}
6762: An operand that is a valid memory address is allowed. This is
6763: for ``load address'' and ``push address'' instructions.
6764:
1.1.1.8 root 6765: @samp{p} in the constraint must be accompanies by @code{address_operand}
6766: as the predicate in the @code{match_operand}.
1.1 root 6767: @end table
6768:
6769: In order to have valid assembler code, each operand must satisfy
6770: its constraint. But a failure to do so does not prevent the pattern
6771: from applying to an insn. Instead, it directs the compiler to modify
6772: the code so that the constraint will be satisfied. Usually this is
6773: done by copying an operand into a register.
6774:
6775: Contrast, therefore, the two instruction patterns that follow:
6776:
6777: @example
6778: (define_insn ""
1.1.1.13 root 6779: [(set (match_operand:SI 0 "general_operand" "=r")
1.1 root 6780: (plus:SI (match_dup 0)
6781: (match_operand:SI 1 "general_operand" "r")))]
6782: ""
6783: "@dots{}")
6784: @end example
6785:
6786: @noindent
6787: which has two operands, one of which must appear in two places, and
6788:
6789: @example
6790: (define_insn ""
1.1.1.13 root 6791: [(set (match_operand:SI 0 "general_operand" "=r")
1.1 root 6792: (plus:SI (match_operand:SI 1 "general_operand" "0")
6793: (match_operand:SI 2 "general_operand" "r")))]
6794: ""
6795: "@dots{}")
6796: @end example
6797:
6798: @noindent
6799: which has three operands, two of which are required by a constraint to be
6800: identical. If we are considering an insn of the form
6801:
6802: @example
6803: (insn @var{n} @var{prev} @var{next}
6804: (set (reg:SI 3)
6805: (plus:SI (reg:SI 6) (reg:SI 109)))
6806: @dots{})
6807: @end example
6808:
6809: @noindent
6810: the first pattern would not apply at all, because this insn does not
6811: contain two identical subexpressions in the right place. The pattern would
6812: say, ``That does not look like an add instruction; try other patterns.''
6813: The second pattern would say, ``Yes, that's an add instruction, but there
6814: is something wrong with it.'' It would direct the reload pass of the
6815: compiler to generate additional insns to make the constraint true. The
6816: results might look like this:
6817:
6818: @example
6819: (insn @var{n2} @var{prev} @var{n}
6820: (set (reg:SI 3) (reg:SI 6))
6821: @dots{})
6822:
6823: (insn @var{n} @var{n2} @var{next}
6824: (set (reg:SI 3)
6825: (plus:SI (reg:SI 3) (reg:SI 109)))
6826: @dots{})
6827: @end example
6828:
6829: It is up to you to make sure that each operand, in each pattern, has
6830: constraints that can handle any RTL expression that could be present for
6831: that operand. (When multiple alternatives are in use, each pattern must,
6832: for each possible combination of operand expressions, have at least one
6833: alternative which can handle that combination of operands.) The
6834: constraints don't need to @emph{allow} any possible operand---when this is
6835: the case, they do not constrain---but they must at least point the way to
6836: reloading any possible operand so that it will fit.
6837:
6838: @itemize @bullet
6839: @item
6840: If the constraint accepts whatever operands the predicate permits,
6841: there is no problem: reloading is never necessary for this operand.
6842:
6843: For example, an operand whose constraints permit everything except
6844: registers is safe provided its predicate rejects registers.
6845:
6846: An operand whose predicate accepts only constant values is safe
6847: provided its constraints include the letter @samp{i}. If any possible
6848: constant value is accepted, then nothing less than @samp{i} will do;
1.1.1.5 root 6849: if the predicate is more selective, then the constraints may also be
1.1 root 6850: more selective.
6851:
6852: @item
6853: Any operand expression can be reloaded by copying it into a register.
6854: So if an operand's constraints allow some kind of register, it is
6855: certain to be safe. It need not permit all classes of registers; the
6856: compiler knows how to copy a register into another register of the
6857: proper class in order to make an instruction valid.
6858:
6859: @item
1.1.1.8 root 6860: A nonoffsettable memory reference can be reloaded by copying the
1.1 root 6861: address into a register. So if the constraint uses the letter
6862: @samp{o}, all memory references are taken care of.
6863:
6864: @item
1.1.1.8 root 6865: A constant operand can be reloaded by allocating space in memory to
6866: hold it as preinitialized data. Then the memory reference can be used
6867: in place of the constant. So if the constraint uses the letters
6868: @samp{o} or @samp{m}, constant operands are not a problem.
1.1 root 6869: @end itemize
6870:
6871: If the operand's predicate can recognize registers, but the constraint does
6872: not permit them, it can make the compiler crash. When this operand happens
6873: to be a register, the reload pass will be stymied, because it does not know
6874: how to copy a register temporarily into memory.
6875:
6876: @node Multi-Alternative, Class Preferences, Simple Constraints, Constraints
6877: @subsection Multiple Alternative Constraints
6878:
6879: Sometimes a single instruction has multiple alternative sets of possible
6880: operands. For example, on the 68000, a logical-or instruction can combine
6881: register or an immediate value into memory, or it can combine any kind of
6882: operand into a register; but it cannot combine one memory location into
6883: another.
6884:
6885: These constraints are represented as multiple alternatives. An alternative
6886: can be described by a series of letters for each operand. The overall
6887: constraint for an operand is made from the letters for this operand
6888: from the first alternative, a comma, the letters for this operand from
6889: the second alternative, a comma, and so on until the last alternative.
6890: Here is how it is done for fullword logical-or on the 68000:
6891:
6892: @example
6893: (define_insn "iorsi3"
1.1.1.9 root 6894: [(set (match_operand:SI 0 "general_operand" "=m,d")
6895: (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
1.1 root 6896: (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
6897: @dots{})
6898: @end example
6899:
6900: The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
1.1.1.9 root 6901: operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
6902: 2. The second alternative has @samp{d} (data register) for operand 0,
6903: @samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and
6904: @samp{%} in the constraints apply to all the alternatives; their meaning
1.1 root 6905: is explained in the next section.
6906:
6907: If all the operands fit any one alternative, the instruction is valid.
6908: Otherwise, for each alternative, the compiler counts how many instructions
6909: must be added to copy the operands so that that alternative applies.
6910: The alternative requiring the least copying is chosen. If two alternatives
6911: need the same amount of copying, the one that comes first is chosen.
6912: These choices can be altered with the @samp{?} and @samp{!} characters:
6913:
6914: @table @samp
6915: @item ?
6916: Disparage slightly the alternative that the @samp{?} appears in,
6917: as a choice when no alternative applies exactly. The compiler regards
6918: this alternative as one unit more costly for each @samp{?} that appears
6919: in it.
6920:
6921: @item !
6922: Disparage severely the alternative that the @samp{!} appears in.
6923: When operands must be copied into registers, the compiler will
6924: never choose this alternative as the one to strive for.
6925: @end table
6926:
1.1.1.5 root 6927: When an insn pattern has multiple alternatives in its constraints, often
6928: the appearance of the assembler code is determined mostly by which
1.1 root 6929: alternative was matched. When this is so, the C code for writing the
6930: assembler code can use the variable @code{which_alternative}, which is
1.1.1.5 root 6931: the ordinal number of the alternative that was actually satisfied (0 for
6932: the first, 1 for the second alternative, etc.). For example:
1.1 root 6933:
6934: @example
6935: (define_insn ""
1.1.1.13 root 6936: [(set (match_operand:SI 0 "general_operand" "=r,m")
1.1 root 6937: (const_int 0))]
6938: ""
6939: "*
6940: return (which_alternative == 0
6941: ? \"clrreg %0\" : \"clrmem %0\");
6942: ")
6943: @end example
6944:
6945: @node Class Preferences, Modifiers, Multi-Alternative, Constraints
6946: @subsection Register Class Preferences
6947:
6948: The operand constraints have another function: they enable the compiler
6949: to decide which kind of hardware register a pseudo register is best
6950: allocated to. The compiler examines the constraints that apply to the
6951: insns that use the pseudo register, looking for the machine-dependent
6952: letters such as @samp{d} and @samp{a} that specify classes of registers.
6953: The pseudo register is put in whichever class gets the most ``votes''.
6954: The constraint letters @samp{g} and @samp{r} also vote: they vote in
6955: favor of a general register. The machine description says which registers
6956: are considered general.
6957:
6958: Of course, on some machines all registers are equivalent, and no register
6959: classes are defined. Then none of this complexity is relevant.
6960:
6961: @node Modifiers, No Constraints, Class Preferences, Constraints
6962: @subsection Constraint Modifier Characters
6963:
6964: @table @samp
6965: @item =
6966: Means that this operand is write-only for this instruction: the previous
6967: value is discarded and replaced by output data.
6968:
6969: @item +
6970: Means that this operand is both read and written by the instruction.
6971:
6972: When the compiler fixes up the operands to satisfy the constraints,
6973: it needs to know which operands are inputs to the instruction and
6974: which are outputs from it. @samp{=} identifies an output; @samp{+}
6975: identifies an operand that is both input and output; all other operands
6976: are assumed to be input only.
6977:
6978: @item &
6979: Means (in a particular alternative) that this operand is written
6980: before the instruction is finished using the input operands.
6981: Therefore, this operand may not lie in a register that is used as an
6982: input operand or as part of any memory address.
6983:
6984: @samp{&} applies only to the alternative in which it is written. In
6985: constraints with multiple alternatives, sometimes one alternative
6986: requires @samp{&} while others do not. See, for example, the
6987: @samp{movdf} insn of the 68000.
6988:
6989: @samp{&} does not obviate the need to write @samp{=}.
6990:
6991: @item %
6992: Declares the instruction to be commutative for this operand and the
6993: following operand. This means that the compiler may interchange the
6994: two operands if that is the cheapest way to make all operands fit the
6995: constraints. This is often used in patterns for addition instructions
6996: that really have only two operands: the result must go in one of the
6997: arguments. Here for example, is how the 68000 halfword-add
6998: instruction is defined:
6999:
7000: @example
7001: (define_insn "addhi3"
7002: [(set (match_operand:HI 0 "general_operand" "=m,r")
7003: (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
7004: (match_operand:HI 2 "general_operand" "di,g")))]
7005: @dots{})
7006: @end example
7007:
7008: Note that in previous versions of GNU CC the @samp{%} constraint
7009: modifier always applied to operands 1 and 2 regardless of which
7010: operand it was written in. The usual custom was to write it in
7011: operand 0. Now it must be in operand 1 if the operands to be
7012: exchanged are 1 and 2.
7013:
7014: @item #
7015: Says that all following characters, up to the next comma, are to be
7016: ignored as a constraint. They are significant only for choosing
7017: register preferences.
7018:
7019: @item *
7020: Says that the following character should be ignored when choosing
7021: register preferences. @samp{*} has no effect on the meaning of the
7022: constraint as a constraint.
7023:
7024: Here is an example: the 68000 has an instruction to sign-extend a
7025: halfword in a data register, and can also sign-extend a value by
7026: copying it into an address register. While either kind of register is
7027: acceptable, the constraints on an address-register destination are
7028: less strict, so it is best if register allocation makes an address
7029: register its goal. Therefore, @samp{*} is used so that the @samp{d}
7030: constraint letter (for data register) is ignored when computing
7031: register preferences.
7032:
7033: @example
7034: (define_insn "extendhisi2"
7035: [(set (match_operand:SI 0 "general_operand" "=*d,a")
7036: (sign_extend:SI
7037: (match_operand:HI 1 "general_operand" "0,g")))]
7038: @dots{})
7039: @end example
7040: @end table
7041:
7042: @node No Constraints,, Modifiers, Constraints
7043: @subsection Not Using Constraints
7044:
7045: Some machines are so clean that operand constraints are not required. For
7046: example, on the Vax, an operand valid in one context is valid in any other
7047: context. On such a machine, every operand constraint would be @samp{g},
7048: excepting only operands of ``load address'' instructions which are
7049: written as if they referred to a memory location's contents but actual
7050: refer to its address. They would have constraint @samp{p}.
7051:
7052: For such machines, instead of writing @samp{g} and @samp{p} for all
7053: the constraints, you can choose to write a description with empty constraints.
1.1.1.8 root 7054: Then you write @samp{""} for the constraint in every @code{match_operand}.
7055: Address operands are identified by writing an @code{address} expression
7056: around the @code{match_operand}, not by their constraints.
1.1 root 7057:
7058: When the machine description has just empty constraints, certain parts
1.1.1.6 root 7059: of compilation are skipped, making the compiler faster. However,
7060: few machines actually do not need constraints; all machine descriptions
7061: now in existence use constraints.
1.1 root 7062:
7063: @node Standard Names, Pattern Ordering, Constraints, Machine Desc
7064: @section Standard Names for Patterns Used in Generation
7065:
7066: Here is a table of the instruction names that are meaningful in the RTL
7067: generation pass of the compiler. Giving one of these names to an
7068: instruction pattern tells the RTL generation pass that it can use the
7069: pattern in to accomplish a certain task.
7070:
7071: @table @asis
7072: @item @samp{mov@var{m}}
1.1.1.8 root 7073: Here @var{m} stands for a two-letter machine mode name, in lower case.
7074: This instruction pattern moves data with that machine mode from operand
7075: 1 to operand 0. For example, @samp{movsi} moves full-word data.
1.1 root 7076:
1.1.1.8 root 7077: If operand 0 is a @code{subreg} with mode @var{m} of a register whose
7078: own mode is wider than @var{m}, the effect of this instruction is
1.1 root 7079: to store the specified value in the part of the register that corresponds
7080: to mode @var{m}. The effect on the rest of the register is undefined.
7081:
7082: This class of patterns is special in several ways. First of all, each
7083: of these names @emph{must} be defined, because there is no other way
7084: to copy a datum from one place to another.
7085:
7086: Second, these patterns are not used solely in the RTL generation pass.
7087: Even the reload pass can generate move insns to copy values from stack
1.1.1.8 root 7088: slots into temporary registers. When it does so, one of the operands is
7089: a hard register and the other is an operand that can need to be reloaded
7090: into a register.
7091:
7092: Therefore, when given such a pair of operands, the pattern must generate
7093: RTL which needs no reloading and needs no temporary registers---no
7094: registers other than the operands. For example, if you support the
7095: pattern with a @code{define_expand}, then in such a case the
7096: @code{define_expand} mustn't call @code{force_reg} or any other such
7097: function which might generate new pseudo registers.
1.1 root 7098:
7099: This requirement exists even for subword modes on a RISC machine where
7100: fetching those modes from memory normally requires several insns and
7101: some temporary registers. Look in @file{spur.md} to see how the
1.1.1.8 root 7102: requirement can be satisfied.
1.1 root 7103:
7104: The variety of operands that have reloads depends on the rest of the
7105: machine description, but typically on a RISC machine these can only be
7106: pseudo registers that did not get hard registers, while on other
7107: machines explicit memory references will get optional reloads.
7108:
1.1.1.9 root 7109: The constraints on a @samp{move@var{m}} must allow any hard register to
7110: be moved to any other hard register (provided that
7111: @code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers).
7112:
7113: It is obligatory to support floating point @samp{move@var{m}}
7114: instructions into and out of any registers that can hold fixed point
7115: values, because unions and structures (which have modes @code{SImode} or
7116: @code{DImode}) can be in those registers and they may have floating
7117: point members.
7118:
7119: There may also be a need to support fixed point @samp{move@var{m}}
7120: instructions in and out of floating point registers. Unfortunately, I
7121: have forgotten why this was so, and I don't know whether it is still
7122: true. If @code{HARD_REGNO_MODE_OK} rejects fixed point values in
7123: floating point registers, then the constraints of the fixed point
7124: @samp{move@var{m}} instructions must be designed to avoid ever trying to
7125: reload into a floating point register.
1.1 root 7126:
7127: @item @samp{movstrict@var{m}}
1.1.1.8 root 7128: Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
1.1 root 7129: with mode @var{m} of a register whose natural mode is wider,
7130: the @samp{movstrict@var{m}} instruction is guaranteed not to alter
7131: any of the register except the part which belongs to mode @var{m}.
7132:
1.1.1.13 root 7133: @item @samp{movsi_unaligned}
7134: Like @samp{movsi} except that the memory reference will not trap
7135: if loading or storing into unaligned memory. You must define this
7136: pattern if you can pass structures or unions in registers when they
7137: have less than a full word of alignment.
7138:
1.1 root 7139: @item @samp{add@var{m}3}
7140: Add operand 2 and operand 1, storing the result in operand 0. All operands
7141: must have mode @var{m}. This can be used even on two-address machines, by
7142: means of constraints requiring operands 1 and 0 to be the same location.
7143:
7144: @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}
7145: Similar, for other arithmetic operations.
7146:
7147: There are special considerations for register classes for logical-and
7148: instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}.
7149: They apply not only to the patterns with these standard names, but to
7150: any patterns that will match such an instruction. @xref{Register
7151: Classes}.
7152:
7153: @item @samp{mulhisi3}
7154: Multiply operands 1 and 2, which have mode @code{HImode}, and store
7155: a @code{SImode} product in operand 0.
7156:
7157: @item @samp{mulqihi3}, @samp{mulsidi3}
7158: Similar widening-multiplication instructions of other widths.
7159:
7160: @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
7161: Similar widening-multiplication instructions that do unsigned
7162: multiplication.
7163:
7164: @item @samp{divmod@var{m}4}
7165: Signed division that produces both a quotient and a remainder.
7166: Operand 1 is divided by operand 2 to produce a quotient stored
7167: in operand 0 and a remainder stored in operand 3.
7168:
7169: @item @samp{udivmod@var{m}4}
7170: Similar, but does unsigned division.
7171:
7172: @item @samp{ashl@var{m}3}
7173: Arithmetic-shift operand 1 left by a number of bits specified by
7174: operand 2, and store the result in operand 0. Operand 2 has
7175: mode @code{SImode}, not mode @var{m}.
7176:
7177: @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}
7178: Other shift and rotate instructions.
7179:
7180: Logical and arithmetic left shift are the same. Machines that do not
7181: allow negative shift counts often have only one instruction for
7182: shifting left. On such machines, you should define a pattern named
7183: @samp{ashl@var{m}3} and leave @samp{lshl@var{m}3} undefined.
7184:
7185: There are special considerations for register classes for shift
7186: instructions, affecting also the macro @code{PREFERRED_RELOAD_CLASS}.
7187: They apply not only to the patterns with these standard names, but to
7188: any patterns that will match such an instruction. @xref{Register
7189: Classes}.
7190:
7191: @item @samp{neg@var{m}2}
7192: Negate operand 1 and store the result in operand 0.
7193:
7194: @item @samp{abs@var{m}2}
7195: Store the absolute value of operand 1 into operand 0.
7196:
7197: @item @samp{sqrt@var{m}2}
7198: Store the square root of operand 1 into operand 0.
7199:
7200: @item @samp{ffs@var{m}2}
7201: Store into operand 0 one plus the index of the least significant 1-bit
7202: of operand 1. If operand 1 is zero, store zero. @var{m} is the mode
7203: of operand 0; operand 1's mode is specified by the instruction
7204: pattern, and the compiler will convert the operand to that mode before
7205: generating the instruction.
7206:
7207: @item @samp{one_cmpl@var{m}2}
7208: Store the bitwise-complement of operand 1 into operand 0.
7209:
7210: @item @samp{cmp@var{m}}
7211: Compare operand 0 and operand 1, and set the condition codes.
7212: The RTL pattern should look like this:
7213:
7214: @example
1.1.1.6 root 7215: (set (cc0) (compare (match_operand:@var{m} 0 @dots{})
7216: (match_operand:@var{m} 1 @dots{})))
1.1 root 7217: @end example
7218:
7219: Each such definition in the machine description, for integer mode
7220: @var{m}, must have a corresponding @samp{tst@var{m}} pattern, because
7221: optimization can simplify the compare into a test when operand 1 is
7222: zero.
7223:
7224: @item @samp{tst@var{m}}
7225: Compare operand 0 against zero, and set the condition codes.
7226: The RTL pattern should look like this:
7227:
7228: @example
7229: (set (cc0) (match_operand:@var{m} 0 @dots{}))
7230: @end example
7231:
7232: @item @samp{movstr@var{m}}
7233: Block move instruction. The addresses of the destination and source
7234: strings are the first two operands, and both are in mode @code{Pmode}.
7235: The number of bytes to move is the third operand, in mode @var{m}.
1.1.1.5 root 7236: The fourth operand is the known shared alignment of the source and
7237: destination, in the form of a @code{const_int} rtx.
1.1 root 7238:
7239: @item @samp{cmpstr@var{m}}
7240: Block compare instruction, with operands like @samp{movstr@var{m}}
7241: except that the two memory blocks are compared byte by byte
7242: in lexicographic order. The effect of the instruction is to set
7243: the condition codes.
7244:
7245: @item @samp{float@var{m}@var{n}2}
1.1.1.9 root 7246: Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
7247: floating point mode @var{n} and store in operand 0 (which has mode
7248: @var{n}).
7249:
7250: @item @samp{floatuns@var{m}@var{n}2}
7251: Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
7252: to floating point mode @var{n} and store in operand 0 (which has mode
7253: @var{n}).
1.1 root 7254:
7255: @item @samp{fix@var{m}@var{n}2}
7256: Convert operand 1 (valid for floating point mode @var{m}) to fixed
7257: point mode @var{n} as a signed number and store in operand 0 (which
7258: has mode @var{n}). This instruction's result is defined only when
7259: the value of operand 1 is an integer.
7260:
7261: @item @samp{fixuns@var{m}@var{n}2}
7262: Convert operand 1 (valid for floating point mode @var{m}) to fixed
7263: point mode @var{n} as an unsigned number and store in operand 0 (which
7264: has mode @var{n}). This instruction's result is defined only when the
7265: value of operand 1 is an integer.
7266:
7267: @item @samp{ftrunc@var{m}2}
7268: Convert operand 1 (valid for floating point mode @var{m}) to an
7269: integer value, still represented in floating point mode @var{m}, and
7270: store it in operand 0 (valid for floating point mode @var{m}).
7271:
7272: @item @samp{fix_trunc@var{m}@var{n}2}
7273: Like @samp{fix@var{m}@var{n}2} but works for any floating point value
7274: of mode @var{m} by converting the value to an integer.
7275:
7276: @item @samp{fixuns_trunc@var{m}@var{n}2}
7277: Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
7278: value of mode @var{m} by converting the value to an integer.
7279:
7280: @item @samp{trunc@var{m}@var{n}}
7281: Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
7282: store in operand 0 (which has mode @var{n}). Both modes must be fixed
7283: point or both floating point.
7284:
7285: @item @samp{extend@var{m}@var{n}}
7286: Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
7287: store in operand 0 (which has mode @var{n}). Both modes must be fixed
7288: point or both floating point.
7289:
7290: @item @samp{zero_extend@var{m}@var{n}}
7291: Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
7292: store in operand 0 (which has mode @var{n}). Both modes must be fixed
7293: point.
7294:
7295: @item @samp{extv}
7296: Extract a bit-field from operand 1 (a register or memory operand),
7297: where operand 2 specifies the width in bits and operand 3 the starting
1.1.1.10 root 7298: bit, and store it in operand 0. Operand 0 must have @code{SImode}.
1.1 root 7299: Operand 1 may have mode @code{QImode} or @code{SImode}; often
7300: @code{SImode} is allowed only for registers. Operands 2 and 3 must be
7301: valid for @code{SImode}.
7302:
7303: The RTL generation pass generates this instruction only with constants
7304: for operands 2 and 3.
7305:
7306: The bit-field value is sign-extended to a full word integer
7307: before it is stored in operand 0.
7308:
7309: @item @samp{extzv}
7310: Like @samp{extv} except that the bit-field value is zero-extended.
7311:
7312: @item @samp{insv}
7313: Store operand 3 (which must be valid for @code{SImode}) into a
7314: bit-field in operand 0, where operand 1 specifies the width in bits
7315: and operand 2 the starting bit. Operand 0 may have mode @code{QImode}
7316: or @code{SImode}; often @code{SImode} is allowed only for registers.
7317: Operands 1 and 2 must be valid for @code{SImode}.
7318:
7319: The RTL generation pass generates this instruction only with constants
7320: for operands 1 and 2.
7321:
7322: @item @samp{s@var{cond}}
7323: Store zero or nonzero in the operand according to the condition codes.
7324: Value stored is nonzero iff the condition @var{cond} is true.
7325: @var{cond} is the name of a comparison operation expression code, such
1.1.1.8 root 7326: as @code{eq}, @code{lt} or @code{leu}.
1.1 root 7327:
7328: You specify the mode that the operand must have when you write the
7329: @code{match_operand} expression. The compiler automatically sees
7330: which mode you have used and supplies an operand of that mode.
7331:
1.1.1.8 root 7332: The value stored for a true condition must have 1 as its low bit, or
7333: else must be negative. Otherwise the instruction is not suitable and
7334: must be omitted from the machine description. You must tell the
7335: compiler exactly which value is stored by defining the macro
7336: @code{STORE_FLAG_VALUE}.
1.1 root 7337:
7338: @item @samp{b@var{cond}}
1.1.1.8 root 7339: Conditional branch instruction. Operand 0 is a @code{label_ref}
1.1 root 7340: that refers to the label to jump to. Jump if the condition codes
7341: meet condition @var{cond}.
7342:
7343: @item @samp{call}
7344: Subroutine call instruction returning no value. Operand 0 is the
7345: function to call; operand 1 is the number of bytes of arguments pushed
1.1.1.8 root 7346: (in mode @code{SImode}, except it is normally a @code{const_int});
1.1 root 7347: operand 2 is the number of registers used as operands.
7348:
7349: On most machines, operand 2 is not actually stored into the RTL
7350: pattern. It is supplied for the sake of some RISC machines which need
7351: to put this information into the assembler code; they can put it in
7352: the RTL instead of operand 1.
7353:
1.1.1.8 root 7354: Operand 0 should be a @code{mem} RTX whose address is the address of
1.1 root 7355: the function.
7356:
7357: @item @samp{call_value}
7358: Subroutine call instruction returning a value. Operand 0 is the hard
7359: register in which the value is returned. There are three more
7360: operands, the same as the three operands of the @samp{call}
7361: instruction (but with numbers increased by one).
7362:
7363: Subroutines that return @code{BLKmode} objects use the @samp{call}
7364: insn.
7365:
7366: @item @samp{return}
7367: Subroutine return instruction. This instruction pattern name should be
7368: defined only if a single instruction can do all the work of returning
7369: from a function.
7370:
1.1.1.8 root 7371: @item @samp{nop}
7372: No-op instruction. This instruction pattern name should always be defined
7373: to output a no-op in assembler code. @code{(const_int 0)} will do as an
7374: RTL pattern.
7375:
1.1 root 7376: @item @samp{casesi}
7377: Instruction to jump through a dispatch table, including bounds checking.
7378: This instruction takes five operands:
7379:
7380: @enumerate
7381: @item
7382: The index to dispatch on, which has mode @code{SImode}.
7383:
7384: @item
7385: The lower bound for indices in the table, an integer constant.
7386:
7387: @item
1.1.1.6 root 7388: The total range of indices in the table---the largest index
7389: minus the smallest one (both inclusive).
1.1 root 7390:
7391: @item
7392: A label to jump to if the index has a value outside the bounds.
7393: (If the machine-description macro @code{CASE_DROPS_THROUGH} is defined,
7394: then an out-of-bounds index drops through to the code following
7395: the jump table instead of jumping to this label. In that case,
7396: this label is not actually used by the @samp{casesi} instruction,
7397: but it is always provided as an operand.)
7398:
7399: @item
7400: A label that precedes the table itself.
7401: @end enumerate
7402:
1.1.1.8 root 7403: The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a
7404: @code{jump_insn}. The number of elements in the table is one plus the
1.1 root 7405: difference between the upper bound and the lower bound.
7406:
7407: @item @samp{tablejump}
7408: Instruction to jump to a variable address. This is a low-level
7409: capability which can be used to implement a dispatch table when there
7410: is no @samp{casesi} pattern.
7411:
7412: This pattern requires two operands: the address or offset, and a label
7413: which should immediately precede the jump table. If the macro
7414: @code{CASE_VECTOR_PC_RELATIVE} is defined then the first operand is an
1.1.1.10 root 7415: offset that counts from the address of the table; otherwise, it is an
7416: absolute address to jump to.
1.1 root 7417:
7418: The @samp{tablejump} insn is always the last insn before the jump
7419: table it uses. Its assembler code normally has no need to use the
7420: second operand, but you should incorporate it in the RTL pattern so
7421: that the jump optimizer will not delete the table as unreachable code.
7422: @end table
7423:
7424: @node Pattern Ordering, Dependent Patterns, Standard Names, Machine Desc
7425: @section When the Order of Patterns Matters
7426:
7427: Sometimes an insn can match more than one instruction pattern. Then the
7428: pattern that appears first in the machine description is the one used.
7429: Therefore, more specific patterns (patterns that will match fewer things)
7430: and faster instructions (those that will produce better code when they
7431: do match) should usually go first in the description.
7432:
7433: In some cases the effect of ordering the patterns can be used to hide
7434: a pattern when it is not valid. For example, the 68000 has an
7435: instruction for converting a fullword to floating point and another
7436: for converting a byte to floating point. An instruction converting
7437: an integer to floating point could match either one. We put the
7438: pattern to convert the fullword first to make sure that one will
7439: be used rather than the other. (Otherwise a large integer might
7440: be generated as a single-byte immediate quantity, which would not work.)
7441: Instead of using this pattern ordering it would be possible to make the
7442: pattern for convert-a-byte smart enough to deal properly with any
7443: constant value.
7444:
7445: @node Dependent Patterns, Jump Patterns, Pattern Ordering, Machine Desc
7446: @section Interdependence of Patterns
7447:
7448: Every machine description must have a named pattern for each of the
7449: conditional branch names @samp{b@var{cond}}. The recognition template
7450: must always have the form
7451:
7452: @example
7453: (set (pc)
7454: (if_then_else (@var{cond} (cc0) (const_int 0))
7455: (label_ref (match_operand 0 "" ""))
7456: (pc)))
7457: @end example
7458:
7459: @noindent
7460: In addition, every machine description must have an anonymous pattern
7461: for each of the possible reverse-conditional branches. These patterns
7462: look like
7463:
7464: @example
7465: (set (pc)
7466: (if_then_else (@var{cond} (cc0) (const_int 0))
7467: (pc)
7468: (label_ref (match_operand 0 "" ""))))
7469: @end example
7470:
7471: @noindent
7472: They are necessary because jump optimization can turn direct-conditional
7473: branches into reverse-conditional branches.
7474:
7475: The compiler does more with RTL than just create it from patterns
7476: and recognize the patterns: it can perform arithmetic expression codes
7477: when constant values for their operands can be determined. As a result,
7478: sometimes having one pattern can require other patterns. For example, the
7479: Vax has no `and' instruction, but it has `and not' instructions. Here
7480: is the definition of one of them:
7481:
7482: @example
7483: (define_insn "andcbsi2"
7484: [(set (match_operand:SI 0 "general_operand" "")
7485: (and:SI (match_dup 0)
7486: (not:SI (match_operand:SI
7487: 1 "general_operand" ""))))]
7488: ""
7489: "bicl2 %1,%0")
7490: @end example
7491:
7492: @noindent
7493: If operand 1 is an explicit integer constant, an instruction constructed
7494: using that pattern can be simplified into an `and' like this:
7495:
7496: @example
7497: (set (reg:SI 41)
7498: (and:SI (reg:SI 41)
7499: (const_int 0xffff7fff)))
7500: @end example
7501:
7502: @noindent
7503: (where the integer constant is the one's complement of what
7504: appeared in the original instruction).
7505:
7506: To avoid a fatal error, the compiler must have a pattern that recognizes
7507: such an instruction. Here is what is used:
7508:
7509: @example
7510: (define_insn ""
7511: [(set (match_operand:SI 0 "general_operand" "")
7512: (and:SI (match_dup 0)
7513: (match_operand:SI 1 "general_operand" "")))]
7514: "GET_CODE (operands[1]) == CONST_INT"
7515: "*
7516: @{ operands[1]
7517: = gen_rtx (CONST_INT, VOIDmode, ~INTVAL (operands[1]));
7518: return \"bicl2 %1,%0\";
7519: @}")
7520: @end example
7521:
7522: @noindent
7523: Whereas a pattern to match a general `and' instruction is impossible to
7524: support on the Vax, this pattern is possible because it matches only a
7525: constant second argument: a special case that can be output as an `and not'
7526: instruction.
7527:
7528: A ``compare'' instruction whose RTL looks like this:
7529:
7530: @example
1.1.1.6 root 7531: (set (cc0) (compare @var{operand} (const_int 0)))
1.1 root 7532: @end example
7533:
7534: @noindent
7535: may be simplified by optimization into a ``test'' like this:
7536:
7537: @example
7538: (set (cc0) @var{operand})
7539: @end example
7540:
7541: @noindent
7542: So in the machine description, each ``compare'' pattern for an integer
7543: mode must have a corresponding ``test'' pattern that will match the
7544: result of such simplification.
7545:
7546: In some cases machines support instructions identical except for the
7547: machine mode of one or more operands. For example, there may be
7548: ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
7549: patterns are
7550:
7551: @example
7552: (set (match_operand:SI 0 @dots{})
7553: (extend:SI (match_operand:HI 1 @dots{})))
7554:
7555: (set (match_operand:SI 0 @dots{})
7556: (extend:SI (match_operand:QI 1 @dots{})))
7557: @end example
7558:
7559: @noindent
7560: Constant integers do not specify a machine mode, so an instruction to
7561: extend a constant value could match either pattern. The pattern it
7562: actually will match is the one that appears first in the file. For correct
7563: results, this must be the one for the widest possible mode (@code{HImode},
7564: here). If the pattern matches the @code{QImode} instruction, the results
7565: will be incorrect if the constant value does not actually fit that mode.
7566:
7567: Such instructions to extend constants are rarely generated because they are
7568: optimized away, but they do occasionally happen in nonoptimized
7569: compilations.
7570:
7571: When an instruction has the constraint letter @samp{o}, the reload
1.1.1.8 root 7572: pass may generate instructions which copy a nonoffsettable address into
1.1 root 7573: an index register. The idea is that the register can be used as a
1.1.1.8 root 7574: replacement offsettable address. In order for these generated
1.1 root 7575: instructions to work, there must be patterns to copy any kind of valid
7576: address into a register.
7577:
7578: Most older machine designs have ``load address'' instructions which do
7579: just what is needed here. Some RISC machines do not advertise such
7580: instructions, but the possible addresses on these machines are very
7581: limited, so it is easy to fake them.
7582:
7583: Auto-increment and auto-decrement addresses are an exception; there
7584: need not be an instruction that can copy such an address into a
7585: register, because reload handles these cases in a different manner.
7586:
7587: @node Jump Patterns, Peephole Definitions, Dependent Patterns, Machine Desc
7588: @section Defining Jump Instruction Patterns
7589:
7590: GNU CC assumes that the machine has a condition code. A comparison insn
7591: sets the condition code, recording the results of both signed and unsigned
7592: comparison of the given operands. A separate branch insn tests the
7593: condition code and branches or not according its value. The branch insns
7594: come in distinct signed and unsigned flavors. Many common machines, such
7595: as the Vax, the 68000 and the 32000, work this way.
7596:
7597: Some machines have distinct signed and unsigned compare instructions, and
7598: only one set of conditional branch instructions. The easiest way to handle
7599: these machines is to treat them just like the others until the final stage
7600: where assembly code is written. At this time, when outputting code for the
7601: compare instruction, peek ahead at the following branch using
7602: @code{NEXT_INSN (insn)}. (The variable @code{insn} refers to the insn
7603: being output, in the output-writing code in an instruction pattern.) If
7604: the RTL says that is an unsigned branch, output an unsigned compare;
7605: otherwise output a signed compare. When the branch itself is output, you
7606: can treat signed and unsigned branches identically.
7607:
7608: The reason you can do this is that GNU CC always generates a pair of
7609: consecutive RTL insns, one to set the condition code and one to test it,
7610: and keeps the pair inviolate until the end.
7611:
7612: To go with this technique, you must define the machine-description macro
7613: @code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no
7614: compare instruction is superfluous.
7615:
7616: Some machines have compare-and-branch instructions and no condition code.
7617: A similar technique works for them. When it is time to ``output'' a
7618: compare instruction, record its operands in two static variables. When
7619: outputting the branch-on-condition-code instruction that follows, actually
7620: output a compare-and-branch instruction that uses the remembered operands.
7621:
7622: It also works to define patterns for compare-and-branch instructions.
7623: In optimizing compilation, the pair of compare and branch instructions
1.1.1.5 root 7624: will be combined according to these patterns. But this does not happen
1.1 root 7625: if optimization is not requested. So you must use one of the solutions
7626: above in addition to any special patterns you define.
7627:
7628: @node Peephole Definitions, Expander Definitions, Jump Patterns, Machine Desc
7629: @section Defining Machine-Specific Peephole Optimizers
7630:
7631: In addition to instruction patterns the @file{md} file may contain
7632: definitions of machine-specific peephole optimizations.
7633:
7634: The combiner does not notice certain peephole optimizations when the data
7635: flow in the program does not suggest that it should try them. For example,
7636: sometimes two consecutive insns related in purpose can be combined even
7637: though the second one does not appear to use a register computed in the
7638: first one. A machine-specific peephole optimizer can detect such
7639: opportunities.
7640:
7641: A definition looks like this:
7642:
7643: @example
7644: (define_peephole
7645: [@var{insn-pattern-1}
7646: @var{insn-pattern-2}
7647: @dots{}]
7648: "@var{condition}"
7649: "@var{template}"
7650: "@var{machine-specific info}")
7651: @end example
7652:
7653: @noindent
7654: The last string operand may be omitted if you are not using any
7655: machine-specific information in this machine description. If present,
1.1.1.8 root 7656: it must obey the same rules as in a @code{define_insn}.
1.1 root 7657:
7658: In this skeleton, @var{insn-pattern-1} and so on are patterns to match
1.1.1.5 root 7659: consecutive insns. The optimization applies to a sequence of insns when
7660: @var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
7661: the next, and so on.@refill
1.1 root 7662:
1.1.1.8 root 7663: Each of the insns matched by a peephole must also match a
7664: @code{define_insn}. Peepholes are checked only at the last stage just
7665: before code generation, and only optionally. Therefore, any insn which
7666: would match a peephole but no @code{define_insn} will cause a crash in code
7667: generation in an unoptimized compilation, or at various optimization
7668: stages.
1.1 root 7669:
1.1.1.5 root 7670: The operands of the insns are matched with @code{match_operands} and
7671: @code{match_dup}, as usual. What is not usual is that the operand numbers
7672: apply to all the insn patterns in the definition. So, you can check for
7673: identical operands in two insns by using @code{match_operand} in one insn
7674: and @code{match_dup} in the other.
1.1 root 7675:
7676: The operand constraints used in @code{match_operand} patterns do not have
1.1.1.8 root 7677: any direct effect on the applicability of the peephole, but they will
7678: be validated afterward, so make sure your constraints are general enough
7679: to apply whenever the peephole matches. If the peephole matches
7680: but the constraints are not satisfied, the compiler will crash.
7681:
7682: It is safe to omit constraints in all the operands of the peephole; or
7683: you can write constraints which serve as a double-check on the criteria
7684: previously tested.
1.1 root 7685:
1.1.1.5 root 7686: Once a sequence of insns matches the patterns, the @var{condition} is
7687: checked. This is a C expression which makes the final decision whether to
7688: perform the optimization (we do so if the expression is nonzero). If
1.1 root 7689: @var{condition} is omitted (in other words, the string is empty) then the
1.1.1.5 root 7690: optimization is applied to every sequence of insns that matches the
1.1 root 7691: patterns.
7692:
1.1.1.5 root 7693: The defined peephole optimizations are applied after register allocation
7694: is complete. Therefore, the peephole definition can check which
7695: operands have ended up in which kinds of registers, just by looking at
7696: the operands.
1.1 root 7697:
7698: The way to refer to the operands in @var{condition} is to write
7699: @code{operands[@var{i}]} for operand number @var{i} (as matched by
7700: @code{(match_operand @var{i} @dots{})}). Use the variable @code{insn} to
7701: refer to the last of the insns being matched; use @code{PREV_INSN} to find
1.1.1.8 root 7702: the preceding insns (but be careful to skip over any @code{note} insns that
1.1 root 7703: intervene).@refill
7704:
7705: When optimizing computations with intermediate results, you can use
7706: @var{condition} to match only when the intermediate results are not used
7707: elsewhere. Use the C expression @code{dead_or_set_p (@var{insn},
7708: @var{op})}, where @var{insn} is the insn in which you expect the value to
7709: be used for the last time (from the value of @code{insn}, together with use
7710: of @code{PREV_INSN}), and @var{op} is the intermediate value (from
7711: @code{operands[@var{i}]}).@refill
7712:
1.1.1.5 root 7713: Applying the optimization means replacing the sequence of insns with one
7714: new insn. The @var{template} controls ultimate output of assembler code
7715: for this combined insn. It works exactly like the template of a
7716: @code{define_insn}. Operand numbers in this template are the same ones
7717: used in matching the original sequence of insns.
1.1 root 7718:
7719: The result of a defined peephole optimizer does not need to match any of
1.1.1.5 root 7720: the insn patterns in the machine description; it does not even have an
7721: opportunity to match them. The peephole optimizer definition itself serves
7722: as the insn pattern to control how the insn is output.
7723:
7724: Defined peephole optimizers are run as assembler code is being output,
7725: so the insns they produce are never combined or rearranged in any way.
1.1 root 7726:
7727: Here is an example, taken from the 68000 machine description:
7728:
7729: @example
7730: (define_peephole
7731: [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
1.1.1.13 root 7732: (set (match_operand:DF 0 "register_operand" "=f")
1.1 root 7733: (match_operand:DF 1 "register_operand" "ad"))]
7734: "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
7735: "*
7736: @{
7737: rtx xoperands[2];
7738: xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1);
7739: #ifdef MOTOROLA
7740: output_asm_insn (\"move.l %1,(sp)\", xoperands);
7741: output_asm_insn (\"move.l %1,-(sp)\", operands);
7742: return \"fmove.d (sp)+,%0\";
7743: #else
7744: output_asm_insn (\"movel %1,sp@@\", xoperands);
7745: output_asm_insn (\"movel %1,sp@@-\", operands);
7746: return \"fmoved sp@@+,%0\";
7747: #endif
7748: @}
7749: ")
7750: @end example
7751:
7752: The effect of this optimization is to change
7753:
7754: @example
7755: jbsr _foobar
7756: addql #4,sp
7757: movel d1,sp@@-
7758: movel d0,sp@@-
7759: fmoved sp@@+,fp0
7760: @end example
7761:
7762: @noindent
7763: into
7764:
7765: @example
7766: jbsr _foobar
7767: movel d1,sp@@
7768: movel d0,sp@@-
7769: fmoved sp@@+,fp0
7770: @end example
7771:
1.1.1.5 root 7772: @ignore
7773: If a peephole matches a sequence including one or more jump insns, you must
7774: take account of the flags such as @code{CC_REVERSED} which specify that the
7775: condition codes are represented in an unusual manner. The compiler
7776: automatically alters any ordinary conditional jumps which occur in such
7777: situations, but the compiler cannot alter jumps which have been replaced by
7778: peephole optimizations. So it is up to you to alter the assembler code
7779: that the peephole produces. Supply C code to write the assembler output,
7780: and in this C code check the condition code status flags and change the
7781: assembler code as appropriate.
7782: @end ignore
7783:
1.1.1.8 root 7784: @var{insn-pattern-1} and so on look @emph{almost} like the second
7785: operand of @code{define_insn}. There is one important difference: the
7786: second operand of @code{define_insn} consists of one or more RTX's
7787: enclosed in square brackets. Usually, there is only one: then the same
7788: action can be written as an element of a @code{define_peephole}. But
7789: when there are multiple actions in a @code{define_insn}, they are
7790: implicitly enclosed in a @code{parallel}. Then you must explicitly
7791: write the @code{parallel}, and the square brackets within it, in the
7792: @code{define_peephole}. Thus, if an insn pattern looks like this,
7793:
7794: @example
7795: (define_insn "divmodsi4"
7796: [(set (match_operand:SI 0 "general_operand" "=d")
7797: (div:SI (match_operand:SI 1 "general_operand" "0")
7798: (match_operand:SI 2 "general_operand" "dmsK")))
7799: (set (match_operand:SI 3 "general_operand" "=d")
7800: (mod:SI (match_dup 1) (match_dup 2)))]
7801: "TARGET_68020"
7802: "divsl%.l %2,%3:%0")
7803: @end example
7804:
7805: @noindent
7806: then the way to mention this insn in a peephole is as follows:
7807:
7808: @example
7809: (define_peephole
7810: [@dots{}
7811: (parallel
7812: [(set (match_operand:SI 0 "general_operand" "=d")
7813: (div:SI (match_operand:SI 1 "general_operand" "0")
7814: (match_operand:SI 2 "general_operand" "dmsK")))
7815: (set (match_operand:SI 3 "general_operand" "=d")
7816: (mod:SI (match_dup 1) (match_dup 2)))])
7817: @dots{}]
7818: @dots{})
7819: @end example
7820:
1.1 root 7821: @node Expander Definitions,, Peephole Definitions, Machine Desc
7822: @section Defining RTL Sequences for Code Generation
7823:
7824: On some target machines, some standard pattern names for RTL generation
7825: cannot be handled with single insn, but a sequence of RTL insns can
7826: represent them. For these target machines, you can write a
1.1.1.8 root 7827: @code{define_expand} to specify how to generate the sequence of RTL.
1.1 root 7828:
1.1.1.8 root 7829: A @code{define_expand} is an RTL expression that looks almost like a
7830: @code{define_insn}; but, unlike the latter, a @code{define_expand} is used
1.1 root 7831: only for RTL generation and it can produce more than one RTL insn.
7832:
1.1.1.8 root 7833: A @code{define_expand} RTX has four operands:
1.1 root 7834:
7835: @itemize @bullet
7836: @item
1.1.1.8 root 7837: The name. Each @code{define_expand} must have a name, since the only
1.1 root 7838: use for it is to refer to it by name.
7839:
7840: @item
7841: The RTL template. This is just like the RTL template for a
1.1.1.8 root 7842: @code{define_peephole} in that it is a vector of RTL expressions
1.1 root 7843: each being one insn.
7844:
7845: @item
7846: The condition, a string containing a C expression. This expression is
7847: used to express how the availability of this pattern depends on
7848: subclasses of target machine, selected by command-line options when
7849: GNU CC is run. This is just like the condition of a
1.1.1.8 root 7850: @code{define_insn} that has a standard name.
1.1 root 7851:
7852: @item
7853: The preparation statements, a string containing zero or more C
7854: statements which are to be executed before RTL code is generated from
7855: the RTL template.
7856:
7857: Usually these statements prepare temporary registers for use as
7858: internal operands in the RTL template, but they can also generate RTL
1.1.1.8 root 7859: insns directly by calling routines such as @code{emit_insn}, etc.
1.1 root 7860: Any such insns precede the ones that come from the RTL template.
7861: @end itemize
7862:
1.1.1.8 root 7863: Every RTL insn emitted by a @code{define_expand} must match some
7864: @code{define_insn} in the machine description. Otherwise, the compiler
7865: will crash when trying to generate code for the insn or trying to optimize
7866: it.
7867:
1.1 root 7868: The RTL template, in addition to controlling generation of RTL insns,
7869: also describes the operands that need to be specified when this pattern
7870: is used. In particular, it gives a predicate for each operand.
7871:
7872: A true operand, which need to be specified in order to generate RTL from
1.1.1.8 root 7873: the pattern, should be described with a @code{match_operand} in its first
1.1 root 7874: occurrence in the RTL template. This enters information on the operand's
7875: predicate into the tables that record such things. GNU CC uses the
7876: information to preload the operand into a register if that is required for
7877: valid RTL code. If the operand is referred to more than once, subsequent
1.1.1.8 root 7878: references should use @code{match_dup}.
1.1 root 7879:
7880: The RTL template may also refer to internal ``operands'' which are
7881: temporary registers or labels used only within the sequence made by the
1.1.1.8 root 7882: @code{define_expand}. Internal operands are substituted into the RTL
7883: template with @code{match_dup}, never with @code{match_operand}. The
1.1 root 7884: values of the internal operands are not passed in as arguments by the
7885: compiler when it requests use of this pattern. Instead, they are computed
7886: within the pattern, in the preparation statements. These statements
7887: compute the values and store them into the appropriate elements of
1.1.1.8 root 7888: @code{operands} so that @code{match_dup} can find them.
1.1 root 7889:
7890: There are two special macros defined for use in the preparation statements:
7891: @code{DONE} and @code{FAIL}. Use them with a following semicolon,
7892: as a statement.
7893:
7894: @table @code
7895: @item DONE
7896: Use the @code{DONE} macro to end RTL generation for the pattern. The
7897: only RTL insns resulting from the pattern on this occasion will be
7898: those already emitted by explicit calls to @code{emit_insn} within the
7899: preparation statements; the RTL template will not be generated.
7900:
7901: @item FAIL
7902: Make the pattern fail on this occasion. When a pattern fails, it means
7903: that the pattern was not truly available. The calling routines in the
7904: compiler will try other strategies for code generation using other patterns.
7905:
7906: Failure is currently supported only for binary operations (addition,
7907: multiplication, shifting, etc.).
7908:
7909: Do not emit any insns explicitly with @code{emit_insn} before failing.
7910: @end table
7911:
7912: Here is an example, the definition of left-shift for the SPUR chip:
7913:
7914: @example
7915: (define_expand "ashlsi3"
7916: [(set (match_operand:SI 0 "register_operand" "")
7917: (ashift:SI
7918: (match_operand:SI 1 "register_operand" "")
7919: (match_operand:SI 2 "nonmemory_operand" "")))]
7920: ""
7921: "
7922: @{
7923: if (GET_CODE (operands[2]) != CONST_INT
7924: || (unsigned) INTVAL (operands[2]) > 3)
7925: FAIL;
7926: @}")
7927: @end example
7928:
7929: @noindent
1.1.1.8 root 7930: This example uses @code{define_expand} so that it can generate an RTL insn
1.1 root 7931: for shifting when the shift-count is in the supported range of 0 to 3 but
7932: fail in other cases where machine insns aren't available. When it fails,
7933: the compiler tries another strategy using different patterns (such as, a
7934: library call).
7935:
7936: If the compiler were able to handle nontrivial condition-strings in
1.1.1.8 root 7937: patterns with names, then it would be possible to use a
7938: @code{define_insn} in that case. Here is another case (zero-extension
7939: on the 68000) which makes more use of the power of @code{define_expand}:
1.1 root 7940:
7941: @example
7942: (define_expand "zero_extendhisi2"
7943: [(set (match_operand:SI 0 "general_operand" "")
7944: (const_int 0))
7945: (set (strict_low_part
7946: (subreg:HI
1.1.1.8 root 7947: (match_dup 0)
1.1 root 7948: 0))
7949: (match_operand:HI 1 "general_operand" ""))]
7950: ""
7951: "operands[1] = make_safe_from (operands[1], operands[0]);")
7952: @end example
7953:
7954: @noindent
7955: Here two RTL insns are generated, one to clear the entire output operand
7956: and the other to copy the input operand into its low half. This sequence
7957: is incorrect if the input operand refers to [the old value of] the output
7958: operand, so the preparation statement makes sure this isn't so. The
7959: function @code{make_safe_from} copies the @code{operands[1]} into a
7960: temporary register if it refers to @code{operands[0]}. It does this
7961: by emitting another RTL insn.
7962:
7963: Finally, a third example shows the use of an internal operand.
1.1.1.8 root 7964: Zero-extension on the SPUR chip is done by @code{and}-ing the result
1.1 root 7965: against a halfword mask. But this mask cannot be represented by a
1.1.1.8 root 7966: @code{const_int} because the constant value is too large to be legitimate
1.1 root 7967: on this machine. So it must be copied into a register with
1.1.1.8 root 7968: @code{force_reg} and then the register used in the @code{and}.
1.1 root 7969:
7970: @example
7971: (define_expand "zero_extendhisi2"
7972: [(set (match_operand:SI 0 "register_operand" "")
7973: (and:SI (subreg:SI
7974: (match_operand:HI 1 "register_operand" "")
7975: 0)
7976: (match_dup 2)))]
7977: ""
7978: "operands[2]
7979: = force_reg (SImode, gen_rtx (CONST_INT,
7980: VOIDmode, 65535)); ")
7981: @end example
7982:
1.1.1.8 root 7983: @strong{Note:} If the @code{define_expand} is used to serve a standard
7984: binary or unary arithmetic operation, then the last insn it generates
7985: must not be a @code{code_label}, @code{barrier} or @code{note}. It must
7986: be an @code{insn}, @code{jump_insn} or @code{call_insn}.
7987:
1.1 root 7988: @node Machine Macros, Config, Machine Desc, Top
7989: @chapter Machine Description Macros
7990:
7991: The other half of the machine description is a C header file conventionally
7992: given the name @file{tm-@var{machine}.h}. The file @file{tm.h} should be a
7993: link to it. The header file @file{config.h} includes @file{tm.h} and most
7994: compiler source files include @file{config.h}.
7995:
7996: @menu
1.1.1.9 root 7997: * Run-time Target:: Defining @samp{-m} options like @samp{-m68000} and @samp{-m68020}.
1.1 root 7998: * Storage Layout:: Defining sizes and alignments of data types.
7999: * Registers:: Naming and describing the hardware registers.
8000: * Register Classes:: Defining the classes of hardware registers.
8001: * Stack Layout:: Defining which way the stack grows and by how much.
1.1.1.12 root 8002: * Library Calls:: Specifying how to call certain library routines.
1.1 root 8003: * Addressing Modes:: Defining addressing modes valid for memory operands.
1.1.1.8 root 8004: * Delayed Branch:: Do branches execute the following instruction?
1.1 root 8005: * Condition Code:: Defining how insns update the condition code.
1.1.1.5 root 8006: * Cross-compilation:: Handling floating point for cross-compilers.
1.1 root 8007: * Misc:: Everything else.
1.1.1.11 root 8008: * Assembler Format:: Defining how to write insns and pseudo-ops to output.
1.1 root 8009: @end menu
8010:
8011: @node Run-time Target, Storage Layout, Machine Macros, Machine Macros
8012: @section Run-time Target Specification
8013:
8014: @table @code
8015: @item CPP_PREDEFINES
8016: Define this to be a string constant containing @samp{-D} options to
8017: define the predefined macros that identify this machine and system.
8018: These macros will be predefined unless the @samp{-ansi} option is
8019: specified.
8020:
1.1.1.4 root 8021: In addition, a parallel set of macros are predefined, whose names are
8022: made by appending @samp{__} at the beginning and at the end. These
8023: @samp{__} macros are permitted by the ANSI standard, so they are
8024: predefined regardless of whether @samp{-ansi} is specified.
8025:
8026: For example, on the Sun, one can use the following value:
1.1 root 8027:
8028: @example
8029: "-Dmc68000 -Dsun -Dunix"
8030: @end example
8031:
1.1.1.8 root 8032: The result is to define the macros @code{__mc68000__}, @code{__sun__}
8033: and @code{__unix__} unconditionally, and the macros @code{mc68000},
8034: @code{sun} and @code{unix} provided @samp{-ansi} is not specified.
1.1.1.4 root 8035:
1.1 root 8036: @item CPP_SPEC
8037: A C string constant that tells the GNU CC driver program options to
8038: pass to CPP. It can also specify how to translate options you
8039: give to GNU CC into options for GNU CC to pass to the CPP.
8040:
8041: Do not define this macro if it does not need to do anything.
8042:
8043: @item CC1_SPEC
8044: A C string constant that tells the GNU CC driver program options to
8045: pass to CC1. It can also specify how to translate options you
8046: give to GNU CC into options for GNU CC to pass to the CC1.
8047:
8048: Do not define this macro if it does not need to do anything.
8049:
8050: @item extern int target_flags;
8051: This declaration should be present.
8052:
8053: @item TARGET_@dots{}
8054: This series of macros is to allow compiler command arguments to
8055: enable or disable the use of optional features of the target machine.
8056: For example, one machine description serves both the 68000 and
8057: the 68020; a command argument tells the compiler whether it should
8058: use 68020-only instructions or not. This command argument works
8059: by means of a macro @code{TARGET_68020} that tests a bit in
8060: @code{target_flags}.
8061:
8062: Define a macro @code{TARGET_@var{featurename}} for each such option.
8063: Its definition should test a bit in @code{target_flags}; for example:
8064:
8065: @example
8066: #define TARGET_68020 (target_flags & 1)
8067: @end example
8068:
8069: One place where these macros are used is in the condition-expressions
8070: of instruction patterns. Note how @code{TARGET_68020} appears
8071: frequently in the 68000 machine description file, @file{m68k.md}.
8072: Another place they are used is in the definitions of the other
8073: macros in the @file{tm-@var{machine}.h} file.
8074:
8075: @item TARGET_SWITCHES
8076: This macro defines names of command options to set and clear
8077: bits in @code{target_flags}. Its definition is an initializer
8078: with a subgrouping for each command option.
8079:
8080: Each subgrouping contains a string constant, that defines the option
8081: name, and a number, which contains the bits to set in
8082: @code{target_flags}. A negative number says to clear bits instead;
8083: the negative of the number is which bits to clear. The actual option
8084: name is made by appending @samp{-m} to the specified name.
8085:
8086: One of the subgroupings should have a null string. The number in
8087: this grouping is the default value for @code{target_flags}. Any
8088: target options act starting with that value.
8089:
8090: Here is an example which defines @samp{-m68000} and @samp{-m68020}
8091: with opposite meanings, and picks the latter as the default:
8092:
8093: @example
8094: #define TARGET_SWITCHES \
8095: @{ @{ "68020", 1@}, \
8096: @{ "68000", -1@}, \
8097: @{ "", 1@}@}
8098: @end example
8099:
8100: @item OVERRIDE_OPTIONS
8101: Sometimes certain combinations of command options do not make sense on
8102: a particular target machine. You can define a macro
8103: @code{OVERRIDE_OPTIONS} to take account of this. This macro, if
8104: defined, is executed once just after all the command options have been
8105: parsed.
8106: @end table
8107:
8108: @node Storage Layout, Registers, Run-time Target, Machine Macros
8109: @section Storage Layout
8110:
8111: Note that the definitions of the macros in this table which are sizes or
8112: alignments measured in bits do not need to be constant. They can be C
8113: expressions that refer to static variables, such as the @code{target_flags}.
8114: @xref{Run-time Target}.
8115:
8116: @table @code
8117: @item BITS_BIG_ENDIAN
8118: Define this macro if the most significant bit in a byte has the lowest
8119: number. This means that bit-field instructions count from the most
8120: significant bit. If the machine has no bit-field instructions, this
8121: macro is irrelevant.
8122:
1.1.1.8 root 8123: This macro does not affect the way structure fields are packed into
8124: bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}.
8125:
1.1 root 8126: @item BYTES_BIG_ENDIAN
8127: Define this macro if the most significant byte in a word has the
8128: lowest number.
8129:
8130: @item WORDS_BIG_ENDIAN
8131: Define this macro if, in a multiword object, the most significant
8132: word has the lowest number.
8133:
8134: @item BITS_PER_UNIT
8135: Number of bits in an addressable storage unit (byte); normally 8.
8136:
8137: @item BITS_PER_WORD
8138: Number of bits in a word; normally 32.
8139:
8140: @item UNITS_PER_WORD
8141: Number of storage units in a word; normally 4.
8142:
8143: @item POINTER_SIZE
8144: Width of a pointer, in bits.
8145:
8146: @item POINTER_BOUNDARY
8147: Alignment required for pointers stored in memory, in bits.
8148:
8149: @item PARM_BOUNDARY
1.1.1.7 root 8150: Normal alignment required for function parameters on the stack, in
8151: bits. All stack parameters receive least this much alignment
8152: regardless of data type. On most machines, this is the same as the
8153: size of an integer.
8154:
8155: @item MAX_PARM_BOUNDARY
8156: Largest alignment required for any stack parameters, in bits. If the
8157: data type of the parameter calls for more alignment than
8158: @code{PARM_BOUNDARY}, then it is given extra padding up to this limit.
8159:
8160: Don't define this macro if it would be equal to @code{PARM_BOUNDARY};
8161: in other words, if the alignment of a stack parameter should not
8162: depend on its data type (as is the case on most machines).
1.1 root 8163:
8164: @item STACK_BOUNDARY
8165: Define this macro if you wish to preserve a certain alignment for
8166: the stack pointer at all times. The definition is a C expression
8167: for the desired alignment (measured in bits).
8168:
8169: @item FUNCTION_BOUNDARY
8170: Alignment required for a function entry point, in bits.
8171:
8172: @item BIGGEST_ALIGNMENT
8173: Biggest alignment that any data type can require on this machine, in bits.
8174:
1.1.1.8 root 8175: @item CONSTANT_ALIGNMENT (@var{code}, @var{typealign})
8176: A C expression to compute the alignment for a constant. The argument
8177: @var{typealign} is the alignment required for the constant's data type.
8178: @var{code} is the tree code of the constant itself.
8179:
8180: If this macro is not defined, the default is to use @var{typealign}. If
8181: you do define this macro, the value must be a multiple of
8182: @var{typealign}.
8183:
8184: The purpose of defining this macro is usually to cause string constants
8185: to be word aligned so that @file{dhrystone} can be made to run faster.
8186:
1.1 root 8187: @item EMPTY_FIELD_BOUNDARY
8188: Alignment in bits to be given to a structure bit field that follows an
8189: empty field such as @code{int : 0;}.
8190:
8191: @item STRUCTURE_SIZE_BOUNDARY
8192: Number of bits which any structure or union's size must be a multiple of.
8193: Each structure or union's size is rounded up to a multiple of this.
8194:
8195: If you do not define this macro, the default is the same as
8196: @code{BITS_PER_UNIT}.
8197:
8198: @item STRICT_ALIGNMENT
8199: Define this if instructions will fail to work if given data not
8200: on the nominal alignment. If instructions will merely go slower
8201: in that case, do not define this macro.
8202:
8203: @item PCC_BITFIELD_TYPE_MATTERS
8204: Define this if you wish to imitate a certain bizarre behavior pattern
8205: of some instances of PCC: a bit field whose declared type is
8206: @code{int} has the same effect on the size and alignment of a
8207: structure as an actual @code{int} would have.
8208:
1.1.1.10 root 8209: If the macro is defined, then its definition should be a C expression;
8210: a nonzero value for the expression enables PCC-compatible behavior.
8211:
1.1 root 8212: Just what effect that is in GNU CC depends on other parameters, but on
8213: most machines it would force the structure's alignment and size to a
8214: multiple of 32 or @code{BIGGEST_ALIGNMENT} bits.
8215:
1.1.1.7 root 8216: @item MAX_FIXED_MODE_SIZE
8217: An integer expression for the largest integer machine mode that should
8218: actually be used. All integer machine modes of this size or smaller
8219: can be used for structures and unions with the appropriate sizes.
8220:
1.1 root 8221: @item CHECK_FLOAT_VALUE (@var{mode}, @var{value})
8222: A C statement to validate the value @var{value} (or type
8223: @code{double}) for mode @var{mode}. This means that you check whether
8224: @var{value} fits within the possible range of values for mode
8225: @var{mode} on this target machine. The mode @var{mode} is always
8226: @code{SFmode} or @code{DFmode}.
8227:
8228: If @var{value} is not valid, you should call @code{error} to print an
8229: error message and then assign some valid value to @var{value}.
8230: Allowing an invalid value to go through the compiler can produce
8231: incorrect assembler code which may even cause Unix assemblers to
8232: crash.
8233:
8234: This macro need not be defined if there is no work for it to do.
8235: @end table
8236:
8237: @node Registers, Register Classes, Storage Layout, Machine Macros
8238: @section Register Usage
8239:
8240: @table @code
8241: @item FIRST_PSEUDO_REGISTER
8242: Number of hardware registers known to the compiler. They receive
8243: numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
8244: pseudo register's number really is assigned the number
8245: @code{FIRST_PSEUDO_REGISTER}.
8246:
8247: @item FIXED_REGISTERS
8248: An initializer that says which registers are used for fixed purposes
8249: all throughout the compiled code and are therefore not available for
8250: general allocation. These would include the stack pointer, the frame
8251: pointer (except on machines where that can be used as a general
8252: register when no frame pointer is needed), the program counter on
8253: machines where that is considered one of the addressable registers,
8254: and any other numbered register with a standard use.
8255:
8256: This information is expressed as a sequence of numbers, separated by
8257: commas and surrounded by braces. The @var{n}th number is 1 if
8258: register @var{n} is fixed, 0 otherwise.
8259:
8260: The table initialized from this macro, and the table initialized by
8261: the following one, may be overridden at run time either automatically,
8262: by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
8263: the user with the command options @samp{-ffixed-@var{reg}},
8264: @samp{-fcall-used-@var{reg}} and @samp{-fcall-saved-@var{reg}}.
8265:
8266: @item CALL_USED_REGISTERS
8267: Like @code{FIXED_REGISTERS} but has 1 for each register that is
8268: clobbered (in general) by function calls as well as for fixed
8269: registers. This macro therefore identifies the registers that are not
8270: available for general allocation of values that must live across
8271: function calls.
8272:
8273: If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
8274: automatically saves it on function entry and restores it on function
8275: exit, if the register is used within the function.
8276:
1.1.1.6 root 8277: @item DEFAULT_CALLER_SAVES
1.1.1.8 root 8278: Define this macro if function calls on the target machine do not preserve
1.1.1.6 root 8279: any registers; in other words, if @code{CALL_USED_REGISTERS} has 1
8280: for all registers. This macro enables @samp{-fcaller-saves} by default.
8281: Eventually that option will be enabled by default on all machines and both
8282: the option and this macro will be eliminated.
8283:
1.1 root 8284: @item CONDITIONAL_REGISTER_USAGE
8285: Zero or more C statements that may conditionally modify two variables
8286: @code{fixed_regs} and @code{call_used_regs} (both of type @code{char
8287: []}) after they have been initialized from the two preceding macros.
8288:
8289: This is necessary in case the fixed or call-clobbered registers depend
8290: on target flags.
8291:
8292: You need not define this macro if it has no work to do.
8293:
8294: If the usage of an entire class of registers depends on the target
1.1.1.5 root 8295: flags, you may indicate this to GCC by using this macro to modify
1.1 root 8296: @code{fixed_regs} and @code{call_used_regs} to 1 for each of the
1.1.1.5 root 8297: registers in the classes which should not be used by GCC. Also define
1.1 root 8298: the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it
8299: is called with a letter for a class that shouldn't be used.
8300:
8301: (However, if this class is not included in @code{GENERAL_REGS} and all
8302: of the insn patterns whose constraints permit this class are
8303: controlled by target switches, then GCC will automatically avoid using
8304: these registers when the target switches are opposed to them.)
8305:
8306: @item OVERLAPPING_REGNO_P (@var{regno})
1.1.1.5 root 8307: If defined, this is a C expression whose value is nonzero if hard
8308: register number @var{regno} is an overlapping register. This means a
8309: hard register which overlaps a hard register with a different number.
8310: (Such overlap is undesirable, but occasionally it allows a machine to
8311: be supported which otherwise could not be.) This macro must return
8312: nonzero for @emph{all} the registers which overlap each other. GNU CC
8313: can use an overlapping register only in certain limited ways. It can
8314: be used for allocation within a basic block, and may be spilled for
8315: reloading; that is all.
1.1 root 8316:
8317: If this macro is not defined, it means that none of the hard registers
8318: overlap each other. This is the usual situation.
8319:
8320: @item INSN_CLOBBERS_REGNO_P (@var{insn}, @var{regno})
8321: If defined, this is a C expression whose value should be nonzero if
8322: the insn @var{insn} has the effect of mysteriously clobbering the
8323: contents of hard register number @var{regno}. By ``mysterious'' we
8324: mean that the insn's RTL expression doesn't describe such an effect.
8325:
8326: If this macro is not defined, it means that no insn clobbers registers
8327: mysteriously. This is the usual situation; all else being equal,
8328: it is best for the RTL expression to show all the activity.
8329:
8330: @item PRESERVE_DEATH_INFO_REGNO_P (@var{regno})
8331: If defined, this is a C expression whose value is nonzero if accurate
8332: @code{REG_DEAD} notes are needed for hard register number @var{regno}
8333: at the time of outputting the assembler code. When this is so, a few
8334: optimizations that take place after register allocation and could
8335: invalidate the death notes are not done when this register is
8336: involved.
8337:
1.1.1.8 root 8338: You would arrange to preserve death info for a register when some of the
8339: code in the machine description which is executed to write the assembler
8340: code looks at the death notes. This is necessary only when the actual
8341: hardware feature which GNU CC thinks of as a register is not actually a
8342: register of the usual sort. (It might, for example, be a hardware
8343: stack.)
1.1 root 8344:
8345: If this macro is not defined, it means that no death notes need to be
8346: preserved. This is the usual situation.
8347:
1.1.1.10 root 8348: @item HARD_REGNO_NREGS (@var{regno}, @var{mode})
1.1 root 8349: A C expression for the number of consecutive hard registers, starting
8350: at register number @var{regno}, required to hold a value of mode
8351: @var{mode}.
8352:
8353: On a machine where all registers are exactly one word, a suitable
8354: definition of this macro is
8355:
8356: @example
8357: #define HARD_REGNO_NREGS(REGNO, MODE) \
8358: ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \
8359: / UNITS_PER_WORD))
8360: @end example
8361:
8362: @item HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
8363: A C expression that is nonzero if it is permissible to store a value
8364: of mode @var{mode} in hard register number @var{regno} (or in several
8365: registers starting with that one). For a machine where all registers
8366: are equivalent, a suitable definition is
8367:
8368: @example
8369: #define HARD_REGNO_MODE_OK(REGNO, MODE) 1
8370: @end example
8371:
1.1.1.8 root 8372: It is not necessary for this macro to check for the numbers of fixed
8373: registers, because the allocation mechanism considers them to be always
8374: occupied.
8375:
8376: On some machines, double-precision values must be kept in even/odd
8377: register pairs. The way to implement that is to define this macro
8378: to reject odd register numbers for such modes.
8379:
8380: GNU CC assumes that it can always move values between registers and
8381: (suitably addressed) memory locations. If it is impossible to move a
8382: value of a certain mode between memory and certain registers, then
8383: @code{HARD_REGNO_MODE_OK} must not allow this mode in those registers.
1.1 root 8384:
8385: Many machines have special registers for floating point arithmetic.
8386: Often people assume that floating point machine modes are allowed only
8387: in floating point registers. This is not true. Any registers that
8388: can hold integers can safely @emph{hold} a floating point machine
8389: mode, whether or not floating arithmetic can be done on it in those
8390: registers.
8391:
1.1.1.9 root 8392: On some machines, though, the converse is true: fixed-point machine
8393: modes may not go in floating registers. This is true if the floating
8394: registers normalize any value stored in them, because storing a
8395: non-floating value there would garble it. In this case,
8396: @code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in
8397: floating registers. But if the floating registers do not automatically
8398: normalize, if you can store any bit pattern in one and retrieve it
8399: unchanged without a trap, then any machine mode may go in a floating
8400: register and this macro should say so.
8401:
8402: The primary significance of special floating registers is rather that
8403: they are the registers acceptable in floating point arithmetic
8404: instructions. However, this is of no concern to
8405: @code{HARD_REGNO_MODE_OK}. You handle it by writing the proper
8406: constraints for those instructions.
8407:
8408: On some machines, the floating registers are especially slow to access,
8409: so that it is better to store a value in a stack frame than in such a
8410: register if floating point arithmetic is not being done. As long as the
8411: floating registers are not in class @code{GENERAL_REGS}, they will not
8412: be used unless some insn's constraint asks for one.
1.1 root 8413:
8414: @item MODES_TIEABLE_P (@var{mode1}, @var{mode2})
8415: A C expression that is nonzero if it is desirable to choose register
8416: allocation so as to avoid move instructions between a value of mode
8417: @var{mode1} and a value of mode @var{mode2}.
8418:
8419: If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
8420: @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different
8421: for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1},
8422: @var{mode2})} must be zero.
8423:
8424: @item PC_REGNUM
8425: If the program counter has a register number, define this as that
8426: register number. Otherwise, do not define it.
8427:
8428: @item STACK_POINTER_REGNUM
8429: The register number of the stack pointer register, which must also be
8430: a fixed register according to @code{FIXED_REGISTERS}. On many
8431: machines, the hardware determines which register this is.
8432:
8433: @item FRAME_POINTER_REGNUM
8434: The register number of the frame pointer register, which is used to
8435: access automatic variables in the stack frame. On some machines, the
8436: hardware determines which register this is. On other machines, you
8437: can choose any register you wish for this purpose.
8438:
8439: @item FRAME_POINTER_REQUIRED
1.1.1.9 root 8440: A C expression which is nonzero if a function must have and use a frame
8441: pointer. This expression is evaluated twice: at the beginning of
8442: generating RTL, and in the reload pass. If its value is nonzero at
8443: either time, then the function will have a frame pointer.
8444:
8445: The expression can in principle examine the current function and decide
8446: according to the facts, but on most machines the constant 0 or the
8447: constant 1 suffices. Use 0 when the machine allows code to be generated
8448: with no frame pointer, and doing so saves some time or space. Use 1
8449: when there is no possible advantage to avoiding a frame pointer.
1.1 root 8450:
1.1.1.5 root 8451: In certain cases, the compiler does not know how to produce valid code
8452: without a frame pointer. The compiler recognizes those cases and
8453: automatically gives the function a frame pointer regardless of what
1.1 root 8454: @code{FRAME_POINTER_REQUIRED} says. You don't need to worry about
8455: them.@refill
8456:
8457: In a function that does not require a frame pointer, the frame pointer
8458: register can be allocated for ordinary usage, unless you mark it as a
8459: fixed register. See @code{FIXED_REGISTERS} for more information.
8460:
8461: @item ARG_POINTER_REGNUM
8462: The register number of the arg pointer register, which is used to
8463: access the function's argument list. On some machines, this is the
8464: same as the frame pointer register. On some machines, the hardware
8465: determines which register this is. On other machines, you can choose
8466: any register you wish for this purpose. If this is not the same
8467: register as the frame pointer register, then you must mark it as a
8468: fixed register according to @code{FIXED_REGISTERS}.
8469:
8470: @item STATIC_CHAIN_REGNUM
8471: The register number used for passing a function's static chain
8472: pointer. This is needed for languages such as Pascal and Algol where
8473: functions defined within other functions can access the local
8474: variables of the outer functions; it is not currently used because C
8475: does not provide this feature, but you must define the macro.
8476:
8477: The static chain register need not be a fixed register.
8478:
8479: @item STRUCT_VALUE_REGNUM
8480: When a function's value's mode is @code{BLKmode}, the value is not
8481: returned according to @code{FUNCTION_VALUE}. Instead, the caller
8482: passes the address of a block of memory in which the value should be
8483: stored.
8484:
8485: If this value is passed in a register, then @code{STRUCT_VALUE_REGNUM}
8486: should be the number of that register.
8487:
8488: @item STRUCT_VALUE
8489: If the structure value address is not passed in a register, define
8490: @code{STRUCT_VALUE} as an expression returning an RTX for the place
1.1.1.8 root 8491: where the address is passed. If it returns a @code{mem} RTX, the
1.1 root 8492: address is passed as an ``invisible'' first argument.
8493:
8494: @item STRUCT_VALUE_INCOMING_REGNUM
8495: On some architectures the place where the structure value address
8496: is found by the called function is not the same place that the
8497: caller put it. This can be due to register windows, or it could
8498: be because the function prologue moves it to a different place.
8499:
8500: If the incoming location of the structure value address is in a
8501: register, define this macro as the register number.
8502:
8503: @item STRUCT_VALUE_INCOMING
8504: If the incoming location is not a register, define
8505: @code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the
8506: called function should find the value. If it should find the value on
1.1.1.8 root 8507: the stack, define this to create a @code{mem} which refers to the
8508: frame pointer. If the value is a @code{mem}, the compiler assumes it
1.1 root 8509: is for an invisible first argument, and leaves space for it when
8510: finding the first real argument.
8511:
8512: @item REG_ALLOC_ORDER
8513: If defined, an initializer for a vector of integers, containing the
8514: numbers of hard registers in the order in which the GNU CC should
8515: prefer to use them (from most preferred to least).
8516:
8517: If this macro is not defined, registers are used lowest numbered first
8518: (all else being equal).
8519:
8520: One use of this macro is on the 360, where the highest numbered
8521: registers must always be saved and the save-multiple-registers
8522: instruction supports only sequences of consecutive registers. This
8523: macro is defined to cause the highest numbered allocatable registers
8524: to be used first.
8525: @end table
8526:
8527: @node Register Classes, Stack Layout, Registers, Machine Macros
8528: @section Register Classes
8529:
8530: On many machines, the numbered registers are not all equivalent.
8531: For example, certain registers may not be allowed for indexed addressing;
8532: certain registers may not be allowed in some instructions. These machine
8533: restrictions are described to the compiler using @dfn{register classes}.
8534:
8535: You define a number of register classes, giving each one a name and saying
8536: which of the registers belong to it. Then you can specify register classes
8537: that are allowed as operands to particular instruction patterns.
8538:
8539: In general, each register will belong to several classes. In fact, one
8540: class must be named @code{ALL_REGS} and contain all the registers. Another
8541: class must be named @code{NO_REGS} and contain no registers. Often the
8542: union of two classes will be another class; however, this is not required.
8543:
8544: One of the classes must be named @code{GENERAL_REGS}. There is nothing
8545: terribly special about the name, but the operand constraint letters
8546: @samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is
8547: the same as @code{ALL_REGS}, just define it as a macro which expands
8548: to @code{ALL_REGS}.
8549:
8550: The way classes other than @code{GENERAL_REGS} are specified in operand
8551: constraints is through machine-dependent operand constraint letters.
8552: You can define such letters to correspond to various classes, then use
8553: them in operand constraints.
8554:
8555: You should define a class for the union of two classes whenever some
8556: instruction allows both classes. For example, if an instruction allows
8557: either a floating-point (coprocessor) register or a general register for a
8558: certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
8559: which includes both of them. Otherwise you will get suboptimal code.
8560:
8561: You must also specify certain redundant information about the register
8562: classes: for each class, which classes contain it and which ones are
8563: contained in it; for each pair of classes, the largest class contained
8564: in their union.
8565:
1.1.1.8 root 8566: When a value occupying several consecutive registers is expected in a
8567: certain class, all the registers used must belong to that class.
8568: Therefore, register classes cannot be used to enforce a requirement for
8569: a register pair to start with an even-numbered register. The way to
8570: specify this requirement is with @code{HARD_REGNO_MODE_OK}.
8571:
1.1 root 8572: Register classes used for input-operands of bitwise-and or shift
8573: instructions have a special requirement: each such class must have, for
8574: each fixed-point machine mode, a subclass whose registers can transfer that
8575: mode to or from memory. For example, on some machines, the operations for
8576: single-byte values (@code{QImode}) are limited to certain registers. When
8577: this is so, each register class that is used in a bitwise-and or shift
8578: instruction must have a subclass consisting of registers from which
8579: single-byte values can be loaded or stored. This is so that
8580: @code{PREFERRED_RELOAD_CLASS} can always have a possible value to return.
8581:
8582: @table @code
8583: @item enum reg_class
8584: An enumeral type that must be defined with all the register class names
8585: as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS}
8586: must be the last register class, followed by one more enumeral value,
8587: @code{LIM_REG_CLASSES}, which is not a register class but rather
8588: tells how many classes there are.
8589:
8590: Each register class has a number, which is the value of casting
8591: the class name to type @code{int}. The number serves as an index
8592: in many of the tables described below.
8593:
8594: @item N_REG_CLASSES
8595: The number of distinct register classes, defined as follows:
8596:
8597: @example
8598: #define N_REG_CLASSES (int) LIM_REG_CLASSES
8599: @end example
8600:
8601: @item REG_CLASS_NAMES
8602: An initializer containing the names of the register classes as C string
8603: constants. These names are used in writing some of the debugging dumps.
8604:
8605: @item REG_CLASS_CONTENTS
8606: An initializer containing the contents of the register classes, as integers
8607: which are bit masks. The @var{n}th integer specifies the contents of class
8608: @var{n}. The way the integer @var{mask} is interpreted is that
8609: register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
8610:
8611: When the machine has more than 32 registers, an integer does not suffice.
8612: Then the integers are replaced by sub-initializers, braced groupings containing
8613: several integers. Each sub-initializer must be suitable as an initializer
8614: for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
8615:
8616: @item REGNO_REG_CLASS (@var{regno})
8617: A C expression whose value is a register class containing hard register
8618: @var{regno}. In general there is more that one such class; choose a class
8619: which is @dfn{minimal}, meaning that no smaller class also contains the
8620: register.
8621:
8622: @item BASE_REG_CLASS
8623: A macro whose definition is the name of the class to which a valid
8624: base register must belong. A base register is one used in an address
8625: which is the register value plus a displacement.
8626:
8627: @item INDEX_REG_CLASS
8628: A macro whose definition is the name of the class to which a valid
8629: index register must belong. An index register is one used in an
8630: address where its value is either multiplied by a scale factor or
8631: added to another register (as well as added to a displacement).
8632:
8633: @item REG_CLASS_FROM_LETTER (@var{char})
8634: A C expression which defines the machine-dependent operand constraint
8635: letters for register classes. If @var{char} is such a letter, the
8636: value should be the register class corresponding to it. Otherwise,
8637: the value should be @code{NO_REGS}.
8638:
8639: @item REGNO_OK_FOR_BASE_P (@var{num})
8640: A C expression which is nonzero if register number @var{num} is
8641: suitable for use as a base register in operand addresses. It may be
8642: either a suitable hard register or a pseudo register that has been
8643: allocated such a hard register.
8644:
8645: @item REGNO_OK_FOR_INDEX_P (@var{num})
8646: A C expression which is nonzero if register number @var{num} is
8647: suitable for use as an index register in operand addresses. It may be
8648: either a suitable hard register or a pseudo register that has been
8649: allocated such a hard register.
8650:
8651: The difference between an index register and a base register is that
8652: the index register may be scaled. If an address involves the sum of
8653: two registers, neither one of them scaled, then either one may be
8654: labeled the ``base'' and the other the ``index''; but whichever
8655: labeling is used must fit the machine's constraints of which registers
8656: may serve in each capacity. The compiler will try both labelings,
8657: looking for one that is valid, and will reload one or both registers
8658: only if neither labeling works.
8659:
8660: @item PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
8661: A C expression that places additional restrictions on the register class
8662: to use when it is necessary to copy value @var{x} into a register in class
8663: @var{class}. The value is a register class; perhaps @var{class}, or perhaps
8664: another, smaller class. On many machines, the definition
8665:
8666: @example
8667: #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
8668: @end example
8669:
8670: @noindent
8671: is safe.
8672:
8673: Sometimes returning a more restrictive class makes better code. For
8674: example, on the 68000, when @var{x} is an integer constant that is in range
8675: for a @samp{moveq} instruction, the value of this macro is always
8676: @code{DATA_REGS} as long as @var{class} includes the data registers.
8677: Requiring a data register guarantees that a @samp{moveq} will be used.
8678:
1.1.1.8 root 8679: If @var{x} is a @code{const_double}, by returning @code{NO_REGS}
1.1 root 8680: you can force @var{x} into a memory constant. This is useful on
8681: certain machines where immediate floating values cannot be loaded into
8682: certain kinds of registers.
8683:
8684: In a shift instruction or a bitwise-and instruction, the mode of @var{x},
8685: the value being reloaded, may not be the same as the mode of the
8686: instruction's operand. (They will both be fixed-point modes, however.) In
8687: such a case, @var{class} may not be a safe value to return. @var{class} is
8688: certainly valid for the instruction, but it may not be valid for reloading
8689: @var{x}. This problem can occur on machines such as the 68000 and 80386
8690: where some registers can handle full-word values but cannot handle
8691: single-byte values.
8692:
8693: On such machines, this macro must examine the mode of @var{x} and return a
8694: subclass of @var{class} which can handle loads and stores of that mode. On
8695: the 68000, where address registers cannot handle @code{QImode}, if @var{x}
8696: has @code{QImode} then you must return @code{DATA_REGS}. If @var{class} is
8697: @code{ADDR_REGS}, then there is no correct value to return; but the shift
8698: and bitwise-and instructions don't use @code{ADDR_REGS}, so this fatal case
8699: never arises.
8700:
8701: @item CLASS_MAX_NREGS (@var{class}, @var{mode})
8702: A C expression for the maximum number of consecutive registers
8703: of class @var{class} needed to hold a value of mode @var{mode}.
8704:
8705: This is closely related to the macro @code{HARD_REGNO_NREGS}.
8706: In fact, the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
8707: should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno}, @var{mode})}
8708: for all @var{regno} values in the class @var{class}.
8709:
8710: This macro helps control the handling of multiple-word values
8711: in the reload pass.
8712: @end table
8713:
8714: Two other special macros describe which constants fit which constraint
8715: letters.
8716:
8717: @table @code
8718: @item CONST_OK_FOR_LETTER_P (@var{value}, @var{c})
8719: A C expression that defines the machine-dependent operand constraint letters
8720: that specify particular ranges of integer values. If @var{c} is one
8721: of those letters, the expression should check that @var{value}, an integer,
8722: is in the appropriate range and return 1 if so, 0 otherwise. If @var{c} is
8723: not one of those letters, the value should be 0 regardless of @var{value}.
8724:
8725: @item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c})
8726: A C expression that defines the machine-dependent operand constraint
8727: letters that specify particular ranges of floating values. If @var{c} is
8728: one of those letters, the expression should check that @var{value}, an RTX
1.1.1.8 root 8729: of code @code{const_double}, is in the appropriate range and return 1 if
1.1 root 8730: so, 0 otherwise. If @var{c} is not one of those letters, the value should
8731: be 0 regardless of @var{value}.
8732: @end table
8733:
1.1.1.12 root 8734: @node Stack Layout, Library Calls, Register Classes, Machine Macros
1.1 root 8735: @section Describing Stack Layout
8736:
8737: @table @code
8738: @item STACK_GROWS_DOWNWARD
8739: Define this macro if pushing a word onto the stack moves the stack
8740: pointer to a smaller address.
8741:
8742: When we say, ``define this macro if @dots{},'' it means that the
8743: compiler checks this macro only with @code{#ifdef} so the precise
8744: definition used does not matter.
8745:
8746: @item FRAME_GROWS_DOWNWARD
8747: Define this macro if the addresses of local variable slots are at negative
8748: offsets from the frame pointer.
8749:
8750: @item STARTING_FRAME_OFFSET
8751: Offset from the frame pointer to the first local variable slot to be allocated.
8752:
8753: If @code{FRAME_GROWS_DOWNWARD}, the next slot's offset is found by
8754: subtracting the length of the first slot from @code{STARTING_FRAME_OFFSET}.
8755: Otherwise, it is found by adding the length of the first slot to
8756: the value @code{STARTING_FRAME_OFFSET}.
8757:
8758: @item PUSH_ROUNDING (@var{npushed})
8759: A C expression that is the number of bytes actually pushed onto the
8760: stack when an instruction attempts to push @var{npushed} bytes.
8761:
8762: If the target machine does not have a push instruction, do not define
8763: this macro. That directs GNU CC to use an alternate strategy: to
8764: allocate the entire argument block and then store the arguments into
8765: it.
8766:
8767: On some machines, the definition
8768:
8769: @example
8770: #define PUSH_ROUNDING(BYTES) (BYTES)
8771: @end example
8772:
8773: @noindent
8774: will suffice. But on other machines, instructions that appear
8775: to push one byte actually push two bytes in an attempt to maintain
8776: alignment. Then the definition should be
8777:
8778: @example
8779: #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
8780: @end example
8781:
8782: @item FIRST_PARM_OFFSET (@var{fundecl})
8783: Offset from the argument pointer register to the first argument's
8784: address. On some machines it may depend on the data type of the
8785: function. (In the next version of GNU CC, the argument will be
8786: changed to the function data type rather than its declaration.)
8787:
8788: @item FIRST_PARM_CALLER_OFFSET (@var{fundecl})
8789: Define this macro on machines where register parameters have shadow
8790: locations on the stack, at addresses below the nominal parameter.
8791: This matters because certain arguments cannot be passed on the stack.
8792: On these machines, such arguments must be stored into the shadow
8793: locations.
8794:
8795: This macro should expand into a C expression whose value is the offset
8796: of the first parameter's shadow location from the nominal stack
8797: pointer value. (That value is itself computed by adding the value of
8798: @code{STACK_POINTER_OFFSET} to the stack pointer register.)
8799:
1.1.1.9 root 8800: @item REG_PARM_STACK_SPACE
8801: Define this macro if functions should assume that stack space has been
8802: allocated for arguments even when their values are passed in
8803: registers.
8804:
8805: The actual allocation of such space would be done either by
8806: the call instruction or by the function prologue, or by
1.1.1.10 root 8807: defining @code{FIRST_PARM_CALLER_OFFSET}.
1.1.1.9 root 8808:
1.1.1.6 root 8809: @item STACK_ARGS_ADJUST (@var{size})
8810: Define this macro if the machine requires padding on the stack for
8811: certain function calls. This is padding on a per-function-call basis,
8812: not padding for individual arguments.
8813:
1.1.1.7 root 8814: The argument @var{size} will be a C variable of type @code{struct
8815: arg_data} which contains two fields, an integer named @code{constant}
8816: and an RTX named @code{var}. These together represent a size measured
8817: in bytes which is the sum of the integer and the RTX. Most of the
8818: time @code{var} is 0, which means that the size is simply the integer.
8819:
8820: The definition should be a C statement or compound statement
8821: which alters the variable supplied in whatever way you wish.
8822:
8823: Note that the value you leave in the variable @code{size} will
8824: ultimately be rounded up to a multiple of @code{STACK_BOUNDARY} bits.
8825:
8826: This macro is not fully implemented for machines which have push
8827: instructions (i.e., on which @code{PUSH_ROUNDING} is defined).
1.1.1.6 root 8828:
1.1 root 8829: @item RETURN_POPS_ARGS (@var{funtype})
8830: A C expression that should be 1 if a function pops its own arguments
8831: on returning, or 0 if the function pops no arguments and the caller
8832: must therefore pop them all after the function returns.
8833:
8834: @var{funtype} is a C variable whose value is a tree node that
8835: describes the function in question. Normally it is a node of type
8836: @code{FUNCTION_TYPE} that describes the data type of the function.
8837: From this it is possible to obtain the data types of the value and
8838: arguments (if known).
8839:
8840: When a call to a library function is being considered, @var{funtype}
8841: will contain an identifier node for the library function. Thus, if
8842: you need to distinguish among various library functions, you can do so
8843: by their names. Note that ``library function'' in this context means
8844: a function used to perform arithmetic, whose name is known specially
8845: in the compiler and was not mentioned in the C code being compiled.
8846:
8847: On the Vax, all functions always pop their arguments, so the
8848: definition of this macro is 1. On the 68000, using the standard
8849: calling convention, no functions pop their arguments, so the value of
8850: the macro is always 0 in this case. But an alternative calling
8851: convention is available in which functions that take a fixed number of
8852: arguments pop them but other functions (such as @code{printf}) pop
8853: nothing (the caller pops all). When this convention is in use,
8854: @var{funtype} is examined to determine whether a function takes a
8855: fixed number of arguments.
8856:
1.1.1.10 root 8857: When this macro returns nonzero, the macro @code{FRAME_POINTER_REQUIRED}
8858: must also return nonzero for proper operation.
8859:
1.1 root 8860: @item FUNCTION_VALUE (@var{valtype}, @var{func})
8861: A C expression to create an RTX representing the place where a
8862: function returns a value of data type @var{valtype}. @var{valtype} is
8863: a tree node representing a data type. Write @code{TYPE_MODE
8864: (@var{valtype})} to get the machine mode used to represent that type.
8865: On many machines, only the mode is relevant. (Actually, on most
8866: machines, scalar values are returned in the same place regardless of
8867: mode).@refill
8868:
8869: If the precise function being called is known, @var{func} is a tree
8870: node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
8871: pointer. This makes it possible to use a different value-returning
8872: convention for specific functions when all their calls are
8873: known.@refill
8874:
8875: @item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func})
8876: Define this macro if the target machine has ``register windows''
8877: so that the register in which a function returns its value is not
8878: the same as the one in which the caller sees the value.
8879:
8880: For such machines, @code{FUNCTION_VALUE} computes the register in
8881: which the caller will see the value, and
8882: @code{FUNCTION_OUTGOING_VALUE} should be defined in a similar fashion
8883: to tell the function where to put the value.@refill
8884:
8885: If @code{FUNCTION_OUTGOING_VALUE} is not defined,
8886: @code{FUNCTION_VALUE} serves both purposes.@refill
8887:
1.1.1.7 root 8888: @item RETURN_IN_MEMORY (@var{type})
8889: A C expression which can inhibit the returning of certain function
8890: values in registers, based on the type of value. A nonzero value says
8891: to return the function value in memory, just as large structures are
8892: always returned. Here @var{type} will be a C expression of type
8893: @code{tree}, representing the data type of the value.
8894:
8895: Note that values of mode @code{BLKmode} are returned in memory
8896: regardless of this macro. Also, the option @samp{-fpcc-struct-return}
8897: takes effect regardless of this macro. On most systems, it is
8898: possible to leave the macro undefined; this causes a default
8899: definition to be used, whose value is the constant 0.
8900:
1.1 root 8901: @item LIBCALL_VALUE (@var{mode})
8902: A C expression to create an RTX representing the place where a library
8903: function returns a value of mode @var{mode}. If the precise function
8904: being called is known, @var{func} is a tree node
8905: (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
8906: pointer. This makes it possible to use a different value-returning
8907: convention for specific functions when all their calls are
8908: known.@refill
8909:
8910: Note that ``library function'' in this context means a compiler
8911: support routine, used to perform arithmetic, whose name is known
8912: specially by the compiler and was not mentioned in the C code being
8913: compiled.
8914:
8915: @item FUNCTION_VALUE_REGNO_P (@var{regno})
8916: A C expression that is nonzero if @var{regno} is the number of a hard
8917: register in which the values of called function may come back.
8918:
8919: A register whose use for returning values is limited to serving as the
8920: second of a pair (for a value of type @code{double}, say) need not be
8921: recognized by this macro. So for most machines, this definition
8922: suffices:
8923:
8924: @example
8925: #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
8926: @end example
8927:
8928: If the machine has register windows, so that the caller and the called
8929: function use different registers for the return value, this macro
8930: should recognize only the caller's register numbers.
8931:
8932: @item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
8933: A C expression that controls whether a function argument is passed
8934: in a register, and which register.
8935:
8936: The arguments are @var{cum}, which summarizes all the previous
8937: arguments; @var{mode}, the machine mode of the argument; @var{type},
8938: the data type of the argument as a tree node or 0 if that is not known
8939: (which happens for C support library functions); and @var{named},
8940: which is 1 for an ordinary argument and 0 for nameless arguments that
1.1.1.8 root 8941: correspond to @samp{@dots{}} in the called function's prototype.
1.1 root 8942:
1.1.1.8 root 8943: The value of the expression should either be a @code{reg} RTX for the
1.1 root 8944: hard register in which to pass the argument, or zero to pass the
8945: argument on the stack.
8946:
8947: For the Vax and 68000, where normally all arguments are pushed, zero
8948: suffices as a definition.
8949:
1.1.1.8 root 8950: The usual way to make the ANSI library @file{stdarg.h} work on a machine
8951: where some arguments are usually passed in registers, is to cause
8952: nameless arguments to be passed on the stack instead. This is done
8953: by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0.
8954:
1.1 root 8955: @item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
8956: Define this macro if the target machine has ``register windows'', so
8957: that the register in which a function sees an arguments is not
8958: necessarily the same as the one in which the caller passed the
8959: argument.
8960:
8961: For such machines, @code{FUNCTION_ARG} computes the register in which
8962: the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should
8963: be defined in a similar fashion to tell the function being called
8964: where the arguments will arrive.
8965:
8966: If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG}
8967: serves both purposes.@refill
8968:
8969: @item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named})
8970: A C expression for the number of words, at the beginning of an
8971: argument, must be put in registers. The value must be zero for
8972: arguments that are passed entirely in registers or that are entirely
8973: pushed on the stack.
8974:
8975: On some machines, certain arguments must be passed partially in
8976: registers and partially in memory. On these machines, typically the
8977: first @var{n} words of arguments are passed in registers, and the rest
8978: on the stack. If a multi-word argument (a @code{double} or a
8979: structure) crosses that boundary, its first few words must be passed
8980: in registers and the rest must be pushed. This macro tells the
8981: compiler when this occurs, and how many of the words should go in
8982: registers.
8983:
8984: @code{FUNCTION_ARG} for these arguments should return the first
8985: register to be used by the caller for this argument; likewise
8986: @code{FUNCTION_INCOMING_ARG}, for the called function.
8987:
8988: @item CUMULATIVE_ARGS
8989: A C type for declaring a variable that is used as the first argument
8990: of @code{FUNCTION_ARG} and other related values. For some target
8991: machines, the type @code{int} suffices and can hold the number of
8992: bytes of argument so far.
8993:
8994: @item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype})
8995: A C statement (sans semicolon) for initializing the variable @var{cum}
8996: for the state at the beginning of the argument list. The variable has
8997: type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node
8998: for the data type of the function which will receive the args, or 0
8999: if the args are to a compiler support library function.
9000:
9001: @item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named})
1.1.1.7 root 9002: A C statement (sans semicolon) to update the summarizer variable
9003: @var{cum} to advance past an argument in the argument list. The
9004: values @var{mode}, @var{type} and @var{named} describe that argument.
9005: Once this is done, the variable @var{cum} is suitable for analyzing
9006: the @emph{following} argument with @code{FUNCTION_ARG}, etc.@refill
1.1 root 9007:
9008: @item FUNCTION_ARG_REGNO_P (@var{regno})
9009: A C expression that is nonzero if @var{regno} is the number of a hard
9010: register in which function arguments are sometimes passed. This does
9011: @emph{not} include implicit arguments such as the static chain and
9012: the structure-value address. On many machines, no registers can be
9013: used for this purpose since all function arguments are pushed on the
9014: stack.
9015:
9016: @item FUNCTION_ARG_PADDING (@var{mode}, @var{size})
9017: If defined, a C expression which determines whether, and in which direction,
9018: to pad out an argument with extra space. The value should be of type
9019: @code{enum direction}: either @code{upward} to pad above the argument,
9020: @code{downward} to pad below, or @code{none} to inhibit padding.
9021:
9022: The argument @var{size} is an RTX which describes the size of the
9023: argument, in bytes. It should be used only if @var{mode} is
9024: @code{BLKmode}. Otherwise, @var{size} is 0.
9025:
9026: This macro does not control the @emph{amount} of padding; that is
9027: always just enough to reach the next multiple of @code{PARM_BOUNDARY}.
9028:
9029: This macro has a default definition which is right for most systems.
9030: For little-endian machines, the default is to pad upward. For
9031: big-endian machines, the default is to pad downward for an argument of
9032: constant size shorter than an @code{int}, and upward otherwise.
9033:
9034: @item FUNCTION_PROLOGUE (@var{file}, @var{size})
9035: A C compound statement that outputs the assembler code for entry to a
9036: function. The prologue is responsible for setting up the stack frame,
9037: initializing the frame pointer register, saving registers that must be
9038: saved, and allocating @var{size} additional bytes of storage for the
9039: local variables. @var{size} is an integer. @var{file} is a stdio
9040: stream to which the assembler code should be output.
9041:
9042: The label for the beginning of the function need not be output by this
9043: macro. That has already been done when the macro is run.
9044:
9045: To determine which registers to save, the macro can refer to the array
9046: @code{regs_ever_live}: element @var{r} is nonzero if hard register
9047: @var{r} is used anywhere within the function. This implies the
9048: function prologue should save register @var{r}, but not if it is one
9049: of the call-used registers.
9050:
9051: On machines where functions may or may not have frame-pointers, the
9052: function entry code must vary accordingly; it must set up the frame
9053: pointer if one is wanted, and not otherwise. To determine whether a
9054: frame pointer is in wanted, the macro can refer to the variable
9055: @code{frame_pointer_needed}. The variable's value will be 1 at run
9056: time in a function that needs a frame pointer.
9057:
1.1.1.10 root 9058: On machines where an argument may be passed partly in registers and
9059: partly in memory, this macro must examine the variable
1.1.1.8 root 9060: @code{current_function_pretend_args_size}, and allocate that many bytes
9061: of uninitialized space on the stack just underneath the first argument
9062: arriving on the stack. (This may not be at the very end of the stack,
9063: if the calling sequence has pushed anything else since pushing the stack
9064: arguments. But usually, on such machines, nothing else has been pushed
9065: yet, because the function prologue itself does all the pushing.)
9066:
1.1 root 9067: @item FUNCTION_PROFILER (@var{file}, @var{labelno})
9068: A C statement or compound statement to output to @var{file} some
9069: assembler code to call the profiling subroutine @code{mcount}.
9070: Before calling, the assembler code must load the address of a
9071: counter variable into a register where @code{mcount} expects to
9072: find the address. The name of this variable is @samp{LP} followed
9073: by the number @var{labelno}, so you would generate the name using
9074: @samp{LP%d} in a @code{fprintf}.
9075:
9076: The details of how the address should be passed to @code{mcount} are
9077: determined by your operating system environment, not by GNU CC. To
9078: figure them out, compile a small program for profiling using the
9079: system's installed C compiler and look at the assembler code that
9080: results.
9081:
1.1.1.6 root 9082: @item FUNCTION_BLOCK_PROFILER (@var{file}, @var{labelno})
9083: A C statement or compound statement to output to @var{file} some
9084: assembler code to initialize basic-block profiling for the current
9085: object module. This code should call the subroutine
9086: @code{__bb_init_func} once per object module, passing it as its sole
9087: argument the address of a block allocated in the object module.
9088:
9089: The name of the block is a local symbol made with this statement:
9090:
9091: @example
9092: ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 0);
9093: @end example
9094:
9095: Of course, since you are writing the definition of
9096: @code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you
9097: can take a short cut in the definition of this macro and use the name
9098: that you know will result.
9099:
9100: The first word of this block is a flag which will be nonzero if the
9101: object module has already been initialized. So test this word first,
9102: and do not call @code{__bb_init_func} if the flag is nonzero.
9103:
9104: @item BLOCK_PROFILER (@var{file}, @var{blockno})
9105: A C statement or compound statement to increment the count associated
9106: with the basic block number @var{blockno}. Basic blocks are numbered
9107: separately from zero within each compilation. The count associated
9108: with block number @var{blockno} is at index @var{blockno} in a vector
9109: of words; the name of this array is a local symbol made with this
9110: statement:
9111:
9112: @example
9113: ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 2);
9114: @end example
9115:
9116: Of course, since you are writing the definition of
9117: @code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you
9118: can take a short cut in the definition of this macro and use the name
9119: that you know will result.
9120:
1.1.1.10 root 9121: @item EXIT_IGNORE_STACK
1.1 root 9122: Define this macro as a C expression that is nonzero if the return
9123: instruction or the function epilogue ignores the value of the stack
9124: pointer; in other words, if it is safe to delete an instruction to
9125: adjust the stack pointer before a return from the function.
9126:
1.1.1.8 root 9127: Note that this macro's value is relevant only for functions for which
9128: frame pointers are maintained. It is never safe to delete a final
9129: stack adjustment in a function that has no frame pointer, and the
1.1.1.10 root 9130: compiler knows this regardless of @code{EXIT_IGNORE_STACK}.
1.1 root 9131:
9132: @item FUNCTION_EPILOGUE (@var{file}, @var{size})
9133: A C compound statement that outputs the assembler code for exit from a
9134: function. The epilogue is responsible for restoring the saved
9135: registers and stack pointer to their values when the function was
9136: called, and returning control to the caller. This macro takes the
9137: same arguments as the macro @code{FUNCTION_PROLOGUE}, and the
9138: registers to restore are determined from @code{regs_ever_live} and
9139: @code{CALL_USED_REGISTERS} in the same way.
9140:
9141: On some machines, there is a single instruction that does all the work
9142: of returning from the function. On these machines, give that
9143: instruction the name @samp{return} and do not define the macro
9144: @code{FUNCTION_EPILOGUE} at all.
9145:
9146: Do not define a pattern named @samp{return} if you want the
9147: @code{FUNCTION_EPILOGUE} to be used. If you want the target switches
9148: to control whether return instructions or epilogues are used, define a
9149: @samp{return} pattern with a validity condition that tests the target
9150: switches appropriately. If the @samp{return} pattern's validity
9151: condition is false, epilogues will be used.
9152:
9153: On machines where functions may or may not have frame-pointers, the
9154: function exit code must vary accordingly. Sometimes the code for
9155: these two cases is completely different. To determine whether a frame
9156: pointer is in wanted, the macro can refer to the variable
9157: @code{frame_pointer_needed}. The variable's value will be 1 at run
9158: time in a function that needs a frame pointer.
9159:
9160: On some machines, some functions pop their arguments on exit while
9161: others leave that for the caller to do. For example, the 68020 when
9162: given @samp{-mrtd} pops arguments in functions that take a fixed
9163: number of arguments.
9164:
9165: Your definition of the macro @code{RETURN_POPS_ARGS} decides which
9166: functions pop their own arguments. @code{FUNCTION_EPILOGUE} needs to
9167: know what was decided. The variable @code{current_function_pops_args}
9168: is nonzero if the function should pop its own arguments. If so, use
9169: the variable @code{current_function_args_size} as the number of bytes
9170: to pop.
9171:
9172: @item FIX_FRAME_POINTER_ADDRESS (@var{addr}, @var{depth})
9173: A C compound statement to alter a memory address that uses the frame
9174: pointer register so that it uses the stack pointer register instead.
9175: This must be done in the instructions that load parameter values into
9176: registers, when the reload pass determines that a frame pointer is not
9177: necessary for the function. @var{addr} will be a C variable name, and
9178: the updated address should be stored in that variable. @var{depth}
9179: will be the current depth of stack temporaries (number of bytes of
9180: arguments currently pushed). The change in offset between a
9181: frame-pointer-relative address and a stack-pointer-relative address
9182: must include @var{depth}.
9183:
9184: Even if your machine description specifies there will always be a
9185: frame pointer in the frame pointer register, you must still define
9186: @code{FIX_FRAME_POINTER_ADDRESS}, but the definition will never be
9187: executed at run time, so it may be empty.
1.1.1.8 root 9188:
9189: @item LONGJMP_RESTORE_FROM_STACK
9190: Define this macro if the @code{longjmp} function restores registers
9191: from the stack frames, rather than from those saved specifically by
9192: @code{setjmp}. Certain quantities must not be kept in registers
9193: across a call to @code{setjmp} on such machines.
1.1 root 9194: @end table
9195:
1.1.1.12 root 9196: @node Library Calls, Addressing Modes, Stack Layout, Machine Macros
9197: @section Implicit Use of Library Routines
1.1 root 9198:
9199: @table @code
1.1.1.5 root 9200: @item MULSI3_LIBCALL
9201: A C string constant giving the name of the function to call for
9202: multiplication of one signed full-word by another. If you do not
9203: define this macro, the default name is used, which is @code{__mulsi3},
9204: a function defined in @file{gnulib}.
9205:
9206: @item UMULSI3_LIBCALL
9207: A C string constant giving the name of the function to call for
9208: multiplication of one unsigned full-word by another. If you do not
9209: define this macro, the default name is used, which is
9210: @code{__umulsi3}, a function defined in @file{gnulib}.
9211:
9212: @item DIVSI3_LIBCALL
9213: A C string constant giving the name of the function to call for
9214: division of one signed full-word by another. If you do not define
9215: this macro, the default name is used, which is @code{__divsi3}, a
9216: function defined in @file{gnulib}.
9217:
1.1 root 9218: @item UDIVSI3_LIBCALL
9219: A C string constant giving the name of the function to call for
1.1.1.5 root 9220: division of one unsigned full-word by another. If you do not define
9221: this macro, the default name is used, which is @code{__udivsi3}, a
9222: function defined in @file{gnulib}.
9223:
9224: @item MODSI3_LIBCALL
9225: A C string constant giving the name of the function to call for the
9226: remainder in division of one signed full-word by another. If you do
9227: not define this macro, the default name is used, which is
9228: @code{__modsi3}, a function defined in @file{gnulib}.
1.1 root 9229:
9230: @item UMODSI3_LIBCALL
9231: A C string constant giving the name of the function to call for the
1.1.1.5 root 9232: remainder in division of one unsigned full-word by another. If you do
9233: not define this macro, the default name is used, which is
9234: @code{__umodsi3}, a function defined in @file{gnulib}.
1.1 root 9235:
9236: @item TARGET_MEM_FUNCTIONS
9237: Define this macro if GNU CC should generate calls to the System V
9238: (and ANSI C) library functions @code{memcpy} and @code{memset}
9239: rather than the BSD functions @code{bcopy} and @code{bzero}.
1.1.1.12 root 9240:
9241: @item GNULIB_NEEDS_DOUBLE
9242: Define this macro if only @code{float} arguments cannot be passed to
9243: library routines (so they must be converted to @code{double}). This
9244: macro affects both how library calls are generated and how the library
9245: routines in @file{gnulib.c} accept their arguments. It is useful on
9246: machines where floating and fixed point arguments are passed
9247: differently, such as the i860.
1.1 root 9248: @end table
9249:
1.1.1.12 root 9250: @node Addressing Modes, Delayed Branch, Library Calls, Machine Macros
1.1 root 9251: @section Addressing Modes
9252:
9253: @table @code
9254: @item HAVE_POST_INCREMENT
9255: Define this macro if the machine supports post-increment addressing.
9256:
9257: @item HAVE_PRE_INCREMENT
9258: @itemx HAVE_POST_DECREMENT
9259: @itemx HAVE_PRE_DECREMENT
9260: Similar for other kinds of addressing.
9261:
9262: @item CONSTANT_ADDRESS_P (@var{x})
9263: A C expression that is 1 if the RTX @var{x} is a constant whose value
9264: is an integer. This includes integers whose values are not explicitly
1.1.1.8 root 9265: known, such as @code{symbol_ref} and @code{label_ref} expressions and
9266: @code{const} arithmetic expressions.
1.1 root 9267:
9268: On most machines, this can be defined as @code{CONSTANT_P (@var{x})},
9269: but a few machines are more restrictive in which constant addresses
9270: are supported.
9271:
9272: @item MAX_REGS_PER_ADDRESS
9273: A number, the maximum number of registers that can appear in a valid
1.1.1.10 root 9274: memory address. Note that it is up to you to specify a value equal to
9275: the maximum number that @code{go_if_legitimate_address} would ever
9276: accept.
1.1 root 9277:
9278: @item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label})
9279: A C compound statement with a conditional @code{goto @var{label};}
9280: executed if @var{x} (an RTX) is a legitimate memory address on the
9281: target machine for a memory operand of mode @var{mode}.
9282:
9283: It usually pays to define several simpler macros to serve as
9284: subroutines for this one. Otherwise it may be too complicated to
9285: understand.
9286:
9287: This macro must exist in two variants: a strict variant and a
9288: non-strict one. The strict variant is used in the reload pass. It
9289: must be defined so that any pseudo-register that has not been
9290: allocated a hard register is considered a memory reference. In
9291: contexts where some kind of register is required, a pseudo-register
9292: with no hard register must be rejected.
9293:
9294: The non-strict variant is used in other passes. It must be defined to
9295: accept all pseudo-registers in every context where some kind of
9296: register is required.
9297:
9298: Compiler source files that want to use the strict variant of this
9299: macro define the macro @code{REG_OK_STRICT}. You should use an
9300: @code{#ifdef REG_OK_STRICT} conditional to define the strict variant
9301: in that case and the non-strict variant otherwise.
9302:
9303: Typically among the subroutines used to define
9304: @code{GO_IF_LEGITIMATE_ADDRESS} are subroutines to check for
9305: acceptable registers for various purposes (one for base registers, one
9306: for index registers, and so on). Then only these subroutine macros
9307: need have two variants; the higher levels of macros may be the same
9308: whether strict or not.@refill
9309:
1.1.1.8 root 9310: Normally, constant addresses which are the sum of a @code{symbol_ref}
9311: and an integer are stored inside a @code{const} RTX to mark them as
9312: constant. Therefore, there is no need to recognize such sums as
9313: legitimate addresses.
9314:
9315: Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant
9316: sums that are not marked with @code{const}. It assumes that a naked
9317: @code{plus} indicates indexing. If so, then you @emph{must} reject such
9318: naked constant sums as illegitimate addresses, so that none of them will
9319: be given to @code{PRINT_OPERAND_ADDRESS}.@refill
9320:
1.1 root 9321: @item REG_OK_FOR_BASE_P (@var{x})
1.1.1.5 root 9322: A C expression that is nonzero if @var{x} (assumed to be a @code{reg}
1.1 root 9323: RTX) is valid for use as a base register. For hard registers, it
9324: should always accept those which the hardware permits and reject the
9325: others. Whether the macro accepts or rejects pseudo registers must be
9326: controlled by @code{REG_OK_STRICT} as described above. This usually
9327: requires two variant definitions, of which @code{REG_OK_STRICT}
9328: controls the one actually used.
9329:
9330: @item REG_OK_FOR_INDEX_P (@var{x})
1.1.1.5 root 9331: A C expression that is nonzero if @var{x} (assumed to be a @code{reg}
1.1 root 9332: RTX) is valid for use as an index register.
9333:
9334: The difference between an index register and a base register is that
9335: the index register may be scaled. If an address involves the sum of
9336: two registers, neither one of them scaled, then either one may be
9337: labeled the ``base'' and the other the ``index''; but whichever
9338: labeling is used must fit the machine's constraints of which registers
9339: may serve in each capacity. The compiler will try both labelings,
9340: looking for one that is valid, and will reload one or both registers
9341: only if neither labeling works.
9342:
9343: @item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win})
9344: A C compound statement that attempts to replace @var{x} with a valid
9345: memory address for an operand of mode @var{mode}. @var{win} will be a
9346: C statement label elsewhere in the code; the macro definition may use
9347:
9348: @example
9349: GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win});
9350: @end example
9351:
9352: @noindent
9353: to avoid further processing if the address has become legitimate.
9354:
9355: @var{x} will always be the result of a call to @code{break_out_memory_refs},
9356: and @var{oldx} will be the operand that was given to that function to produce
9357: @var{x}.
9358:
9359: The code generated by this macro should not alter the substructure of
9360: @var{x}. If it transforms @var{x} into a more legitimate form, it
9361: should assign @var{x} (which will always be a C variable) a new value.
9362:
9363: It is not necessary for this macro to come up with a legitimate
9364: address. The compiler has standard ways of doing so in all cases. In
9365: fact, it is safe for this macro to do nothing. But often a
9366: machine-dependent strategy can generate better code.
9367:
9368: @item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label})
9369: A C statement or compound statement with a conditional @code{goto
9370: @var{label};} executed if memory address @var{x} (an RTX) can have
9371: different meanings depending on the machine mode of the memory
9372: reference it is used for.
9373:
9374: Autoincrement and autodecrement addresses typically have mode-dependent
9375: effects because the amount of the increment or decrement is the size
9376: of the operand being addressed. Some machines have other mode-dependent
9377: addresses. Many RISC machines have no mode-dependent addresses.
9378:
9379: You may assume that @var{addr} is a valid address for the machine.
9380:
9381: @item LEGITIMATE_CONSTANT_P (@var{x})
9382: A C expression that is nonzero if @var{x} is a legitimate constant for
9383: an immediate operand on the target machine. You can assume that
1.1.1.8 root 9384: either @var{x} is a @code{const_double} or it satisfies
1.1 root 9385: @code{CONSTANT_P}, so you need not check these things. In fact,
9386: @samp{1} is a suitable definition for this macro on machines where any
1.1.1.8 root 9387: @code{const_double} is valid and anything @code{CONSTANT_P} is valid.@refill
9388: @end table
9389:
9390: @node Delayed Branch, Condition Code, Addressing Modes, Machine Macros
9391: @section Parameters for Delayed Branch Optimization
9392:
9393: @table @code
9394: @item HAVE_DELAYED_BRANCH
9395: Define this macro if the target machine has delayed branches, that is,
9396: a branch does not take effect immediately, and the actual branch
9397: instruction may be followed by one or more instructions that will be
9398: issued before the PC is actually changed.
9399:
9400: If defined, this allows a special scheduling pass to be run after the
9401: second jump optimization to attempt to reorder instructions to exploit
9402: this. Defining this macro also requires the definition of certain
9403: other macros described below.
9404:
9405: @item DBR_SLOTS_AFTER (@var{insn})
9406: This macro must be defined if @code{HAVE_DELAYED_BRANCH} is defined.
9407: Its definition should be a C expression returning the number of
9408: available delay slots following the instruction(s) output by the
9409: pattern for @var{insn}. The definition of ``slot'' is
9410: machine-dependent, and may denote instructions, bytes, or whatever.
9411:
9412: @item DBR_INSN_SLOTS (@var{insn})
9413: This macro must be defined if @code{HAVE_DELAYED_BRANCH} is defined.
9414: It should be a C expression returning the number of slots (typically
9415: the number of machine instructions) consumed by @var{insn}.
9416:
9417: You may assume that @var{insn} is truly an insn, not a note, label,
9418: barrier, dispatch table, @code{use}, or @code{clobber}.
9419:
9420: @item DBR_INSN_ELIGIBLE_P (@var{insn}, @var{dinsn})
9421: A C expression whose value is non-zero if it is legitimate to put
9422: @var{insn} in the delay slot following @var{dinsn}.
9423:
9424: You do not need to take account of data flow considerations in the
9425: definition of this macro, because the delayed branch optimizer always
9426: does that. This macro is needed only when certain insns may not be
9427: placed in certain delay slots for reasons not evident from the RTL
9428: expressions themselves. If there are no such problems, you don't need
9429: to define this macro.
9430:
9431: You may assume that @var{insn} is truly an insn, not a note, label,
9432: barrier, dispatch table, @code{use}, or @code{clobber}. You may
9433: assume that @var{dinsn} is a jump insn with a delay slot.
9434:
9435: @item DBR_OUTPUT_SEQEND(@var{file})
9436: A C statement, to be executed after all slot-filler instructions have
9437: been output. If necessary, call @code{dbr_sequence_length} to
9438: determine the number of slots filled in a sequence (zero if not
9439: currently outputting a sequence), to decide how many no-ops to output,
9440: or whatever.
9441:
9442: Don't define this macro if it has nothing to do, but it is helpful in
9443: reading assembly output if the extent of the delay sequence is made
9444: explicit (e.g. with white space).
9445:
9446: Note that output routines for instructions with delay slots must be
9447: prepared to deal with not being output as part of a sequence (i.e.
9448: when the scheduling pass is not run, or when no slot fillers could be
9449: found.) The variable @code{final_sequence} is null when not
9450: processing a sequence, otherwise it contains the @code{sequence} rtx
9451: being output.
1.1 root 9452: @end table
9453:
1.1.1.9 root 9454: @node Condition Code, Cross-compilation, Delayed Branch, Machine Macros
1.1.1.8 root 9455: @section Condition Code Information
9456:
9457: The file @file{conditions.h} defines a variable @code{cc_status} to
9458: describe how the condition code was computed (in case the interpretation of
9459: the condition code depends on the instruction that it was set by). This
9460: variable contains the RTL expressions on which the condition code is
9461: currently based, and several standard flags.
9462:
9463: Sometimes additional machine-specific flags must be defined in the machine
9464: description header file. It can also add additional machine-specific
9465: information by defining @code{CC_STATUS_MDEP}.
9466:
9467: @table @code
9468: @item CC_STATUS_MDEP
9469: C code for a data type which is used for declaring the @code{mdep}
9470: component of @code{cc_status}. It defaults to @code{int}.
9471:
9472: @item CC_STATUS_MDEP_INIT
1.1.1.9 root 9473: A C expression to initialize the @code{mdep} field to ``empty''.
9474: The default definition does nothing, since most machines don't use
9475: the field anyway. If you want to use the field, you should probably
9476: define this macro to initialize it.
1.1.1.8 root 9477:
9478: @item NOTICE_UPDATE_CC (@var{exp}, @var{insn})
9479: A C compound statement to set the components of @code{cc_status}
9480: appropriately for an insn @var{insn} whose body is @var{exp}. It is
9481: this macro's responsibility to recognize insns that set the condition
9482: code as a byproduct of other activity as well as those that explicitly
9483: set @code{(cc0)}.
9484:
9485: If there are insn that do not set the condition code but do alter
9486: other machine registers, this macro must check to see whether they
9487: invalidate the expressions that the condition code is recorded as
9488: reflecting. For example, on the 68000, insns that store in address
9489: registers do not set the condition code, which means that usually
9490: @code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such
9491: insns. But suppose that the previous insn set the condition code
9492: based on location @samp{a4@@(102)} and the current insn stores a new
9493: value in @samp{a4}. Although the condition code is not changed by
9494: this, it will no longer be true that it reflects the contents of
9495: @samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter
9496: @code{cc_status} in this case to say that nothing is known about the
9497: condition code value.
9498:
9499: The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal
9500: with the results of peephole optimization: insns whose patterns are
9501: @code{parallel} RTXs containing various @code{reg}, @code{mem} or
9502: constants which are just the operands. The RTL structure of these
9503: insns is not sufficient to indicate what the insns actually do. What
9504: @code{NOTICE_UPDATE_CC} should do when it sees one is just to run
9505: @code{CC_STATUS_INIT}.
9506: @end table
9507:
9508: @node Cross-compilation, Misc, Condition Code, Machine Macros
1.1.1.5 root 9509: @section Cross Compilation and Floating-Point Format
9510:
1.1.1.9 root 9511: While all modern machines use 2's complement representation for integers,
1.1.1.5 root 9512: there are a variety of representations for floating point numbers. This
9513: means that in a cross-compiler the representation of floating point numbers
9514: in the compiled program may be different from that used in the machine
9515: doing the compilation.
9516:
9517: Because different representation systems may offer different amounts of
9518: range and precision, the cross compiler cannot safely use the host
9519: machine's floating point arithmetic. Therefore, floating point constants
9520: must be represented in the target machine's format. This means that the
9521: cross compiler cannot use @code{atof} to parse a floating point constant;
9522: it must have its own special routine to use instead. Also, constant
9523: folding must emulate the target machine's arithmetic (or must not be done
9524: at all).
9525:
9526: The macros in the following table should be defined only if you are cross
9527: compiling between different floating point formats.
9528:
9529: Otherwise, don't define them. Then default definitions will be set up which
9530: use @code{double} as the data type, @code{==} to test for equality, etc.
9531:
9532: You don't need to worry about how many times you use an operand of any
9533: of these macros. The compiler never uses operands which have side effects.
9534:
9535: @table @code
9536: @item REAL_VALUE_TYPE
9537: A macro for the C data type to be used to hold a floating point value
9538: in the target machine's format. Typically this would be a
9539: @code{struct} containing an array of @code{int}.
9540:
9541: @item REAL_VALUES_EQUAL (@var{x}, @var{y})
9542: A macro for a C expression which compares for equality the two values,
9543: @var{x} and @var{y}, both of type @code{REAL_VALUE_TYPE}.
9544:
9545: @item REAL_VALUES_LESS (@var{x}, @var{y})
9546: A macro for a C expression which tests whether @var{x} is less than
9547: @var{y}, both values being of type @code{REAL_VALUE_TYPE} and
9548: interpreted as floating point numbers in the target machine's
9549: representation.
9550:
9551: @item REAL_VALUE_LDEXP (@var{x}, @var{scale})
9552: A macro for a C expression which performs the standard library
9553: function @code{ldexp}, but using the target machine's floating point
9554: representation. Both @var{x} and the value of the expression have
9555: type @code{REAL_VALUE_TYPE}. The second argument, @var{scale}, is an
9556: integer.
9557:
9558: @item REAL_VALUE_ATOF (@var{string})
9559: A macro for a C expression which converts @var{string}, an expression
9560: of type @code{char *}, into a floating point number in the target
9561: machine's representation. The value has type @code{REAL_VALUE_TYPE}.
9562: @end table
9563:
9564: Define the following additional macros if you want to make floating
9565: point constant folding work while cross compiling. If you don't
9566: define them, cross compilation is still possible, but constant folding
9567: will not happen for floating point values.
9568:
9569: @table @code
9570: @item REAL_ARITHMETIC (@var{output}, @var{code}, @var{x}, @var{y})
9571: A macro for a C statement which calculates an arithmetic operation of
9572: the two floating point values @var{x} and @var{y}, both of type
9573: @code{REAL_VALUE_TYPE} in the target machine's representation, to
9574: produce a result of the same type and representation which is stored
9575: in @var{output} (which will be a variable).
9576:
9577: The operation to be performed is specified by @var{code}, a tree code
9578: which will always be one of the following: @code{PLUS_EXPR},
9579: @code{MINUS_EXPR}, @code{MULT_EXPR}, @code{RDIV_EXPR},
9580: @code{MAX_EXPR}, @code{MIN_EXPR}.@refill
9581:
9582: The expansion of this macro is responsible for checking for overflow.
9583: If overflow happens, the macro expansion should execute the statement
9584: @code{return 0;}, which indicates the inability to perform the
9585: arithmetic operation requested.
9586:
9587: @item REAL_VALUE_NEGATE (@var{x})
9588: A macro for a C expression which returns the negative of the floating
9589: point value @var{x}. Both @var{x} and the value of the expression
9590: have type @code{REAL_VALUE_TYPE} and are in the target machine's
9591: floating point representation.
9592:
9593: There is no way for this macro to report overflow, since overflow
9594: can't happen in the negation operation.
9595:
9596: @item REAL_VALUE_TO_INT (@var{low}, @var{high}, @var{x})
9597: A macro for a C expression which converts a floating point value
9598: @var{x} into a double-precision integer which is then stored into
9599: @var{low} and @var{high}, two variables of type @var{int}.
9600:
9601: @item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high})
9602: A macro for a C expression which converts a double-precision integer
9603: found in @var{low} and @var{high}, two variables of type @var{int},
9604: into a floating point value which is then stored into @var{x}.
9605: @end table
9606:
1.1.1.8 root 9607: @node Misc, Assembler Format, Cross-compilation, Machine Macros
1.1 root 9608: @section Miscellaneous Parameters
9609:
9610: @table @code
9611: @item CASE_VECTOR_MODE
9612: An alias for a machine mode name. This is the machine mode that
9613: elements of a jump-table should have.
9614:
9615: @item CASE_VECTOR_PC_RELATIVE
9616: Define this macro if jump-tables should contain relative addresses.
9617:
9618: @item CASE_DROPS_THROUGH
9619: Define this if control falls through a @code{case} insn when the index
9620: value is out of range. This means the specified default-label is
9621: actually ignored by the @code{case} insn proper.
9622:
9623: @item IMPLICIT_FIX_EXPR
9624: An alias for a tree code that should be used by default for conversion
9625: of floating point values to fixed point. Normally,
9626: @code{FIX_ROUND_EXPR} is used.@refill
9627:
9628: @item FIXUNS_TRUNC_LIKE_FIX_TRUNC
9629: Define this macro if the same instructions that convert a floating
9630: point number to a signed fixed point number also convert validly to an
9631: unsigned one.
9632:
9633: @item EASY_DIV_EXPR
9634: An alias for a tree code that is the easiest kind of division to
9635: compile code for in the general case. It may be
9636: @code{TRUNC_DIV_EXPR}, @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or
9637: @code{ROUND_DIV_EXPR}. These four division operators differ in how
9638: they round the result to an integer. @code{EASY_DIV_EXPR} is used
9639: when it is permissible to use any of those kinds of division and the
9640: choice should be made on the basis of efficiency.@refill
9641:
9642: @item DEFAULT_SIGNED_CHAR
9643: An expression whose value is 1 or 0, according to whether the type
9644: @code{char} should be signed or unsigned by default. The user can
9645: always override this default with the options @samp{-fsigned-char}
9646: and @samp{-funsigned-char}.
9647:
9648: @item SCCS_DIRECTIVE
9649: Define this if the preprocessor should ignore @code{#sccs} directives
9650: and print no error message.
9651:
1.1.1.7 root 9652: @item HAVE_VPRINTF
9653: Define this if the library function @code{vprintf} is available on your
9654: system.
1.1 root 9655:
9656: @item MOVE_MAX
9657: The maximum number of bytes that a single instruction can move quickly
9658: from memory to memory.
9659:
9660: @item INT_TYPE_SIZE
9661: A C expression for the size in bits of the type @code{int} on the
1.1.1.8 root 9662: target machine. If you don't define this, the default is one word.
9663:
9664: @item SHORT_TYPE_SIZE
9665: A C expression for the size in bits of the type @code{short} on the
9666: target machine. If you don't define this, the default is half a word.
9667: (If this would be less than one storage unit, it is rounded up to one
9668: unit.)
9669:
9670: @item LONG_TYPE_SIZE
9671: A C expression for the size in bits of the type @code{long} on the
9672: target machine. If you don't define this, the default is one word.
9673:
9674: @item LONG_LONG_TYPE_SIZE
9675: A C expression for the size in bits of the type @code{long long} on the
9676: target machine. If you don't define this, the default is two
9677: words.
9678:
9679: @item CHAR_TYPE_SIZE
9680: A C expression for the size in bits of the type @code{char} on the
9681: target machine. If you don't define this, the default is one quarter
9682: of a word. (If this would be less than one storage unit, it is rounded up
9683: to one unit.)
9684:
9685: @item FLOAT_TYPE_SIZE
9686: A C expression for the size in bits of the type @code{float} on the
9687: target machine. If you don't define this, the default is one word.
9688:
9689: @item DOUBLE_TYPE_SIZE
9690: A C expression for the size in bits of the type @code{double} on the
9691: target machine. If you don't define this, the default is two
9692: words.
9693:
9694: @item LONG_DOUBLE_TYPE_SIZE
9695: A C expression for the size in bits of the type @code{long double} on
9696: the target machine. If you don't define this, the default is two
9697: words.
1.1 root 9698:
9699: @item SLOW_BYTE_ACCESS
9700: Define this macro as a C expression which is nonzero if accessing less
9701: than a word of memory (i.e. a @code{char} or a @code{short}) is slow
9702: (requires more than one instruction).
9703:
9704: @item SLOW_ZERO_EXTEND
9705: Define this macro if zero-extension (of a @code{char} or @code{short}
9706: to an @code{int}) can be done faster if the destination is a register
9707: that is known to be zero.
9708:
9709: If you define this macro, you must have instruction patterns that
9710: recognize RTL structures like this:
9711:
9712: @example
9713: (set (strict-low-part (subreg:QI (reg:SI @dots{}) 0)) @dots{})
9714: @end example
9715:
9716: @noindent
9717: and likewise for @code{HImode}.
9718:
9719: @item SHIFT_COUNT_TRUNCATED
9720: Define this macro if shift instructions ignore all but the lowest few
9721: bits of the shift count. It implies that a sign-extend or zero-extend
9722: instruction for the shift count can be omitted.
9723:
9724: @item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec})
9725: A C expression which is nonzero if on this machine it is safe to
9726: ``convert'' an integer of @var{inprec} bits to one of @var{outprec}
9727: bits (where @var{outprec} is smaller than @var{inprec}) by merely
9728: operating on it as if it had only @var{outprec} bits.
9729:
9730: On many machines, this expression can be 1.
9731:
9732: @item NO_FUNCTION_CSE
9733: Define this macro if it is as good or better to call a constant
9734: function address than to call an address kept in a register.
9735:
9736: @item PROMOTE_PROTOTYPES
9737: Define this macro if an argument declared as @code{char} or
9738: @code{short} in a prototype should actually be passed as an
9739: @code{int}. In addition to avoiding errors in certain cases of
9740: mismatch, it also makes for better code on certain machines.
9741:
9742: @item STORE_FLAG_VALUE
9743: A C expression for the value stored by a store-flag instruction
9744: (@code{s@var{cond}}) when the condition is true. This is usually 1 or
1.1.1.9 root 9745: -1; it is required to be an odd number or a negative number.
1.1 root 9746:
9747: Do not define @code{STORE_FLAG_VALUE} if the machine has no store-flag
9748: instructions.
9749:
9750: @item Pmode
9751: An alias for the machine mode for pointers. Normally the definition
9752: can be
9753:
9754: @example
9755: #define Pmode SImode
9756: @end example
9757:
9758: @item FUNCTION_MODE
9759: An alias for the machine mode used for memory references to functions
1.1.1.8 root 9760: being called, in @code{call} RTL expressions. On most machines this
1.1 root 9761: should be @code{QImode}.
9762:
9763: @item INSN_MACHINE_INFO
9764: This macro should expand into a C structure type to use for the
9765: machine-dependent info field specified with the optional last argument
1.1.1.8 root 9766: in @code{define_insn} and @code{define_peephole} patterns. For example,
9767: it might expand into @code{struct machine_info}; then it would be up
1.1 root 9768: to you to define this structure in the @file{tm.h} file.
9769:
9770: You do not need to define this macro if you do not write the optional
9771: last argument in any of the patterns in the machine description.
9772:
1.1.1.8 root 9773: @item DEFAULT_MACHINE_INFO
9774: This macro should expand into a C initializer to use to initialize
9775: the machine-dependent info for one insn pattern. It is used for patterns
9776: that do not specify the machine-dependent info.
9777:
9778: If you do not define this macro, zero is used.
9779:
1.1 root 9780: @item CONST_COSTS (@var{x}, @var{code})
9781: A part of a C @code{switch} statement that describes the relative
9782: costs of constant RTL expressions. It must contain @code{case} labels
1.1.1.8 root 9783: for expression codes @code{const_int}, @code{const}, @code{symbol_ref}, @code{label_ref}
9784: and @code{const_double}. Each case must ultimately reach a
1.1 root 9785: @code{return} statement to return the relative cost of the use of that
9786: kind of constant value in an expression. The cost may depend on the
9787: precise value of the constant, which is available for examination in
9788: @var{x}.
9789:
9790: @var{code} is the expression code---redundant, since it can be
9791: obtained with @code{GET_CODE (@var{x})}.
9792:
9793: @item DOLLARS_IN_IDENTIFIERS
9794: Define this to be nonzero if the character @samp{$} should be allowed
9795: by default in identifier names.
9796: @end table
9797:
1.1.1.8 root 9798: @node Assembler Format,, Misc, Machine Macros
1.1 root 9799: @section Output of Assembler Code
9800:
9801: @table @code
9802: @item ASM_SPEC
9803: A C string constant that tells the GNU CC driver program options to
9804: pass to the assembler. It can also specify how to translate options
9805: you give to GNU CC into options for GNU CC to pass to the assembler.
9806: See the file @file{tm-sun3.h} for an example of this.
9807:
9808: Do not define this macro if it does not need to do anything.
9809:
9810: @item LINK_SPEC
9811: A C string constant that tells the GNU CC driver program options to
9812: pass to the linker. It can also specify how to translate options you
9813: give to GNU CC into options for GNU CC to pass to the linker.
9814:
9815: Do not define this macro if it does not need to do anything.
9816:
9817: @item LIB_SPEC
9818: Another C string constant used much like @code{LINK_SPEC}. The difference
9819: between the two is that @code{LIBS_SPEC} is used at the end of the
9820: command given to the linker.
9821:
9822: If this macro is not defined, a default is provided that
9823: loads the standard C library from the usual place. See @file{gcc.c}.
9824:
1.1.1.12 root 9825: @item LIBG_SPEC
9826: Another C string constant used much like @code{LINK_SPEC}.
9827: This controls whether to link @file{libg.a} when debugging.
9828: Some systems expect this; others do not have any @file{libg.a}.
9829:
9830: If this macro is not defined, a default is provided that loads the
9831: @file{libg.a} provided @samp{-g} is specified. See @file{gcc.c}.
9832:
1.1 root 9833: @item STARTFILE_SPEC
9834: Another C string constant used much like @code{LINK_SPEC}. The
9835: difference between the two is that @code{STARTFILE_SPEC} is used at
9836: the very beginning of the command given to the linker.
9837:
9838: If this macro is not defined, a default is provided that loads the
9839: standard C startup file from the usual place. See @file{gcc.c}.
9840:
1.1.1.7 root 9841: @item STANDARD_EXEC_PREFIX
9842: Define this macro as a C string constant if you wish to override the
9843: standard choice of @file{/usr/local/lib/gcc-} as the default prefix to
9844: try when searching for the executable files of the compiler.
9845:
9846: The prefix specified by the @samp{-B} option, if any, is tried before
9847: the default prefix. After the default prefix, if the executable is
9848: not found that way, @file{/usr/lib/gcc-} is tried next; then the
9849: directories in your search path for shell commands are searched.
9850:
1.1.1.4 root 9851: @item STANDARD_STARTFILE_PREFIX
9852: Define this macro as a C string constant if you wish to override the
1.1.1.7 root 9853: standard choice of @file{/usr/local/lib/} as the default prefix to try
9854: when searching for startup files such as @file{crt0.o}.
9855:
9856: In this search, all the prefixes tried for executable files are tried
9857: first. Then comes the default startfile prefix specified by this
9858: macro, followed by the prefixes @file{/lib/} and @file{/usr/lib/} as
9859: last resorts.
1.1.1.4 root 9860:
1.1 root 9861: @item ASM_FILE_START (@var{stream})
9862: A C expression which outputs to the stdio stream @var{stream}
9863: some appropriate text to go at the start of an assembler file.
9864:
9865: Normally this macro is defined to output a line containing
9866: @samp{#NO_APP}, which is a comment that has no effect on most
9867: assemblers but tells the GNU assembler that it can save time by not
9868: checking for certain assembler constructs.
9869:
9870: On systems that use SDB, it is necessary to output certain commands;
9871: see @file{tm-attasm.h}.
9872:
1.1.1.8 root 9873: @item ASM_FILE_END (@var{stream})
9874: A C expression which outputs to the stdio stream @var{stream}
9875: some appropriate text to go at the end of an assembler file.
9876:
9877: If this macro is not defined, the default is to output nothing
9878: special at the end of the file. Most systems don't require any
9879: definition.
9880:
9881: On systems that use SDB, it is necessary to output certain commands;
9882: see @file{tm-attasm.h}.
9883:
9884: @item ASM_IDENTIFY_GCC (@var{file})
9885: A C statement to output assembler commands which will identify
9886: the object file as having been compiled with GNU CC (or another
9887: GNU compiler).
9888:
9889: If you don't define this macro, the string @samp{gcc_compiled.:}
9890: is output. This string is calculated to define a symbol which,
9891: on BSD systems, will never be defined for any other reason.
9892: GDB checks for the presence of this symbol when reading the
9893: symbol table of an executable.
9894:
9895: On non-BSD systems, you must arrange communication with GDB in
9896: some other fashion. If GDB is not used on your system, you can
9897: define this macro with an empty body.
9898:
1.1 root 9899: @item ASM_APP_ON
9900: A C string constant for text to be output before each @code{asm}
9901: statement or group of consecutive ones. Normally this is
9902: @code{"#APP"}, which is a comment that has no effect on most
9903: assemblers but tells the GNU assembler that it must check the lines
9904: that follow for all valid assembler constructs.
9905:
9906: @item ASM_APP_OFF
9907: A C string constant for text to be output after each @code{asm}
9908: statement or group of consecutive ones. Normally this is
9909: @code{"#NO_APP"}, which tells the GNU assembler to resume making the
9910: time-saving assumptions that are valid for ordinary compiler output.
9911:
9912: @item TEXT_SECTION_ASM_OP
9913: A C string constant for the assembler operation that should precede
9914: instructions and read-only data. Normally @code{".text"} is right.
9915:
9916: @item DATA_SECTION_ASM_OP
9917: A C string constant for the assembler operation to identify the
9918: following data as writable initialized data. Normally @code{".data"}
9919: is right.
9920:
1.1.1.8 root 9921: @item EXTRA_SECTIONS
9922: A list of names for sections other than the standard two, which are
9923: @code{in_text} and @code{in_data}. You need not define this macro
9924: on a system with no other sections (that GCC needs to use).
9925:
9926: @item EXTRA_SECTION_FUNCTIONS
9927: One or more functions to be defined in @file{varasm.c}. These
9928: functions should do jobs analogous to those of @code{text_section} and
9929: @code{data_section}, for your additional sections. Do not define this
9930: macro if you do not define @code{EXTRA_SECTIONS}.
9931:
9932: @item SELECT_SECTION (@var{exp})
9933: A C statement or statements to switch to the appropriate section for
9934: output of @var{exp}. You can assume that @var{exp} is either a
9935: @code{VAR_DECL} node or a constant of some sort. Select the section
9936: by calling @code{text_section} or one of the alternatives for other
9937: sections.
9938:
9939: Do not define this macro if you use only the standard two sections
9940: and put all read-only variables and constants in the text section.
9941:
9942: @item SELECT_RTX_SECTION (@var{mode}, @var{rtx})
9943: A C statement or statements to switch to the appropriate section for
9944: output of @var{rtx} in mode @var{mode}. You can assume that @var{rtx}
9945: is some kind of constant in RTL. The argument @var{mode} is redundant
9946: except in the case of a @code{const_int} rtx. Select the section by
9947: calling @code{text_section} or one of the alternatives for other
9948: sections.
9949:
9950: Do not define this macro if you use only the standard two sections and
9951: put all constants in the text section.
9952:
1.1 root 9953: @item REGISTER_NAMES
9954: A C initializer containing the assembler's names for the machine
9955: registers, each one as a C string constant. This is what translates
9956: register numbers in the compiler into assembler language.
9957:
9958: @item DBX_REGISTER_NUMBER (@var{regno})
9959: A C expression that returns the DBX register number for the compiler
9960: register number @var{regno}. In simple cases, the value of this
9961: expression may be @var{regno} itself. But sometimes there are some
9962: registers that the compiler knows about and DBX does not, or vice
9963: versa. In such cases, some register may need to have one number in
9964: the compiler and another for DBX.
9965:
9966: @item DBX_DEBUGGING_INFO
9967: Define this macro if GNU CC should produce debugging output for DBX
9968: in response to the @samp{-g} option.
9969:
9970: @item SDB_DEBUGGING_INFO
9971: Define this macro if GNU CC should produce debugging output for SDB
9972: in response to the @samp{-g} option.
9973:
9974: @item PUT_SDB_@var{op}
9975: Define these macros to override the assembler syntax for the special
9976: SDB assembler directives. See @file{sdbout.c} for a list of these
9977: macros and their arguments. If the standard syntax is used, you need
9978: not define them yourself.
9979:
9980: @item SDB_GENERATE_FAKE
9981: Define this macro to override the usual method of constructing a dummy
9982: name for anonymous structure and union types. See @file{sdbout.c} for
1.1.1.9 root 9983: more information.
1.1 root 9984:
9985: @item DBX_NO_XREFS
9986: Define this macro if DBX on your system does not support the construct
9987: @samp{xs@var{tagname}}. On some systems, this construct is used to
9988: describe a forward reference to a structure named @var{tagname}.
9989: On other systems, this construct is not supported at all.
9990:
9991: @item DBX_CONTIN_LENGTH
9992: A symbol name in DBX-format debugging information is normally
9993: continued (split into two separate @code{.stabs} directives) when it
9994: exceeds a certain length (by default, 80 characters). On some
9995: operating systems, DBX requires this splitting; on others, splitting
9996: must not be done. You can inhibit splitting by defining this macro
9997: with the value zero. You can override the default splitting-length by
9998: defining this macro as an expression for the length you desire.
9999:
10000: @item DBX_CONTIN_CHAR
10001: Normally continuation is indicated by adding a @samp{\} character to
10002: the end of a @code{.stabs} string when a continuation follows. To use
10003: a different character instead, define this macro as a character
10004: constant for the character you want to use. Do not define this macro
10005: if backslash is correct for your system.
10006:
1.1.1.8 root 10007: @item DBX_STATIC_STAB_DATA_SECTION
10008: Define this macro if it is necessary to go to the data section before
10009: outputting the @samp{.stabs} pseudo-op for a non-global static
10010: variable.
10011:
1.1 root 10012: @item ASM_OUTPUT_LABEL (@var{stream}, @var{name})
10013: A C statement (sans semicolon) to output to the stdio stream
1.1.1.8 root 10014: @var{stream} the assembler definition of a label named @var{name}.
10015: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
10016: output the name itself; before and after that, output the additional
1.1 root 10017: assembler syntax for defining the name, and a newline.
10018:
10019: @item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl})
10020: A C statement (sans semicolon) to output to the stdio stream
10021: @var{stream} any text necessary for declaring the name @var{name} of a
10022: function which is being defined. This macro is responsible for
10023: outputting the label definition (perhaps using
10024: @code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the
10025: @code{FUNCTION_DECL} tree node representing the function.
10026:
10027: If this macro is not defined, then the function name is defined in the
10028: usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
10029:
10030: @item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name})
10031: A C statement (sans semicolon) to output to the stdio stream
10032: @var{stream} some commands that will make the label @var{name} global;
10033: that is, available for reference from other files. Use the expression
10034: @code{assemble_name (@var{stream}, @var{name})} to output the name
10035: itself; before and after that, output the additional assembler syntax
10036: for making that name global, and a newline.
10037:
1.1.1.8 root 10038: @item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name})
1.1 root 10039: A C statement (sans semicolon) to output to the stdio stream
10040: @var{stream} any text necessary for declaring the name of an external
10041: symbol named @var{name} which is referenced in this compilation but
10042: not defined. The value of @var{decl} is the tree node for the
10043: declaration.
10044:
10045: This macro need not be defined if it does not need to output anything.
10046: The GNU assembler and most Unix assemblers don't require anything.
10047:
10048: @item ASM_OUTPUT_LABELREF (@var{stream}, @var{name})
1.1.1.8 root 10049: A C statement to output to the stdio stream @var{stream} a reference
10050: in assembler syntax to a label named @var{name}. The character
10051: @samp{_} should be added to the front of the name, if that is
10052: customary on your operating system, as it is in most Berkeley Unix
10053: systems. This macro is used in @code{assemble_name}.
1.1 root 10054:
10055: @item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num})
1.1.1.8 root 10056: A C statement to store into the string @var{string} a label whose name
10057: is made from the string @var{prefix} and the number @var{num}.
1.1 root 10058:
10059: This string, when output subsequently by @code{ASM_OUTPUT_LABELREF},
10060: should produce the same output that @code{ASM_OUTPUT_INTERNAL_LABEL}
10061: would produce with the same @var{prefix} and @var{num}.
10062:
10063: @item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num})
10064: A C statement to output to the stdio stream @var{stream} a label whose
10065: name is made from the string @var{prefix} and the number @var{num}.
10066: These labels are used for internal purposes, and there is no reason
10067: for them to appear in the symbol table of the object file. On many
10068: systems, the letter @samp{L} at the beginning of a label has this
10069: effect. The usual definition of this macro is as follows:
10070:
10071: @example
10072: fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num})
10073: @end example
10074:
10075: @item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table})
10076: Define this if the label before a jump-table needs to be output
10077: specially. The first three arguments are the same as for
10078: @code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the
1.1.1.8 root 10079: jump-table which follows (a @code{jump_insn} containing an
10080: @code{addr_vec} or @code{addr_diff_vec}).
1.1 root 10081:
10082: This feature is used on system V to output a @code{swbeg} statement
10083: for the table.
10084:
10085: If this macro is not defined, these labels are output with
10086: @code{ASM_OUTPUT_INTERNAL_LABEL}.
10087:
10088: @item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table})
1.1.1.8 root 10089: Define this if something special must be output at the end of a
10090: jump-table. The definition should be a C statement to be executed
10091: after the assembler code for the table is written. It should write
10092: the appropriate code to stdio stream @var{stream}. The argument
10093: @var{table} is the jump-table insn, and @var{num} is the label-number
10094: of the preceding label.
1.1 root 10095:
10096: If this macro is not defined, nothing special is output at the end of
10097: the jump-table.
10098:
1.1.1.4 root 10099: @item ASM_OUTPUT_ALIGN_CODE (@var{file})
10100: A C expression to output text to align the location counter in the way
10101: that is desirable at a point in the code that is reached only by
10102: jumping.
10103:
10104: This macro need not be defined if you don't want any special alignment
10105: to be done at such a time. Most machine descriptions do not currently
10106: define the macro.
10107:
1.1 root 10108: @item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number})
10109: A C expression to assign to @var{outvar} (which is a variable of type
10110: @code{char *}) a newly allocated string made from the string
10111: @var{name} and the number @var{number}, with some suitable punctuation
10112: added. Use @code{alloca} to get space for the string.
10113:
10114: This string will be used as the argument to @code{ASM_OUTPUT_LABELREF}
10115: to produce an assembler label for an internal static variable whose
10116: name is @var{name}. Therefore, the string must be such as to result
10117: in valid assembler code. The argument @var{number} is different each
10118: time this macro is executed; it prevents conflicts between
10119: similarly-named internal static variables in different scopes.
10120:
10121: Ideally this string should not be a valid C identifier, to prevent any
10122: conflict with the user's own symbols. Most assemblers allow periods
10123: or percent signs in assembler symbols; putting at least one of these
10124: between the name and the number will suffice.
10125:
10126: @item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno})
10127: A C expression to output to @var{stream} some assembler code
10128: which will push hard register number @var{regno} onto the stack.
10129: The code need not be optimal, since this macro is used only when
10130: profiling.
10131:
10132: @item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno})
10133: A C expression to output to @var{stream} some assembler code
10134: which will pop hard register number @var{regno} off of the stack.
10135: The code need not be optimal, since this macro is used only when
10136: profiling.
10137:
10138: @item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{value}, @var{rel})
10139: This macro should be provided on machines where the addresses
10140: in a dispatch table are relative to the table's own address.
10141:
10142: The definition should be a C statement to output to the stdio stream
10143: @var{stream} an assembler pseudo-instruction to generate a difference
10144: between two labels. @var{value} and @var{rel} are the numbers of two
10145: internal labels. The definitions of these labels are output using
10146: @code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same
10147: way here. For example,
10148:
10149: @example
10150: fprintf (@var{stream}, "\t.word L%d-L%d\n",
10151: @var{value}, @var{rel})
10152: @end example
10153:
10154: @item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value})
10155: This macro should be provided on machines where the addresses
10156: in a dispatch table are absolute.
10157:
10158: The definition should be a C statement to output to the stdio stream
10159: @var{stream} an assembler pseudo-instruction to generate a reference to
10160: a label. @var{value} is the number of an internal label whose
10161: definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}.
10162: For example,
10163:
10164: @example
10165: fprintf (@var{stream}, "\t.word L%d\n", @var{value})
10166: @end example
10167:
10168: @item ASM_OUTPUT_DOUBLE (@var{stream}, @var{value})
10169: A C statement to output to the stdio stream @var{stream} an assembler
10170: instruction to assemble a @code{double} constant whose value is
10171: @var{value}. @var{value} will be a C expression of type
10172: @code{double}.
10173:
10174: @item ASM_OUTPUT_FLOAT (@var{stream}, @var{value})
10175: A C statement to output to the stdio stream @var{stream} an assembler
10176: instruction to assemble a @code{float} constant whose value is
10177: @var{value}. @var{value} will be a C expression of type @code{float}.
10178:
10179: @item ASM_OUTPUT_INT (@var{stream}, @var{exp})
10180: @itemx ASM_OUTPUT_SHORT (@var{stream}, @var{exp})
10181: @itemx ASM_OUTPUT_CHAR (@var{stream}, @var{exp})
10182: A C statement to output to the stdio stream @var{stream} an assembler
10183: instruction to assemble a @code{int}, @code{short} or @code{char}
1.1.1.10 root 10184: constant whose value is @var{value}. The argument @var{exp} will be an
10185: RTL expression which represents a constant value. Use
10186: @samp{output_addr_const (@var{stream}, @var{exp})} to output this value
10187: as an assembler expression.@refill
1.1 root 10188:
1.1.1.8 root 10189: @item ASM_OUTPUT_DOUBLE_INT (@var{stream}, @var{exp})
10190: A C statement to output to the stdio stream @var{stream} an assembler
10191: instruction to assemble a @code{long long} constant whose value is
10192: @var{exp}. The argument @var{exp} will be an RTL expression which
10193: represents a constant value. It may be a @code{const_double} RTX,
10194: or it may be an ordinary single-precision constant. In the latter
10195: case, you should zero-extend it.
10196:
1.1 root 10197: @item ASM_OUTPUT_BYTE (@var{stream}, @var{value})
10198: A C statement to output to the stdio stream @var{stream} an assembler
10199: instruction to assemble a single byte containing the number @var{value}.
10200:
10201: @item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len})
10202: A C statement to output to the stdio stream @var{stream} an assembler
10203: instruction to assemble a string constant containing the @var{len}
10204: bytes at @var{ptr}. @var{ptr} will be a C expression of type
10205: @code{char *} and @var{len} a C expression of type @code{int}.
10206:
10207: If the assembler has a @code{.ascii} pseudo-op as found in the
10208: Berkeley Unix assembler, do not define the macro
10209: @code{ASM_OUTPUT_ASCII}.
10210:
10211: @item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes})
10212: A C statement to output to the stdio stream @var{stream} an assembler
10213: instruction to advance the location counter by @var{nbytes} bytes.
10214: @var{nbytes} will be a C expression of type @code{int}.
10215:
10216: @item ASM_OUTPUT_ALIGN (@var{stream}, @var{power})
10217: A C statement to output to the stdio stream @var{stream} an assembler
10218: instruction to advance the location counter to a multiple of 2 to the
10219: @var{power} bytes. @var{power} will be a C expression of type @code{int}.
10220:
1.1.1.7 root 10221: @item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded})
1.1 root 10222: A C statement (sans semicolon) to output to the stdio stream
1.1.1.7 root 10223: @var{stream} the assembler definition of a common-label named
10224: @var{name} whose size is @var{size} bytes. The variable @var{rounded}
10225: is the size rounded up to whatever alignment the caller wants.
10226:
10227: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
10228: output the name itself; before and after that, output the additional
10229: assembler syntax for defining the name, and a newline.
1.1 root 10230:
10231: This macro controls how the assembler definitions of uninitialized
10232: global variables are output.
10233:
1.1.1.7 root 10234: @item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded})
1.1 root 10235: A C statement (sans semicolon) to output to the stdio stream
10236: @var{stream} the assembler definition of a local-common-label named
1.1.1.7 root 10237: @var{name} whose size is @var{size} bytes. The variable @var{rounded}
10238: is the size rounded up to whatever alignment the caller wants.
10239:
10240: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
10241: output the name itself; before and after that, output the additional
10242: assembler syntax for defining the name, and a newline.
1.1 root 10243:
10244: This macro controls how the assembler definitions of uninitialized
10245: static variables are output.
10246:
1.1.1.8 root 10247: @item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name})
10248: A C statment to output DBX or SDB debugging information which indicates
10249: that filename @var{name} is the current source file to the stdio stream
10250: @var{stream}.
10251:
10252: This macro need not be defined if the standard form of debugging
10253: information for the debugger in use is appropriate.
10254:
1.1 root 10255: @item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line})
10256: A C statment to output DBX or SDB debugging information before code
10257: for line number @var{line} of the current source file to the
10258: stdio stream @var{stream}.
10259:
10260: This macro need not be defined if the standard form of debugging
10261: information for the debugger in use is appropriate.
10262:
10263: @item ASM_OUTPUT_IDENT (@var{stream}, @var{string})
10264: A C statement to output something to the assembler file to handle a
10265: @samp{#ident} directive containing the text @var{string}. If this
1.1.1.7 root 10266: macro is not defined, nothing is output for a @samp{#ident} directive.
1.1 root 10267:
10268: @item TARGET_BELL
10269: A C constant expression for the integer value for escape sequence
10270: @samp{\a}.
10271:
10272: @item TARGET_BS
10273: @itemx TARGET_TAB
10274: @itemx TARGET_NEWLINE
10275: C constant expressions for the integer values for escape sequences
10276: @samp{\b}, @samp{\t} and @samp{\n}.
10277:
10278: @item TARGET_VT
10279: @itemx TARGET_FF
10280: @itemx TARGET_CR
10281: C constant expressions for the integer values for escape sequences
10282: @samp{\v}, @samp{\f} and @samp{\r}.
10283:
10284: @item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr})
10285: Define this macro if you are using an unusual assembler that
10286: requires different names for the machine instructions.
10287:
10288: The definition is a C statement or statements which output an
10289: assembler instruction opcode to the stdio stream @var{stream}. The
10290: macro-operand @var{ptr} is a variable of type @code{char *} which
10291: points to the opcode name in its ``internal'' form---the form that is
10292: written in the machine description. The definition should output the
10293: opcode name to @var{stream}, performing any translation you desire, and
10294: increment the variable @var{ptr} to point at the end of the opcode
10295: so that it will not be output twice.
10296:
10297: In fact, your macro definition may process less than the entire opcode
10298: name, or more than the opcode name; but if you want to process text
10299: that includes @samp{%}-sequences to substitute operands, you must take
10300: care of the substitution yourself. Just be sure to increment
10301: @var{ptr} over whatever text should not be output normally.
10302:
1.1.1.8 root 10303: If you need to look at the operand values, they can be found as the
10304: elements of @code{recog_operand}.
10305:
1.1 root 10306: If the macro definition does nothing, the instruction is output
10307: in the usual way.
10308:
10309: @item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands})
10310: If defined, a C statement to be executed just prior to the output of
10311: assembler code for @var{insn}, to modify the extracted operands so
10312: they will be output differently.
10313:
10314: Here the argument @var{opvec} is the vector containing the operands
10315: extracted from @var{insn}, and @var{noperands} is the number of
10316: elements of the vector which contain meaningful data for this insn.
10317: The contents of this vector are what will be used to convert the insn
10318: template into assembler code, so you can change the assembler output
10319: by changing the contents of the vector.
10320:
10321: This macro is useful when various assembler syntaxes share a single
10322: file of instruction patterns; by defining this macro differently, you
10323: can cause a large class of instructions to be output differently (such
10324: as with rearranged operands). Naturally, variations in assembler
10325: syntax affecting individual insn patterns ought to be handled by
10326: writing conditional output routines in those patterns.
10327:
10328: If this macro is not defined, it is equivalent to a null statement.
10329:
10330: @item PRINT_OPERAND (@var{stream}, @var{x}, @var{code})
10331: A C compound statement to output to stdio stream @var{stream} the
10332: assembler syntax for an instruction operand @var{x}. @var{x} is an
10333: RTL expression.
10334:
10335: @var{code} is a value that can be used to specify one of several ways
10336: of printing the operand. It is used when identical operands must be
10337: printed differently depending on the context. @var{code} comes from
10338: the @samp{%} specification that was used to request printing of the
10339: operand. If the specification was just @samp{%@var{digit}} then
10340: @var{code} is 0; if the specification was @samp{%@var{ltr}
10341: @var{digit}} then @var{code} is the ASCII code for @var{ltr}.
10342:
10343: If @var{x} is a register, this macro should print the register's name.
10344: The names can be found in an array @code{reg_names} whose type is
10345: @code{char *[]}. @code{reg_names} is initialized from
10346: @code{REGISTER_NAMES}.
10347:
10348: When the machine description has a specification @samp{%@var{punct}}
10349: (a @samp{%} followed by a punctuation character), this macro is called
10350: with a null pointer for @var{x} and the punctuation character for
10351: @var{code}.
10352:
1.1.1.8 root 10353: @item PRINT_OPERAND_PUNCT_VALID_P (@var{code})
10354: A C expression which evaluates to true if @var{code} is a valid
10355: punctuation character for use in the @code{PRINT_OPERAND} macro. If
10356: @code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no
10357: punctuation characters (except for the standard one, @samp{%}) are used
10358: in this way.
10359:
1.1 root 10360: @item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x})
10361: A C compound statement to output to stdio stream @var{stream} the
10362: assembler syntax for an instruction operand that is a memory reference
10363: whose address is @var{x}. @var{x} is an RTL expression.
10364:
10365: @item ASM_OPEN_PAREN
10366: @itemx ASM_CLOSE_PAREN
10367: These macros are defined as C string constant, describing the syntax
10368: in the assembler for grouping arithmetic expressions. The following
10369: definitions are correct for most assemblers:
10370:
10371: @example
10372: #define ASM_OPEN_PAREN "("
10373: #define ASM_CLOSE_PAREN ")"
10374: @end example
10375: @end table
10376:
10377: @node Config,, Machine Macros, Top
10378: @chapter The Configuration File
10379:
1.1.1.3 root 10380: The configuration file @file{xm-@var{machine}.h} contains macro definitions
10381: that describe the machine and system on which the compiler is running.
10382: Most of the values in it are actually the same on all machines that GNU CC
10383: runs on, so large parts of all configuration files are identical. But
1.1 root 10384: there are some macros that vary:
10385:
10386: @table @code
10387: @item FAILURE_EXIT_CODE
10388: A C expression for the status code to be returned when the compiler
10389: exits after serious errors.
10390:
10391: @item SUCCESS_EXIT_CODE
10392: A C expression for the status code to be returned when the compiler
10393: exits without serious errors.
1.1.1.10 root 10394:
10395: @item USE_C_ALLOCA
10396: Define this macro to indicate that the compiler is running with the
10397: @code{alloca} implemented in C. This version of @code{alloca} can be
10398: found in the file @file{alloca.c}; to use it, you must also alter the
10399: @file{Makefile} variable @code{ALLOCA}.
10400:
10401: This macro, unlike most, describes the machine that the compiler is
10402: running on, rather than the one the compiler is compiling for.
10403: Therefore, it should be set in the @file{xm-@var{machine}.h} file
10404: rather than in the @file{tm-@var{machine}.h} file.
10405:
10406: If you do define this macro, you should probably do it as follows:
10407:
10408: @example
10409: #ifndef __GNUC__
10410: #define USE_C_ALLOCA
10411: #else
10412: #define alloca __builtin_alloca
10413: #endif
10414: @end example
10415:
10416: @noindent
10417: so that when the compiler is compiled with GNU CC it uses the more
10418: efficient built-in @code{alloca} function.
1.1 root 10419: @end table
10420:
1.1.1.3 root 10421: In addition, configuration files for system V define @code{bcopy},
10422: @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
10423: as a macro when compiled with GNU CC, in order to take advantage of the
10424: benefit of GNU CC's built-in @code{alloca}.
10425:
1.1 root 10426: @contents
10427: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.