![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to internals.texinfo CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 1.x] / gcc|
Return to internals.texinfo CVS log | Up to [GCC 1.x] / gcc |
1.1 root 1: \input texinfo @c -*-texinfo-*-
2:
3: @settitle Internals of GNU CC
4: @setfilename internals
5:
6: @ifinfo
7: This file documents the internals of the GNU compiler.
8:
9: Copyright (C) 1987 Richard M. Stallman.
10:
11: Permission is granted to make and distribute verbatim copies of
12: this manual provided the copyright notice and this permission notice
13: are preserved on all copies.
14:
15: @ignore
16: Permission is granted to process this file through Tex and print the
17: results, provided the printed document carries copying permission
18: notice identical to this one except for the removal of this paragraph
19: (this paragraph not being relevant to the printed manual).
20:
21: @end ignore
22: Permission is granted to copy and distribute modified versions of this
23: manual under the conditions for verbatim copying, provided also that the
24: section entitled ``GNU CC General Public License'' is included exactly as
25: in the original, and provided that the entire resulting derived work is
26: distributed under the terms of a permission notice identical to this one.
27:
28: Permission is granted to copy and distribute translations of this manual
29: into another language, under the above conditions for modified versions,
30: except that the section entitled ``GNU CC General Public License'' may be
31: included in a translation approved by the author instead of in the original
32: English.
33: @end ifinfo
34:
35: @setchapternewpage odd
36:
37: @titlepage
38: @center @titlefont{Internals of GNU CC}
39: @sp 2
40: @center Richard M. Stallman
41: @page
42: @vskip 0pt plus 1filll
43: Copyright @copyright{} 1987 Richard M. Stallman.
44:
45: Permission is granted to make and distribute verbatim copies of
46: this manual provided the copyright notice and this permission notice
47: are preserved on all copies.
48:
49: Permission is granted to copy and distribute modified versions of this
50: manual under the conditions for verbatim copying, provided also that the
51: section entitled ``GNU CC General Public License'' is included exactly as
52: in the original, and provided that the entire resulting derived work is
53: distributed under the terms of a permission notice identical to this one.
54:
55: Permission is granted to copy and distribute translations of this manual
56: into another language, under the above conditions for modified versions,
57: except that the section entitled ``GNU CC General Public License'' may be
58: included in a translation approved by the author instead of in the original
59: English.
60: @end titlepage
61: @page
62:
63: @ifinfo
64: @node Top, Switches, , (DIR)
65:
66: Introduction
67: ************
68:
69: This manual documents how to install and port the GNU C compiler.
70:
71: @end ifinfo
72: @menu
73: * Copying:: GNU CC General Public License says
74: how you can copy and share GNU CC.
75: * Switches:: Command switches supported by @samp{gcc}.
76: * Installation:: How to configure, compile and install GNU CC.
77: * Portability:: Goals of GNU CC's portability features.
78: * Passes:: Order of passes, what they do, and what each file is for.
79: * RTL:: The intermediate representation that most passes work on.
80: * Machine Desc:: How to write machine description instruction patterns.
81: * Machine Macros:: How to write the machine description C macros.
82: @end menu
83:
84: @node Copying, Switches, Top, Top
85: @unnumbered GNU CC GENERAL PUBLIC LICENSE
86:
87: The license agreements of most software companies keep you at the
88: mercy of those companies. By contrast, our general public license is
89: intended to give everyone the right to share GNU CC. To make sure that
90: you get the rights we want you to have, we need to make restrictions
91: that forbid anyone to deny you these rights or to ask you to surrender
92: the rights. Hence this license agreement.
93:
94: Specifically, we want to make sure that you have the right to give
95: away copies of GNU CC, that you receive source code or else can get it
96: if you want it, that you can change GNU CC or use pieces of it in new
97: free programs, and that you know you can do these things.
98:
99: To make sure that everyone has such rights, we have to forbid you to
100: deprive anyone else of these rights. For example, if you distribute
101: copies of GNU CC, you must give the recipients all the rights that you
102: have. You must make sure that they, too, receive or can get the
103: source code. And you must tell them their rights.
104:
105: Also, for our own protection, we must make certain that everyone
106: finds out that there is no warranty for GNU CC. If GNU CC is modified by
107: someone else and passed on, we want its recipients to know that what
108: they have is not what we distributed, so that any problems introduced
109: by others will not reflect on our reputation.
110:
111: Therefore we (Richard Stallman and the Free Software Fundation,
112: Inc.) make the following terms which say what you must do to be
113: allowed to distribute or change GNU CC.
114:
115: @unnumberedsec COPYING POLICIES
116:
117: @enumerate
118: @item
119: You may copy and distribute verbatim copies of GNU CC source code as
120: you receive it, in any medium, provided that you conspicuously and
121: appropriately publish on each copy a valid copyright notice
122: ``Copyright @copyright{} 1987 Free Software Foundation, Inc.'' (or
123: with the year updated if that is appropriate); keep intact the notices
124: on all files that refer to this License Agreement and to the absence
125: of any warranty; and give any other recipients of the GNU CC program a
126: copy of this License Agreement along with the program. You may charge
127: a distribution fee for the physical act of transferring a copy.
128:
129: @item
130: You may modify your copy or copies of GNU CC or any portion of it,
131: and copy and distribute such modifications under the terms of
132: Paragraph 1 above, provided that you also do the following:
133:
134: @itemize @bullet
135: @item
136: cause the modified files to carry prominent notices stating
137: that you changed the files and the date of any change; and
138:
139: @item
140: cause the whole of any work that you distribute or publish,
141: that in whole or in part contains or is a derivative of GNU CC or
142: any part thereof, to be licensed at no charge to all third
143: parties on terms identical to those contained in this License
144: Agreement (except that you may choose to grant more extensive
145: warranty protection to some or all third parties, at your
146: option).
147:
148: @item
149: You may charge a distribution fee for the physical act of
150: transferring a copy, and you may at your option offer warranty
151: protection in exchange for a fee.
152: @end itemize
153:
154: @item
155: You may copy and distribute GNU CC or any portion of it in
156: compiled, executable or object code form under the terms of Paragraphs
157: 1 and 2 above provided that you do the following:
158:
159: @itemize @bullet
160: @item
161: cause each such copy to be accompanied by the
162: corresponding machine-readable source code, which must
163: be distributed under the terms of Paragraphs 1 and 2 above; or,
164:
165: @item
166: cause each such copy to be accompanied by a
167: written offer, with no time limit, to give any third party
168: free (except for a nominal shipping charge) a machine readable
169: copy of the corresponding source code, to be distributed
170: under the terms of Paragraphs 1 and 2 above; or,
171:
172: @item
173: in the case of a recipient of GNU CC in compiled, executable
174: or object code form (without the corresponding source code) you
175: shall cause copies you distribute to be accompanied by a copy
176: of the written offer of source code which you received along
177: with the copy you received.
178: @end itemize
179:
180: @item
181: You may not copy, sublicense, distribute or transfer GNU CC
182: except as expressly provided under this License Agreement. Any attempt
183: otherwise to copy, sublicense, distribute or transfer GNU CC is void and
184: your rights to use the program under this License agreement shall be
185: automatically terminated. However, parties who have received computer
186: software programs from you with this License Agreement will not have
187: their licenses terminated so long as such parties remain in full compliance.
188:
189: @item
190: If you wish to incorporate parts of GNU CC into other free programs
191: whose distribution conditions are different, write to the Free Software
192: Foundation at 1000 Mass Ave, Cambridge, MA 02138. We have not yet worked
193: out a simple rule that can be stated here, but we will often permit this.
194: We will be guided by the two goals of preserving the free status of all
195: derivatives our free software and of promoting the sharing and reuse of
196: software.
197: @end enumerate
198:
199: Your comments and suggestions about our licensing policies and our
200: software are welcome! Please contact the Free Software Foundation, Inc.,
201: 1000 Mass Ave, Cambridge, MA 02138, or call (617) 876-3296.
202:
203: @unnumberedsec NO WARRANTY
204:
205: BECAUSE GNU CC IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO
206: WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT
207: WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC,
208: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU CC "AS IS" WITHOUT
209: WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
210: LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
211: A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
212: PERFORMANCE OF GNU CC IS WITH YOU. SHOULD GNU CC PROVE DEFECTIVE, YOU
213: ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
214:
215: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL RICHARD M.
216: STALLMAN, THE FREE SOFTWARE FOUNDATION, INC., AND/OR ANY OTHER PARTY
217: WHO MAY MODIFY AND REDISTRIBUTE GNU CC AS PERMITTED ABOVE, BE LIABLE TO
218: YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
219: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
220: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
221: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
222: FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) GNU CC, EVEN
223: IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR
224: ANY CLAIM BY ANY OTHER PARTY.
225:
226: @node Switches, Installation, Copying, Top
227: @chapter GNU CC Switches
228:
229: @table @samp
230: @item -O
231: Do optimize.
232:
233: @item -g
234: Produce debugging information in DBX format.
235:
236: @item -c
237: Compile but do not link the object files.
238:
239: @item -o @var{file}
240: Place linker output in file @var{file}.
241:
242: @item -S
243: Compile into assembler code but do not assemble.
244:
245: @item -m@var{machinespec}
246: Machine-dependent switch specifying something about the type
247: of target machine. For example, using the 68000 machine description,
248: @samp{-m68000} specifies do not use the 68020 instructions,
249: and @samp{-msoft-float} specifies do not use the 68881 floating point
250: instructions.
251:
252: @item -d@var{letters}
253: Says to make debugging dumps at times specified by @var{letters}.
254: Here are the possible letters:
255:
256: @table @samp
257: @item t
258: Dump syntax-tree.
259: @item r
260: Dump after RTL generation.
261: @item j
262: Dump after first jump optimization.
263: @item s
264: Dump after CSE.
265: @item L
266: Dump after loop optimization.
267: @item f
268: Dump after flow analysis.
269: @item c
270: Dump after instruction combination.
271: @item l
272: Dump after local register allocation.
273: @item g
274: Dump after global register allocation.
275: @end table
276:
277: @item -pedantic
278: Attempt to support strict ANSI standard C. Valid ANSI standard C
279: programs should compile properly with or without this switch.
280: However, without this switch, certain useful or traditional constructs
281: banned by the standard are supported. With this switch, they are
282: rejected. There is no reason to use this switch; it exists only
283: to satisfy pedants.
284:
285: @item E
286: Preprocess the input files and output the results to standard output.
287:
288: @item C
289: Tell the preprocessor not to discard comments. Used with the @samp{-E}
290: switch.
291:
292: @item I@var{dir}
293: Search directory @var{dir} for include files.
294:
295: @item D@var{macro}
296: Define macro @var{macro} with the empty string as its definition.
297:
298: @item D@var{macro}=@var{defn}
299: Define macro @var{macro} as @var{defn}.
300:
301: @item U@var{macro}
302: Undefine macro @var{macro}.
303:
304: @item w
305: Inhibit warning messages.
306:
307: @item v
308: Compiler driver program prints the commands it executes as it runs
309: the preprocessor, compiler proper, assembler and linker.
310:
311: @item B@var{prefix}
312: Compiler driver program tries @var{prefix} as a prefix for each program
313: it tries to run. These programs are @file{cpp}, @file{cc1},
314: @file{as} and @file{ld}.
315:
316: For each subprogram to be run, the compiler driver first tries the
317: @samp{-B} prefix, if any. If that name is not found, or if @samp{-B}
318: was not specified, the driver tries two standard prefixes, which are
319: @file{/usr/lib/gcc-} and @file{/usr/local/lib/gcc-}. If neither of
320: those results in a file name that is found, the unmodified program
321: name is searched for using the @samp{PATH} environment variable.
322: @end table
323:
324: @node Installation, Portability, Switches, Top
325: @chapter Installing GNU CC
326:
327: @enumerate
328: @item
329: Choose configuration files.
330:
331: @itemize @bullet
332: @item
333: Make a symbolic link from file @file{config.h} to the top-level
334: config file for the machine you are using. Its name should be
335: @file{config-@var{machine}.h}. This file is responsible for
336: defining information about the host machine. It includes
337: @file{tm.h}.
338:
339: @item
340: Make a symbolic link from @file{tm.h} to the machine-description
341: macro file for your machine (its name should be
342: @file{tm-@var{machine}.h}).
343:
344: @item
345: Make a symbolic link from @file{md} to the
346: machine description pattern file (its name should be
347: @file{@var{machine}.md}).
348:
349: @item
350: Make a symbolic link from
351: @file{aux-output.c} to the output-subroutine file for your machine
352: (its name should be @file{@var{machine}-output.c}).
353: @end itemize
354:
355: @item
356: Make sure the Bison parser generator is installed.
357:
358: @item
359: Build the compiler. Just type @samp{make} in the compiler directory.
360:
361: @item
362: Delete @file{*.o} in the compiler directory. The executables from
363: the previous step remain for the next step.
364:
365: @item
366: Remake the compiler with
367:
368: @example
369: make CC=./gcc CFLAGS="-g -O -I."
370: @end example
371:
372: @item
373: Install the compiler's passes. Copy the file @file{cc1} made by the
374: compiler to the name @file{/usr/local/lib/gcc-cc1}.
375:
376: Make the file @file{/usr/local/lib/gcc-cpp} either a link to @file{/lib/cpp}
377: or a copy of the file @file{cpp} generated by @samp{make}.
378:
379: @strong{Warning: the GNU CPP may not work for @file{ioctl.h}.} This
380: cannot be fixed in the GNU CPP because the bug is in @file{ioctl.h}:
381: at least on some machines, it relies on behavior that is incompatible
382: with ANSI C. This behavior consists of substituting for macro
383: argument names when they appear inside of character constants.
384:
385: @item
386: Install the compiler driver. This is the file @file{gcc} generated
387: by @samp{make}.
388: @end enumerate
389:
390: @node Portability, Passes, Installation, Top
391: @chapter GNU CC and Portability
392:
393: The main goal of GNU CC was to make a good, fast compiler for machines in
394: the class that the GNU system aims to run on: 32-bit machines that address
395: 8-bit bytes and have several general registers. Elegance, theoretical
396: power and simplicity are only secondary.
397:
398: GNU CC gets most of the information about the target machine from a machine
399: description which gives an algebraic formula for each of the machine's
400: instructions. This is a very clean way to describe the target. But when
401: the compiler needs information that is difficult to express in this
402: fashion, I have not hesitated to define an ad-hoc parameter to the machine
403: description. The purpose of portability is to reduce the total work needed
404: on the compiler; it was not of interest for its own sake.
405:
406: GNU CC does not contain machine dependent code, but it does contain code
407: that depends on machine parameters such as endianness (whether the most
408: significant byte has the highest or lowest address of the bytes in a word)
409: and the availability of autoincrement addressing. In the RTL-generation
410: pass, it is often necessary to have multiple strategies for generating code
411: for a particular kind of syntax tree, strategies that are usable for different
412: combinations of parameters. Often I have not tried to address all possible
413: cases, but only the common ones or only the ones that I have encountered.
414: As a result, a new target may require additional strategies. You will know
415: if this happens because the compiler will call @code{abort}. Fortunately,
416: the new strategies can be added to all versions of the compiler, and will
417: be relevant only for target machines that need them.
418:
419: @node Passes, RTL, Portability, Top
420: @chapter Passes and Files of the Compiler
421:
422: The overall control structure of the compiler is in @file{toplev.c}. This
423: file is responsible for initialization, decoding arguments, opening and
424: closing files, and sequencing the passes.
425:
426: The parsing pass is invoked only once, to parse the entire input. Each
427: time a complete function definition or top-level data definition is read,
428: the parsing pass calls the function @code{rest_of_compilation} in
429: @file{toplev.c}, which is responsible for all further processing necessary,
430: ending with output of the assembler language. All other compiler passes
431: run, in sequence, within @code{rest_of_compilation}. After
432: @code{rest_of_compilation} returns from compiling a function definition,
433: the storage used for its compilation is entirely freed.
434:
435: Here is a list of all the passes of the compiler and their source files.
436: Also included is a description of where debugging dumps can be requested
437: with @samp{-d} switches.
438:
439: @itemize @bullet
440: @item
441: Parsing. This pass reads the entire text of a function definition,
442: constructing a syntax tree. The tree representation does not entirely
443: follow C syntax, because it is intended to support other languages as well.
444:
445: C data type analysis is also done in this pass, and every tree node that
446: represents an expression has a data type attached. Variables are represented
447: as declaration nodes.
448:
449: Constant folding and associative-law simplifications are also done during
450: this pass.
451:
452: The source files of the parsing pass are @file{parse.y}, @file{decl.c},
453: @file{typecheck.c}, @file{stor-layout.c}, @file{fold-const.c}, and
454: @file{tree.c}. The last three are intended to be language-independent.
455: There are also header files @file{parse.h}, @file{c-tree.h},
456: @file{tree.h} and @file{tree.def}. The last two define the format of
457: the tree representation.
458:
459: @item
460: RTL generation. This pass converts the tree structure for one
461: function into RTL code.
462:
463: This is where the bulk of target-parameter-dependent code is found,
464: since often it is necessary for strategies to apply only when certain
465: standard kinds of instructions are available. The purpose of named
466: instruction patterns is to provide this information to the RTL
467: generation pass.
468:
469: Optimization is done in this pass for @code{if}-conditions that are
470: comparisons, boolean operations or conditional expressions. Tail
471: recursion is detected at this time also. Decisions are made about how
472: best to arrange loops and how to output @code{switch} statements.
473:
474: The files of the RTL generation pass are @file{stmt.c}, @file{expr.c},
475: @file{explow.c}, @file{expmed.c}, @file{optabs.c} and @file{emit-rtl.c}.
476: Also, the file @file{insn-emit.c}, generated from the machine description
477: by the program @code{genemit}, is used in this pass. The header files
478: @file{expr.h} is used for communication within this pass.
479:
480: The header files @file{insn-flags.h} and @file{insn-codes.h}, generated from
481: the machine description by the programs @code{genflags} and @code{gencodes},
482: tell this pass which standard names are available for use and which patterns
483: correspond to them.
484:
485: Aside from debugging information output, none of the following passes
486: refers to the tree structure representation of the function.
487:
488: The switch @samp{-dr} causes a debugging dump of the RTL code after this
489: pass. This dump file's name is made by appending @samp{.rtl} to the
490: input file name.
491:
492: @item
493: Jump optimization. This pass simplifies jumps to the following instruction,
494: jumps across jumps, and jumps to jumps. It deletes unreferenced labels
495: and unreachable code, except that unreachable code that contains a loop
496: is not recognized as unreachable in this pass. (Such loops are deleted
497: later in the basic block analysis.)
498:
499: Jump optimization is performed two or three times. The first time is
500: immediately following RTL generation.
501:
502: The source file of this pass is @file{jump.c}.
503:
504: The switch @samp{-dj} causes a debugging dump of the RTL code after this
505: pass is run for the first time. This dump file's name is made by appending
506: @samp{.jump} to the input file name.
507:
508: @item
509: Register scan. This pass finds the first and last use of each
510: register, as a guide for common subexpression elimination. Its source
511: is in @file{regclass.c}.
512:
513: @item
514: Common subexpression elimination. This pass also does constant
515: propagation. Its source file is @file{cse.c}. If constant
516: propagation causes conditional jumps to become unconditional or to
517: become no-ops, jump optimization is run again when cse is finished.
518:
519: The switch @samp{-ds} causes a debugging dump of the RTL code after
520: this pass. This dump file's name is made by appending @samp{.cse} to
521: the input file name.
522:
523: @item
524: Loop optimization. This pass moves constant expressions out of loops.
525: Its source file is @file{loop.c}.
526:
527: The switch @samp{-dL} causes a debugging dump of the RTL code after
528: this pass. This dump file's name is made by appending @samp{.loop} to
529: the input file name.
530:
531: @item
532: Stupid register allocation is performed at this point in a
533: nonoptimizing compilation. It does a little data flow analysis as
534: well. When stupid register allocation is in use, the next pass
535: executed is the reloading pass; the others in between are skipped.
536: The source file is @file{stupid.c}, with header file @file{stupid.h}
537: used for communication with the RTL generation pass.
538:
539: @item
540: Data flow analysis (@file{flow.c}). This pass divides the program
541: into basic blocks (and in the process deletes unreachable loops); then
542: it computes which pseudo-registers are live at each point in the
543: program, and makes the first instruction that uses a value point at
544: the instruction that computed the value.
545:
546: This pass also deletes computations whose results are never used, and
547: combines memory references with add or subtract instructions to make
548: autoincrement or autodecrement addressing.
549:
550: The switch @samp{-df} causes a debugging dump of the RTL code after
551: this pass. This dump file's name is made by appending @samp{.flow} to
552: the input file name. If stupid register allocation is in use, this
553: dump file reflects the full results of such allocation.
554:
555: @item
556: Instruction combination (@file{combine.c}). This pass attempts to
557: combine groups of two or three instructions that are related by data
558: flow into single instructions. It combines the RTL expressions for
559: the instructions by substitution, simplifies the result using algebra,
560: and then attempts to match the result against the machine description.
561:
562: The switch @samp{-dc} causes a debugging dump of the RTL code after
563: this pass. This dump file's name is made by appending @samp{.combine}
564: to the input file name.
565:
566: @item
567: Register class preferencing. The RTL code is scanned to find out
568: which register class is best for each pseudo register. The source file
569: is @file{regclass.c}.
570:
571: @item
572: Local register allocation (@file{local-alloc.c}). This pass allocates
573: hard registers to pseudo registers that are used only within one basic
574: block. Because the basic block is linear, it can use fast and powerful
575: techniques to do a very good job.
576:
577: The switch @samp{-dl} causes a debugging dump of the RTL code after
578: this pass. This dump file's name is made by appending @samp{.lreg} to
579: the input file name.
580:
581: @item
582: Global register allocation (@file{global-alloc.c}). This pass
583: allocates hard registers for the remaining pseudo registers (those
584: whose life spans are not contained in one basic block).
585:
586: @item
587: Reloading. This pass finds instructions that are invalid because a
588: value has failed to end up in a register, or has ended up in a
589: register of the wrong kind. It fixes up these instructions by
590: reloading the problematical values into registers temporarily.
591: Additional instructions are generated to do the copying.
592:
593: Source files are @file{reload.c} and @file{reload1.c}, plus the header
594: @file{reload.h} used for communication between them.
595:
596: The switch @samp{-dg} causes a debugging dump of the RTL code after
597: this pass. This dump file's name is made by appending @samp{.greg} to
598: the input file name.
599:
600: @item
601: Jump optimization is repeated, this time including cross-jumping.
602:
603: @item
604: Final. This pass outputs the assembler code for the function. It is
605: also responsible for identifying no-op move instructions and spurious
606: test and compare instructions. The function entry and exit sequences
607: are generated directly as assembler code in this pass; they never
608: exist as RTL. Pseudo registers that did not get hard registers are
609: given stack slots in this pass.
610:
611: The source files are @file{final.c} plus @file{insn-output.c}; the
612: latter is generated automatically from the machine description by the
613: tool @file{genoutput}. The header file @file{conditions.h} is used
614: for communication between these files.
615:
616: @item
617: Debugging information output. This is run after final because it must
618: output the stack slot offsets for pseudo registers that did not get
619: hard registers. Source files are @file{dbxout.c} for DBX symbol table
620: format and @file{symout.c} for GDB's own symbol table format.
621: @end itemize
622:
623: Some additional files are used by all or many passes:
624:
625: @itemize @bullet
626: @item
627: Every pass uses @file{machmode.def}, which defines the machine modes.
628:
629: @item
630: All the passes that work with RTL use the header files @file{rtl.h}
631: and @file{rtl.def}, and subroutines in file @file{rtl.c}. The
632: tools @code{gen*} also use these files to read and work with the
633: machine description RTL.
634:
635: @item
636: Several passes refer to the header file @file{insn-config.h} which
637: contains a few parameters (C macro definitions) generated
638: automatically from the machine description RTL by the tool
639: @code{genconfig}.
640:
641: @item
642: Several passes use the instruction recognizer, which consists of
643: @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
644: and @file{insn-extract.c} that are generated automatically from the
645: machine description by the tools @file{genrecog} and @file{genextract}.
646:
647: @item
648: Several passes use the header file @file{regs.h} which defines the
649: information recorded about pseudo register usage, @file{basic-block.h}
650: which defines the information recorded about basic blocks.
651:
652: @item
653: @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
654: with a bit for each hard register, and some macros to manipulate it.
655: This type is just @code{int} if the machine has few enough hard registers;
656: otherwise it is an array of @code{int} and some of the macros expand
657: into loops.
658: @end itemize
659:
660: @node RTL, Machine Desc, Passes, Top
661: @chapter RTL Representation
662:
663: Most of the work of the compiler is done on an intermediate representation
664: called register tranfer language. In this language, the instructions to be
665: output are described, pretty much one by one, in an algebraic form that
666: describes what the instruction does.
667:
668: RTL is inspired by Lisp lists. It has both an internal form, made up of
669: structures that point at other structures, and a textual form that is used
670: in the machine description and in printed debugging dumps. The textual
671: form uses nested parentheses to indicate the pointers in the internal form.
672:
673: @menu
674: * RTL Objects:: Expressions vs vectors vs strings vs integers.
675: * Accessors:: Macros to access expression operands or vector elts.
676: * Machine Modes:: Describing the size and format of a datum.
677: * Constants:: Expressions with constant values.
678: * Regs and Memory:: Expressions representing register contents or memory.
679: * Arithmetic:: Expressions representing arithmetic on other expressions.
680: * Comparisons:: Expressions representing comparison of expressions.
681: * Bit Fields:: Expressions representing bit-fields in memory or reg.
682: * Conversions:: Extending, truncating, floating or fixing.
683: * RTL Declarations:: Declaring volatility, constancy, etc.
684: * Side Effects:: Expressions for storing in registers, etc.
685: * Incdec:: Embedded side-effects for autoincrement addressing.
686: * Insns:: Expression types for entire insns.
687: * Sharing:: Some expressions are unique; others *must* be copied.
688: @end menu
689:
690: @node RTL Objects, Accessors, RTL, RTL
691: @section RTL Object Types
692:
693: RTL uses four kinds of objects: expressions, integers, strings and vectors.
694: Expressions are the most important ones. An RTL expression is a C
695: structure, but it is usually referred to with a pointer; a type that is
696: given the typedef name @code{rtx}.
697:
698: An integer is simply an @code{int}, and a string is a @code{char *}.
699: Within rtl code, strings appear only inside @samp{symbol_ref} expressions,
700: but they appear in other contexts in the rtl expressions that make up
701: machine descriptions. Their written form uses decimal digits.
702:
703: A string is a sequence of characters. In core it is represented as a
704: @code{char *} in usual C fashion, and they are written in C syntax as well.
705: However, strings in RTL may never be null. If you write an empty string in
706: a machine description, it is represented in core as a null pointer rather
707: than as a pointer to a null character. In certain contexts, these null
708: pointers instead of strings are valid.
709:
710: A vector contains an arbitrary, specified number of pointers to
711: expressions. The number of elements in the vector is explicitly present in
712: the vector. The written form of a vector consists of square brackets
713: (@samp{[@dots{}]}) surrounding the elements, in sequence and with
714: whitespace separating them. Vectors of length zero are not created; null
715: pointers are used instead.
716:
717: Expressions are classified by @dfn{expression code}. The expression code
718: is a name defined in @file{rtl.def}, which is also (in upper case) a C
719: enumeration constant. The possible expression codes and their meanings are
720: machine-independent. The code of an rtx can be extracted with the macro
721: @code{GET_CODE (@var{x})} and altered with @code{PUT_CODE (@var{x},
722: @var{newcode})}.
723:
724: The expression code determines how many operands the expression contains,
725: and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
726: by looking at an operand what kind of object it is. Instead, you must know
727: from its context---from the expression code of the containing expression.
728: For example, in an expression of code @code{subreg}, the first operand is
729: to be regarded as an expression and the second operand as an integer. In
730: an expression of code @code{plus}, there are two operands, both of which
731: are to be regarded as expressions. In a @code{symbol_ref} expression,
732: there is one operand, which is to be regarded as a string.
733:
734: Expressions are written as parentheses containing the name of the
735: expression type, its flags and machine mode if any, and then the operands
736: of the expression (separated by spaces).
737:
738: In a few contexts a null pointer is valid where an expression is normally
739: wanted. The written form of this is @samp{(nil)}.
740:
741: @node Accessors, Machine Modes, RTL Objects, RTL
742: @section Access to Operands
743:
744: For each expression type @file{rtl.def} specifies the number of contained
745: objects and their kinds, with four possibilities: @samp{e} for expression
746: (actually a pointer to an expression), @samp{i} for integer, @samp{s} for
747: string, and @samp{E} for vector of expressions. The sequence of letters
748: for an expression code is called its @dfn{format}. Thus, the format of
749: @code{subreg} is @samp{ei}.
750:
751: Two other format characters are used occasionally: @samp{u} and @samp{0}.
752: @samp{u} is equivalent to @samp{e} except that it is printed differently in
753: debugging dumps, and @samp{0} means a slot whose contents do not fit any
754: normal category. @samp{0} slots are not printed at all in dumps, and are
755: often used in special ways by small parts of the compiler.
756:
757: There are macros to get the number of operands and the format of an
758: expression code:
759:
760: @table @code
761: @item GET_RTX_LENGTH (@var{code})
762: Number of operands of an rtx of code @var{code}.
763:
764: @item GET_RTX_FORMAT (@var{code})
765: The format of an rtx of code @var{code}, as a C string.
766: @end table
767:
768: Operands of expressions are accessed using the macros @code{XEXP},
769: @code{XINT} and @code{XSTR}. Each of these macros takes two arguments: an
770: expression-pointer (rtx) and an operand number (counting from zero). Thus,
771:
772: @example
773: XEXP (x, 2)
774: @end example
775:
776: @noindent
777: accesses operand 2 of expression @var{x}, as an expression.
778:
779: @example
780: XINT (x, 2)
781: @end example
782:
783: @noindent
784: accesses the same operand as an integer. @code{XSTR}, used in the same
785: fashion, would access it as a string.
786:
787: Any operand can be accessed as an integer, as an expression or as a string.
788: You must choose the correct method of access for the kind of value actually
789: stored in the operand. You would do this based on the expression code of
790: the containing expression. That is also how you would know how many
791: operands there are.
792:
793: For example, if @var{x} is a @samp{subreg} expression, you know that it has
794: two operands which can be correctly accessed as @code{XEXP (x, 0)} and
795: @code{XINT (x, 1)}. If you did @code{XINT (x, 0)}, you would get the
796: address of the expression operand but cast as an integer; that might
797: occasionally be useful, but it would be cleaner to write @code{(int) XEXP
798: (x, 0)}. @code{XEXP (x, 1)} would also compile without error, and would
799: return the second, integer operand cast as an expression pointer, which
800: would probably result in a crash when accessed. Nothing stops you from
801: writing @code{XEXP (x, 28)} either, but this will access memory past the
802: end of the expression with unpredictable results.
803:
804: Access to operands which are vectors is more complicated. You can use the
805: macro @code{XVEC} to get the vector-pointer itself, or the macros
806: @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
807: vector.
808:
809: @table @code
810: @item XVEC (@var{exp}, @var{idx})
811: Access the vector-pointer which is operand number @var{idx} in @var{exp}.
812:
813: @item XVECLEN (@var{exp}, @var{idx})
814: Access the length (number of elements) in the vector which is
815: in operand number @var{idx} in @var{exp}. This value is an @code{int}.
816:
817: @item XVECLEN (@var{exp}, @var{idx}, @var{eltnum})
818: Access element number @var{eltnum} in the vector which is
819: in operand number @var{idx} in @var{exp}. This value is an @code{rtx}.
820:
821: It is up to you to make sure that @var{eltnum} is not negative
822: and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
823: @end table
824:
825: All the macros defined in this section expand into lvalues and therefore
826: can be used to assign the operands, lengths and vector elements as well as
827: to access them.
828:
829: @node Machine Modes, Constants, Accessors, RTL
830: @section Machine Modes
831:
832: A machine mode describes a size of data object and the representation used
833: for it. In the C code, machine modes are represented by an enumeration
834: type, @code{enum machine_mode}. Each rtl expression has room for a machine
835: mode and so do certain kinds of tree expressions (declarations and types,
836: to be precise).
837:
838: In debugging dumps and machine descriptions, the machine mode of an RTL
839: expression is written after the expression code with a colon to separate
840: them. The letters @samp{mode} which appear at the end of each machine mode
841: name are omitted. For example, @code{(reg:SI 38)} is a @samp{reg}
842: expression with machine mode @code{SImode}. If the mode is
843: @code{VOIDmode}, it is not written at all.
844:
845: Here is a table of machine modes.
846:
847: @table @code
848: @item QImode
849: ``Quarter-Integer'' mode represents a single byte treated as an integer.
850:
851: @item HImode
852: ``Half-Integer'' mode represents a two-byte integer.
853:
854: @item SImode
855: ``Single Integer'' mode represents a four-byte integer.
856:
857: @item DImode
858: ``Double Integer'' mode represents an eight-byte integer.
859:
860: @item TImode
861: ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
862:
863: @item SFmode
864: ``Single Floating'' mode represents a single-precision (four byte) floating
865: point number.
866:
867: @item DFmode
868: ``Double Floating'' mode represents a double-precision (eight byte) floating
869: point number.
870:
871: @item TFmode
872: ``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
873: floating point number.
874:
875: @item BLKmode
876: ``Block'' mode represents values that are aggregates to which none of
877: the other modes apply. In rtl, only memory references can have this mode,
878: and only if they appear in string-move or vector instructions. On machines
879: which have no such instructions, @code{BLKmode} will not appear in RTL.
880:
881: @item VOIDmode
882: Void mode means the absence of a mode or an unspecified mode.
883: For example, RTL expresslons of code @samp{const_int} have mode
884: @code{VOIDmode} because they can be taken to have whatever mode the context
885: requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
886: the absence of any mode.
887:
888: @item EPmode
889: ``Entry Pointer'' mode is intended to be used for function variables in
890: Pascal and other block structured languages. Such values contain
891: both a function address and a static chain pointer for access to
892: automatic variables of outer levels. This mode is only partially
893: implemented since C does not use it.
894:
895: @item CSImode@r{, @dots{}}
896: ``Complex Single Integer'' mode stands for a complex number represented
897: as a pair of @code{SImode} integers. Any of the integer and floating modes
898: may have @samp{C} prefixed to its name to obtain a complex number mode.
899: For example, there are @code{CQImode}, @code{CSFmode}, and @code{CDFmode}.
900: Since C does not support complex numbers, these machine modes are only
901: partially implemented.
902:
903: @item BImode
904: This is the machine mode of a bit-field in a structure. It is used
905: only in the syntax tree, never in RTL, and in the syntax tree it appears
906: only in declaration nodes. In C, it appears only in @code{FIELD_DECL}
907: nodes for structure fields defined with a bit size.
908: @end table
909:
910: The machine description defines @code{Pmode} as a C macro which expands
911: into the machine mode used for addresses. Normally this is @code{SImode}.
912:
913: The only modes which a machine description @i{must} support are
914: @code{QImode}, @code{SImode}, @code{SFmode} and @code{DFmode}. The
915: compiler will attempt to use @code{DImode} for two-word structures and
916: unions, but it would not be hard to program it to avoid this. Likewise,
917: you can arrange for the C type @code{short int} to avoid using
918: @code{HImode}. In the long term it would be desirable to make the set of
919: available machine modes machine-dependent and eliminate all assumptions
920: about specific machine modes or their uses from the machine-independent
921: code of the compiler.
922:
923: Here are some C macros that relate to machine modes:
924:
925: @table @code
926: @item GET_MODE (@var{x})
927: Returns the machine mode of the rtx @var{x}.
928:
929: @item PUT_MODE (@var{x}, @var{newmode})
930: Alters the machine mode of the rtx @var{x} to be @var{newmode}.
931:
932: @item GET_MODE_SIZE (@var{m})
933: Returns the size in bytes of a datum of mode @var{m}.
934:
935: @item GET_MODE_BITSIZE (@var{m})
936: Returns the size in bits of a datum of mode @var{m}.
937:
938: @item GET_MODE_UNIT_SIZE (@var{m})
939: Returns the size in bits of the subunits of a datum of mode @var{m}.
940: This is the same as @code{GET_MODE_SIZE} except in the case of
941: complex modes and @code{EPmode}. For them, the unit size ithe
942: size of the real or imaginary part, or the size of the function
943: pointer or the context pointer.
944: @end table
945:
946: @node Constants, Regs and Memory, Machine Modes, RTL
947: @section Constant Expression Types
948:
949: The simplest RTL expressions are those that represent constant values.
950:
951: @table @code
952: @item (const_int @var{i})
953: This type of expression represents the integer value @var{i}. @var{i}
954: is customarily accessed with the macro @code{INTVAL} as in
955: @code{INTVAL (exp)}, which is equivalent to @code{XINT (exp, 0)}.
956:
957: There is only one expression object for the integer value zero;
958: it is the value of the variable @code{const0_rtx}. Likewise, the
959: only expression for integer value one is found in @code{const1_rtx}.
960: Any attempt to create an expression of code @code{const_int} and
961: value zero or one will return @code{const0_rtx} or @code{const1_rtx}
962: as appropriate.
963:
964: @item (const_double:@var{m} @var{i0} @var{i1})
965: Represents a floating point constant value of mode @var{m}. The two
966: integers @var{i0} and @var{i1} together contain the bits of a
967: @code{double} value. To convert them to a @code{double}, do
968:
969: @example
970: union { double d; int i[2];} u;
971: u.i[0] = XINT (x, 0);
972: u.i[1] = XINT (x, 1);
973: @end example
974:
975: @noindent
976: and then refer to @code{u.d}. The value of the constant is
977: represented as a double in this fashion even if the value represented
978: is single-precision.
979:
980: @code{dconst0_rtx} and @code{fconst0_rtx} are @samp{CONST_DOUBLE}
981: expressions with value 0 and modes @code{DFmode} and @code{SFmode}.
982:
983: @item (symbol_ref @var{symbol})
984: Represents the value of an assembler label for data. @var{symbol} is
985: a string that describes the name of the assembler label. If it starts
986: with a @samp{*}, the label is the rest of @var{symbol} not including
987: the @samp{*}. Otherwise, the label is @var{symbol}, prefixed with
988: @samp{_}.
989:
990: @item (label_ref @var{label})
991: Represents the value of an assembler label for code. It contains one
992: operand, an expression, which must be a @code{code_label} that appears
993: in the instruction sequence to identify the place where the label
994: should go.
995:
996: The reason for using a distinct expression type for code label
997: references is so that jump optimization can distinguish them.
998:
999: @item (const @var{exp})
1000: Represents a constant that is the result of an assembly-time
1001: arithmetic computation. The operand, @var{exp}, is an expression that
1002: contains only constants (@samp{const_int}, @samp{symbol_ref} and
1003: @samp{label_ref} expressions) combined with @samp{plus} and
1004: @samp{minus}. However, not all combinations are valid, since the
1005: assembler cannot do arbitrary arithmetic on relocatable symbols.
1006: @end table
1007:
1008: @node Regs and Memory, Arithmetic, Constants, RTL
1009: @section Registers and Memory
1010:
1011: Here are the RTL expression types for describing access to machine
1012: registers and to main memory.
1013:
1014: @table @code
1015: @item (reg:@var{m} @var{n})
1016: For small values of the integer @var{n} (less than
1017: @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1018: register number @var{n}: a @dfn{hard register}. For larger values of
1019: @var{n}, it stands for a temporary value or @dfn{pseudo register}.
1020: The compiler's strategy is to generate code assuming an unlimited
1021: number of such pseudo registers, and later convert them into hard
1022: registers or into memory references.
1023:
1024: The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1025: description, since the number of hard registers on the machine is an
1026: invariant characteristic of the machine. Note, however, that not
1027: all of the machine registers must be general registers. All the
1028: machine registers that can be used for storage of data are given
1029: hard register numbers, even those that can be used only in certain
1030: instructions or can hold only certain types of data.
1031:
1032: Each pseudo register number used in a function's rtl code is
1033: represented by a unique @samp{reg} expression.
1034:
1035: @var{m} is the machine mode of the reference. It is necessary because
1036: machines can generally refer to each register in more than one mode.
1037: For example, a register may contain a full word but there may be
1038: instructions to refer to it as a half word or as a single byte, as
1039: well as instructions to refer to it as a floating point number of
1040: various precisions.
1041:
1042: Even for a register that the machine can access in only one mode,
1043: the mode must always be specified.
1044:
1045: A hard register may be accessed in various modes throughout one
1046: function, but each pseudo register is given a natural mode
1047: and is accessed only in that mode. When it is necessary to describe
1048: an access to a pseudo register using a nonnatural mode, a @samp{subreg}
1049: expression is used.
1050:
1051: A @samp{reg} expression with a machine mode that specifies more than
1052: one word of data may actually stand for several consecutive registers.
1053: If in addition the register number specifies a hardware register, then
1054: it actually represents several consecutive hardware registers starting
1055: with the specified one.
1056:
1057: Such multi-word hardware register @samp{reg} expressions may not be live
1058: across the boundary of a basic block. The lifetime analysis pass does not
1059: know how to record properly that several consecutive registers are
1060: actually live there, and therefore register allocation would be confused.
1061: The CSE pass must go out of its way to make sure the situation does
1062: not arise.
1063:
1064: @item (subreg:@var{m} @var{reg} @var{wordnum})
1065: @samp{subreg} expressions are used to refer to a register in a machine
1066: mode other than its natural one, or to refer to one register of
1067: a multi-word @samp{reg} that actually refers to several registers.
1068:
1069: Each pseudo-register has a natural mode. If it is necessary to
1070: operate on it in a different mode---for example, to perform a fullword
1071: move instruction on a pseudo-register that contains a single byte---
1072: the pseudo-register must be enclosed in a @samp{subreg}. In such
1073: a case, @var{wordnum} is zero.
1074:
1075: The other use of @samp{subreg} is to extract the individual registers
1076: of a multi-register value. Machine modes such as @code{DImode} and
1077: @code{EPmode} indicate values longer than a word, values which usually
1078: require two consecutive registers. To access one of the registers,
1079: use a @samp{subreg} with mode @code{SImode} and a @var{wordnum} that
1080: says which register.
1081:
1082: The compilation parameter @code{WORDS_BIG_ENDIAN}, if defined, says
1083: that word number zero is the most significant part; otherwise, it is
1084: the least significant part.
1085:
1086: Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
1087: using a @samp{subreg}. On some machines the most significant part of a
1088: @code{DFmode} value does not have the same format as a single-precision
1089: floating value.
1090:
1091: @item (cc0)
1092: This refers to the machine's condition code register. It has no
1093: operands and may not have a machine mode. It may be validly used in
1094: only two contexts: as the destination of an assignment (in test and
1095: compare instructions) and in comparison operators comparing against
1096: zero (@code{const_int} with value zero; that is to say,
1097: @code{const0_rtx}.
1098:
1099: There is only one expression object of code @code{cc0}; it is the
1100: value of the variable @code{cc0_rtx}. Any attempt to create an
1101: expression of code @code{cc0} will return @code{cc0_rtx}.
1102:
1103: One special thing about the condition code register is that instructions
1104: can set it implicitly. On many machines, nearly all instructions set
1105: the condition code based on the value that they compute or store.
1106: It is not necessary to record these actions explicitly in the RTL
1107: because the machine description includes a prescription for recognizing
1108: the instructions that do so (by means of the macro @code{NOTICE_UPDATE_CC}).
1109: Only instructions whose sole purpose is to set the condition code,
1110: and instructions that use the condition code, need mention @code{(cc0)}.
1111:
1112: @item (pc)
1113: This represents the machine's program counter. It has no operands and
1114: may not have a machine mode. @code{(pc)} may be validly used only in
1115: certain specific contexts in jump instructions.
1116:
1117: There is only one expression object of code @code{pc}; it is the value of
1118: the variable @code{pc_rtx}. Any attempt to create an expression of code
1119: @code{pc} will return @code{pc_rtx}.
1120:
1121: All instructions that do not jump alter the program counter implicitly,
1122: but there is no need to mention this in the RTL.
1123:
1124: @item (mem:@var{m} @var{addr})
1125: This rtx represents a reference to main memory at an address
1126: represented by the expression @var{addr}. @var{m} specifies how
1127: large a unit of memory is accessed.
1128: @end table
1129:
1130: @node Arithmetic, Comparisons, Regs and Memory, RTL
1131: @section RTL Expressions for Arithmetic
1132:
1133: @table @code
1134: @item (plus:@var{m} @var{x} @var{y})
1135: Represents the sum of the values represented by @var{x} and @var{y}
1136: carried out in machine mode @var{m}. This is valid only if
1137: @var{x} and @var{y} both are valid for mode @var{m}.
1138:
1139: @item (minus:@var{m} @var{x} @var{y})
1140: Like @samp{plus} but represents subtraction.
1141:
1142: @item (minus @var{x} @var{y})
1143: Represents the result of subtracting @var{y} from @var{x}
1144: for purposes of comparison. The absence of a machine mode
1145: in the @samp{minus} expression indicates that the result is
1146: computed without overflow, as if with infinite precision.
1147:
1148: Of course, machines can't really subtract with infinite precision.
1149: However, they can pretend to do so when only the sign of the
1150: result will be used, which is the case when the result is stored
1151: in @code{(cc0)}. And that is the only was this kind of expression
1152: may validly be used: as a value to be stored in the condition codes.
1153:
1154: @item (neg:@var{m} @var{x})
1155: Represents the negation (subtraction from zero) of the value
1156: represented by @var{x}, carried out in mode @var{m}. @var{x} must be
1157: valid for mode @var{m}.
1158:
1159: @item (mult:@var{m} @var{x} @var{y})
1160: Represents the signed product of the values represented by @var{x} and
1161: @var{y} carried out in machine mode @var{m}. If
1162: @var{x} and @var{y} are both valid for mode @var{m}, this is ordinary
1163: size-preserving multiplication. Alteratively, both @var{x} and @var{y}
1164: may be valid for a different, narrower mode. This represents the
1165: kind of multiplication that generates a product wider than the operands.
1166: Widening multiplication and same-size multiplication are completely
1167: distinct and supported by different machine instructions; machines may
1168: support one but not the other.
1169:
1170: @samp{mult} may be used for floating point division as well.
1171: Then @var{m} is a floating point machine mode.
1172:
1173: @item (umult:@var{m} @var{x} @var{y})
1174: Like @samp{mult} but represents unsigned multiplication. It may be
1175: used in both same-size and widening forms, like @samp{mult}.
1176: @samp{umult} is used only for fixed-point division.
1177:
1178: @item (div:@var{m} @var{x} @var{y})
1179: Represents the quotient in signed division of @var{x} by @var{y},
1180: carried out in machine mode @var{m}. If @var{m} is a floating-point
1181: mode, it represents the exact quotient; otherwise, the integerized
1182: quotient. If @var{x} and @var{y} are both valid for mode @var{m},
1183: this is ordinary size-preserving division. Some machines have
1184: division instructions in which the operands and quotient widths are
1185: not all the same; such instructions are represented by @samp{div}
1186: expressions in which the machine modes are not all the same.
1187:
1188: @item (udiv:@var{m} @var{x} @var{y})
1189: Like @samp{div} but represents unsigned division.
1190:
1191: @item (mod:@var{m} @var{x} @var{y})
1192: @itemx (umod:@var{m} @var{x} @var{y})
1193: Like @samp{div} and @samp{udiv} but represent the remainder instead of
1194: the quotient.
1195:
1196: @item (not:@var{m} @var{x})
1197: Represents the bitwise complement of the value represented by @var{x},
1198: carried out in mode @var{m}, which must be a fixed-point machine mode.
1199: @var{x} must be valid for mode @var{m}, which must be a fixed-point mode.
1200:
1201: @item (and:@var{m} @var{x} @var{y})
1202: Represents the bitwise logical-and of the values represented by
1203: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
1204: valid only if @var{x} and @var{y} both are valid for mode @var{m},
1205: which must be a fixed-point mode.
1206:
1207: @item (ior:@var{m} @var{x} @var{y})
1208: Represents the bitwise inclusive-or of the values represented by
1209: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
1210: valid only if @var{x} and @var{y} both are valid for mode @var{m},
1211: which must be a fixed-point mode.
1212:
1213: @item (xor:@var{m} @var{x} @var{y})
1214: Represents the bitwise exclusive-or of the values represented by
1215: @var{x} and @var{y}, carried out in machine mode @var{m}. This is
1216: valid only if @var{x} and @var{y} both are valid for mode @var{m},
1217: which must be a fixed-point mode.
1218:
1219: @item (lshift:@var{m} @var{x} @var{c})
1220: Represents the result of logically shifting @var{x} left by @var{c}
1221: places. @var{x} must be valid for the mode @var{m}, a fixed-point
1222: machine mode. @var{c} must be valid for a fixed-point mode;
1223: which mode is determined by the mode called for in the machine
1224: description entry for the left-shift instruction. For example,
1225: on the Vax, the mode of @var{c} is @code{QImode} regardless of @var{m}.
1226:
1227: On some machines, negative values of @var{c} may be meaningful; this
1228: is why logical left shift an arithmetic left shift are distinguished.
1229: For example, Vaxes have no right-shift instructions, and right shifts
1230: are represented as left-shift instructions whose counts happen
1231: to be negative constants or else computed (in a previous instruction)
1232: by negation.
1233:
1234: @item (ashift:@var{m} @var{x} @var{c})
1235: Like @samp{lshift} but for arithmetic left shift.
1236:
1237: @item (lshiftrt:@var{m} @var{x} @var{c})
1238: @itemx (ashiftrt:@var{m} @var{x} @var{c})
1239: Like @samp{lshift} and @samp{ashift} but for right shift.
1240:
1241: @item (rotate:@var{m} @var{x} @var{c})
1242: @itemx (rotatert:@var{m} @var{x} @var{c})
1243: Similar but represent left and right rotate.
1244:
1245: @item (abs:@var{m} @var{x})
1246: Represents the absolute value of @var{x}, computed in mode @var{m}.
1247: @var{x} must be valid for @var{m}.
1248:
1249: @item (sqrt:@var{m} @var{x})
1250: Represents the square root of @var{x}, computed in mode @var{m}.
1251: @var{x} must be valid for @var{m}. Most often @var{m} will be
1252: a floating point mode.
1253: @end table
1254:
1255: @node Comparisons, Bit Fields, Arithmetic, RTL
1256: @section Comparison Operations
1257:
1258: Comparison operators test a relation on two operands and are considered to
1259: represent the value 1 if the relation holds, or zero if it does not. The
1260: mode of the comparison is determined by the operands; they must both be
1261: valid for a common machine mode. A comparison with both operands constant
1262: would be invalid as the machine mode could not be deduced from it, but such
1263: a comparison should never exist in rtl due to constant folding.
1264:
1265: Inequality comparisons come in two flavors, signed and unsigned. Thus,
1266: there are distinct expression codes @samp{GT} and @samp{GTU} for signed and
1267: unsigned greater-than. These can produce different results for the same
1268: pair of integer values: for example, 1 is signed greater-than -1 but not
1269: unsigned greater-than, because -1 when regarded as unsigned is actually
1270: 0xffffffff which is greater than 1.
1271:
1272: The signed comparisons are also used for floating point values. Floating
1273: point comparisons are distinguished by the machine modes of the operands.
1274:
1275: The comparison operators may be used to compare the condition codes
1276: @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}.
1277: Such a construct actually refers to the result of the preceding
1278: instruction in which the condition codes were set. The above
1279: example stands for 1 if the condition codes were set to say
1280: ``zero'' or ``equal'', 0 otherwise. Although the same comparison
1281: operators are used for this as may be used in other contexts
1282: on actual data, no confusion can result since the machine description
1283: would never allow both kinds of uses in the same context.
1284:
1285: @table @code
1286: @item (eq @var{x} @var{y})
1287: 1 if the values represented by @var{x} and @var{y} are equal,
1288: otherwise 0.
1289:
1290: @item (ne @var{x} @var{y})
1291: 1 if the values represented by @var{x} and @var{y} are not equal,
1292: otherwise 0.
1293:
1294: @item (gt @var{x} @var{y})
1295: 1 if the @var{x} is greater than @var{y}. If they are fixed-point,
1296: the comparison is done in a signed sense.
1297:
1298: @item (gtu @var{x} @var{y})
1299: Like @samp{gt} but does unsigned comparison, on fixed-point numbers only.
1300:
1301: @item (lt @var{x} @var{y})
1302: @item (ltu @var{x} @var{y})
1303: Like @samp{gt} and @samp{gtu} but test for ``less than''.
1304:
1305: @item (ge @var{x} @var{y})
1306: @item (geu @var{x} @var{y})
1307: Like @samp{gt} and @samp{gtu} but test for ``greater than or equal''.
1308:
1309: @item (le @var{x} @var{y})
1310: @item (leu @var{x} @var{y})
1311: Like @samp{gt} and @samp{gtu} but test for ``less than or equal''.
1312:
1313: @item (if_then_else @var{cond} @var{then} @var{else})
1314: This is not a comparison operation but is listed here because it is
1315: always used in conjunction with a comparison operation. To be
1316: precise, @var{cond} is a comparison expression. This expression
1317: represents a choice, according to @var{cond}, between the value
1318: represented by @var{then} and the one represented by @var{else}.
1319:
1320: On most machines, @samp{if_then_else} expressions are valid only
1321: to express conditional jumps.
1322: @end table
1323:
1324: @node Bit Fields, Conversions, Comparisons, RTL
1325: @section Bit-fields
1326:
1327: Special expression codes exist to represent bit-field instructions.
1328: These types of expressions are lvalues in rtl; they may appear
1329: on the left side of a assignment, indicating insertion of a value
1330: into the specified bit field.
1331:
1332: @table @code
1333: @item (sign_extract:SI @var{loc} @var{size} @var{pos})
1334: This represents a reference to a sign-extended bit-field contained or
1335: starting in @var{loc} (a memory or register reference). The bit field
1336: is @var{size} bits wide and starts at bit @var{pos}. The compilation
1337: switch @code{BITS_BIG_ENDIAN} says which end of the memory unit
1338: @var{pos} counts from.
1339:
1340: Which machine modes are valid for @var{loc} depends on the machine,
1341: but typically @var{loc} should be a single byte when in memory
1342: or a full word in a register.
1343:
1344: @item (zero_extract:SI @var{loc} @var{pos} @var{size})
1345: Like @samp{sign_extract} but refers to an unsigned or zero-extended
1346: bit field. The same sequence of bits are extracted, but they
1347: are filled to an entire word with zeros instead of by sign-extension.
1348: @end table
1349:
1350: @node Conversions, RTL Declarations, Bit Fields, RTL
1351: @section Conversions
1352:
1353: All conversions between machine modes must be represented by
1354: explicit conversion operations. For example, an expression
1355: which the sum of a byte and a full word cannot be written as
1356: @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @samp{plus}
1357: operation requires two operands of the same machine mode.
1358: Therefore, the byte-sized operand is enclosed in a conversion
1359: operation, as in
1360:
1361: @example
1362: (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
1363: @end example
1364:
1365: The conversion operation is not a mere placeholder, because there
1366: may be more than one way of converting from a given starting mode
1367: to the desired final mode. The conversion operation code says how
1368: to do it.
1369:
1370: @table @code
1371: @item (sign_extend:@var{m} @var{x})
1372: Represents the result of sign-extending the value @var{x}
1373: to machine mode @var{m}. @var{m} must be a fixed-point mode
1374: and @var{x} a fixed-point value of a mode narrower than @var{m}.
1375:
1376: @item (zero_extend:@var{m} @var{x})
1377: Represents the result of zero-extending the value @var{x}
1378: to machine mode @var{m}. @var{m} must be a fixed-point mode
1379: and @var{x} a fixed-point value of a mode narrower than @var{m}.
1380:
1381: @item (float_extend:@var{m} @var{x})
1382: Represents the result of extending the value @var{x}
1383: to machine mode @var{m}. @var{m} must be a floating point mode
1384: and @var{x} a floating point value of a mode narrower than @var{m}.
1385:
1386: @item (truncate:@var{m} @var{x})
1387: Represents the result of truncating the value @var{x}
1388: to machine mode @var{m}. @var{m} must be a fixed-point mode
1389: and @var{x} a fixed-point value of a mode wider than @var{m}.
1390:
1391: @item (float_truncate:@var{m} @var{x})
1392: Represents the result of truncating the value @var{x}
1393: to machine mode @var{m}. @var{m} must be a floating point mode
1394: and @var{x} a floating point value of a mode wider than @var{m}.
1395:
1396: @item (float:@var{m} @var{x})
1397: Represents the result of converting fixed point value @var{x}
1398: to floating point mode @var{m}.
1399:
1400: @item (fix:@var{m} @var{x})
1401: Represents the result of converting floating point value @var{x}
1402: to fixed point mode @var{m}. How rounding is done is not specified.
1403:
1404: @end table
1405:
1406: @node RTL Declarations, Side Effects, Conversions, RTL
1407: @section Declarations
1408:
1409: Declaration expression codes do not represent arithmetic operations
1410: but rather state assertions about their operands.
1411:
1412: @table @code
1413: @item (volatile:@var{m} @var{x})
1414: Represents the same value @var{x} does, but makes the assertion
1415: that it should be treated as a volatile value. This forbids
1416: coalescing multiple accesses or deleting them even if it would
1417: appear to have no effect on the program. @var{x} must be a @samp{mem}
1418: expression with mode @var{m}.
1419:
1420: The first thing the reload pass does to an insn is to remove all
1421: @samp{volatile} expressions from it; each one is replaced by its
1422: operand.
1423:
1424: Recognizers will never recognize anything with @samp{volatile} in it.
1425: This automatically prevents some optimizations on such things
1426: (such as instruction combination). After the reload pass removes
1427: all volatility information, the insns can be recognized.
1428:
1429: Cse removes @samp{volatile} from destinations of @samp{set}'s, because
1430: no optimizations reorder such @samp{set}s. This is not required for
1431: correct code and is done to permit some optimization on the value to
1432: be stored.
1433:
1434: @item (unchanging:@var{m} @var{x})
1435: Represents the same value @var{x} does, but makes the assertion
1436: that its value is effectively constant during the execution
1437: of the current function. This permits references to @var{x}
1438: to be moved freely within the function. @var{x} must be a @samp{reg}
1439: expression with mode @var{m}.
1440:
1441: @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
1442: This expression code is used in only one context: operand 0 of a
1443: @samp{set} expression. In addition, the operand of this expression
1444: must be a @samp{subreg} expression.
1445:
1446: The presence of @samp{strict_low_part} says that the part of the
1447: register which is meaningful in mode @var{n} but is not part of
1448: mode @var{m} is not to be altered. Normally, an assignment to such
1449: a subreg is allowed to have undefined effects on the rest of the
1450: register when @var{m} is less than a word.
1451: @end table
1452:
1453: @node Side Effects, Incdec, RTL Declarations, RTL
1454: @section Side Effect Expressions
1455:
1456: The expression codes described so far represent values, not actions.
1457: But machine instructions never produce values; they are meaningful
1458: only for their side effects on the state of the machine. Special
1459: expression codes are used to represent side effects.
1460:
1461: The body of an instruction is always one of these side effect codes;
1462: the codes described above, which represent values, appear only as
1463: the operands of these.
1464:
1465: @table @code
1466: @item (set @var{lval} @var{x})
1467: Represents the action of storing the value of @var{x} into the place
1468: represented by @var{lval}. @var{lval} must be an expression
1469: representing a place that can be stored in: @samp{reg} (or
1470: @samp{subreg} or @samp{strict_low_part}), @samp{mem}, @samp{pc} or
1471: @samp{cc0}.
1472:
1473: If @var{lval} is a @samp{reg}, @samp{subreg} or @samp{mem}, it has a
1474: machine mode; then @var{x} must be valid for that mode.
1475:
1476: If @var{lval} is a @samp{reg} whose machine mode is less than the full
1477: width of the register, then it means that the part of the register
1478: specified by the machine mode is given the specified value and the
1479: rest of the register receives an undefined value. Likewise, if
1480: @var{lval} is a @samp{subreg} whose machine mode is narrower than
1481: @code{SImode}, the rest of the register can be changed in an undefined way.
1482:
1483: If @var{lval} is a @samp{strict_low_part} of a @samp{subreg}, then the
1484: part of the register specified by the machine mode of the
1485: @samp{subreg} is given the value @var{x} and the rest of the register
1486: is not changed.
1487:
1488: If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
1489: have any mode. This represents a ``test'' or ``compare'' instruction.
1490:
1491: If @var{lval} is @code{(pc)}, we have a jump instruction, and the
1492: possibilities for @var{x} are very limited. It may be a
1493: @samp{label_ref} expression (unconditional jump). It may be an
1494: @samp{if_then_else} (conditional jump), in which case either the
1495: second or the third operand must be @code{(pc)} (for the case which
1496: does not jump) and the other of the two must be a @samp{label_ref}
1497: (for the case which does jump). @var{x} may also be a @samp{mem} or
1498: @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @samp{reg} or a
1499: @samp{mem}; these unusual patterns are used to represent jumps through
1500: branch tables.
1501:
1502: @item (return)
1503: Represents a return from the current function, on machines where
1504: this can be done with one instruction, such as Vaxen. On machines
1505: where a multi-instruction ``epilogue'' must be executed in order
1506: to return from the function, returning is done by jumping to a
1507: label which precedes the epilogue, and the @samp{return} expression
1508: code is never used.
1509:
1510: @item (call @var{function} @var{nargs})
1511: Represents a function call. @var{function} is a @samp{mem} expression
1512: whose address is the address of the function to be called. @var{nargs}
1513: is an expression representing the number of words of argument.
1514:
1515: Each machine has a standard machine mode which @var{function} must
1516: have. The machine descripion defines macro @code{FUNCTION_MODE} to
1517: expand into the requisite mode name. The purpose of this mode is to
1518: specify what kind of addressing is allowed, on machines where the
1519: allowed kinds of addressing depend on the machine mode being
1520: addressed.
1521:
1522: @item (clobber @var{x})
1523: Represents the storing or possible storing of an unpredictable,
1524: undescribed value into @var{x}, which must be a @samp{reg} or
1525: @samp{mem} expression.
1526:
1527: One place this is used is in string instructions that store standard
1528: values into particular hard registers. It may not be worth the
1529: trouble to describe the values that are stored, but it is essential
1530: to inform the compiler that the registers will be altered, lest it
1531: attempt to keep data in them across the string instruction.
1532:
1533: @var{x} may also be null---a null C pointer, no expression at all.
1534: Such a @code{(clobber (null))} expression means that all memory
1535: locations must be presumed clobbered.
1536:
1537: Note that the machine description classifies certain hard registers as
1538: ``call-clobbered''. All function call instructions are assumed by
1539: default to clobber these registers, so there is no need to use
1540: @samp{clobber} expressions to indicate this fact. Also, each function
1541: call is assumed to have the potential to alter any memory location.
1542:
1543: @item (use @var{x})
1544: Represents the use of the value of @var{x}. It indicates that
1545: the value in @var{x} at this point in the program is needed,
1546: even though it may not be apparent whythis is so. Therefore, the
1547: compiler will not attempt to delete instructions whose only
1548: effect is to store a value in @var{x}. @var{x} must be a @samp{reg}
1549: expression.
1550:
1551: @item (parallel [@var{x0} @var{x1} @dots{}])
1552: Represents several side effects performed in parallel. The square
1553: brackets stand for a vector; the operand of @samp{parallel} is a
1554: vector of expressions. @var{x0}, @var{x1} and so on are individual
1555: side effects---expressions of code @samp{set}, @samp{call},
1556: @samp{return}, @samp{clobber} or @samp{use}.
1557:
1558: ``In parallel'' means that first all the values used in
1559: the individual side-effects are computed, and second all the actual
1560: side-effects are performed. For example,
1561:
1562: @example
1563: (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
1564: (set (mem:SI (reg:SI 1)) (reg:SI 1))])
1565: @end example
1566:
1567: @noindent
1568: says unambiguously that the values of hard register 1 and the memory
1569: location addressed by it are interchanged. In both places where
1570: @code{(reg:SI 1)} appears as a memory address it refers to the value
1571: in register 1 @i{before} the execution of the instruction.
1572: @end table
1573:
1574: Three expression codes appear in place of a side effect, as the body
1575: of an insn, though strictly speaking they do not describe side effects
1576: as such:
1577:
1578: @table @code
1579: @item (asm_input @var{s})
1580: Represents literal assembler code as described by the string @var{s}.
1581:
1582: @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
1583: Represents a table of jump addresses. @var{lr0} etc. are
1584: @samp{label_ref} expressions. The mode @var{m} specifies how much
1585: space is given to each address; normally @var{m} would be
1586: @code{Pmode}.
1587:
1588: @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
1589: Represents a table of jump addresses expressed as offsets from
1590: @var{base}. @var{lr0} etc. are @samp{label_ref} expressions and so is
1591: @var{base}. The mode @var{m} specifies how much space is given to
1592: each address-difference.
1593: @end table
1594:
1595: @node Incdec, Insns, Side Effects, RTL
1596: @section Embedded Side-Effects on Addresses
1597:
1598: Four special side-effect expression codes appear as memory addresses.
1599:
1600: @table @code
1601: @item (pre_dec:@var{m} @var{x})
1602: Represents the side effect of decrementing @var{x} by a standard
1603: amount and represents also the value that @var{x} has after being
1604: decremented. @var{x} must be a @samp{reg} or @samp{mem}, but most
1605: machines allow only a @samp{reg}. @var{m} must be the machine mode
1606: for pointers on the machine in use. The amount @var{x} is decrement
1607: by is the length in bytes of the machine mode of the containing memory
1608: reference of which this expression serves as the address. Here is an
1609: example of its use:
1610:
1611: @example
1612: (mem:DF (pre_dec:SI (reg:SI 39)))
1613: @end example
1614:
1615: @noindent
1616: This says to decrement pseudo register 39 by the length of a @code{DFmode}
1617: value and use the result to address a @code{DFmode} value.
1618:
1619: @item (pre_inc:@var{m} @var{x})
1620: Similar, but specifies incrementing @var{x} instead of decrementing it.
1621:
1622: @item (post_dec:@var{m} @var{x})
1623: Represents the same side effect as @samp{pre_decrement} but a different
1624: value. The value represented here is the value @var{x} has @i{before}
1625: being decremented.
1626:
1627: @item (post_inc:@var{m} @var{x})
1628: Similar, but specifies incrementing @var{x} instead of decrementing it.
1629: @end table
1630:
1631: These embedded side effect expressions must be used with care. Instruction
1632: patterns may not use them. Until the @samp{flow} pass of the compiler,
1633: they may occur only to represent pushes onto the stack. The @samp{flow}
1634: pass finds cases where registers are incremented or decremented in one
1635: instruction and used as an address shortly before or after; these cases are
1636: then transformed to use pre- or post-increment or -decrement.
1637:
1638: Explicit popping of the stack could be represented with these embedded
1639: side effect operators, but that would not be safe; the instruction
1640: combination pass could move the popping past pushes, thus changing
1641: the meaning of the code.
1642:
1643: An instruction that can be represented with an embedded side effect
1644: could also be represented using @samp{parallel} containing an additional
1645: @samp{set} to describe how the address register is altered. This is not
1646: done because machines that allow these operations at all typically
1647: allow them wherever a memory address is called for. Describing them as
1648: additional parallel stores would require doubling the number of entries
1649: in the machine description.
1650:
1651: @node Insns, Sharing, Incdec, RTL
1652: @section Insns
1653:
1654: The RTL representation of the code for a function is a doubly-linked
1655: chain of objects called @dfn{insns}. Insns are expressions with
1656: special codes that are used for no other purpose. Some insns are
1657: actual instructions; others represent dispatch tables for @code{switch}
1658: statements; others represent labels to jump to or various sorts of
1659: declaratory information.
1660:
1661: In addition to its own specific data, each insn must have a unique id number
1662: that distinguishes it from all other insns in the current function, and
1663: chain pointers to the preceding and following insns. These three fields
1664: occupy the same position in every insn, independent of the expression code
1665: of the insn. They could be accessed with @code{XEXP} and @code{XINT},
1666: but instead three special macros are always used:
1667:
1668: @table @code
1669: @item INSN_UID (@var{i})
1670: Accesses the unique id of insn @var{i}.
1671:
1672: @item PREV_INSN (@var{i})
1673: Accesses the chain pointer to the insn preceding @var{i}.
1674: If @var{i} is the first insn, this is a null pointer.
1675:
1676: @item NEXT_INSN (@var{i})
1677: Accesses the chain pointer to the insn following @var{i}.
1678: If @var{i} is the last insn, this is a null pointer.
1679: @end table
1680:
1681: The @code{NEXT_INSN} and @code{PREV_INSN} pointers must always
1682: correspond: if @var{i} is not the first insn,
1683:
1684: @example
1685: NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
1686: @end example
1687:
1688: @noindent
1689: is always true.
1690:
1691: Every insn has one of the following six expression codes:
1692:
1693: @table @code
1694: @item insn
1695: The expression code @samp{insn} is used for instructions that do not jump
1696: and do not do function calls. Insns with code @samp{insn} have four
1697: additional fields beyond the three mandatory ones listed above.
1698: These four are described in a table below.
1699:
1700: @item jump_insn
1701: The expression code @samp{jump_insn} is used for instructions that may jump
1702: (or, more generally, may contain @samp{label_ref} expressions).
1703: @samp{jump_insn} insns have the same extra fields as @samp{insn} insns,
1704: accessed in the same way.
1705:
1706: @item call_insn
1707: The expression code @samp{call_insn} is used for instructions that may do
1708: function calls. It is important to distinguish these instructions because
1709: they imply that certain registers and memory locations may be altered
1710: unpredictably.
1711:
1712: @samp{call_insn} insns have the same extra fields as @samp{insn} insns,
1713: accessed in the same way.
1714:
1715: @item code_label
1716: A @samp{code_label} insn represents a label that a jump insn can jump to.
1717: It contains one special field of data in addition to the three standard ones.
1718: It is used to hold the @dfn{label number}, a number that identifies this
1719: label uniquely among all the labels in the compilation (not just in the
1720: current function). Ultimately, the label is represented in the assembler
1721: output as an assembler label @samp{L@var{n}} where @var{n} is the label number.
1722:
1723: @item barrier
1724: Barriers are placed in the instruction stream after unconditional
1725: jump instructions to indicate that the jumps are unconditional.
1726: They contain no information beyond the three standard fields.
1727:
1728: @item note
1729: @samp{note} insns are used to represent additional debugging and
1730: declaratory information. They contain two nonstandard fields, an
1731: integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
1732: string accessed with @code{NOTE_SOURCE_FILE}.
1733:
1734: If @code{NOTE_LINE_NUMBER} is positive, the note represents the
1735: position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
1736: that the line came from. These notes control generation of line
1737: number data in the assembler output.
1738:
1739: Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
1740: code with one of the following values (and @code{NOTE_SOURCE_FILE}
1741: must contain a null pointer):
1742:
1743: @table @code
1744: @item NOTE_INSN_DELETED
1745: Such a note is completely ignorable. Some passes of the compiler
1746: delete insns by altering them into notes of this kind.
1747:
1748: @item NOTE_INSN_BLOCK_BEG
1749: @itemx NOTE_INSN_BLOCK_END
1750: These types of notes indicate the position of the beginning and end
1751: of a level of scoping of variable names. They control the output
1752: of debugging information.
1753:
1754: @item NOTE_INSN_LOOP_BEG
1755: @itemx NOTE_INSN_LOOP_END
1756: These types of notes indicate the position of the beginning and end
1757: of a @code{while} or @code{for} loop. They enable the loop optimizer
1758: to find loops quickly.
1759: @end table
1760: @end table
1761:
1762: Here is a table of the extra fields of @samp{insn}, @samp{jump_insn}
1763: and @samp{call_insn} insns:
1764:
1765: @table @code
1766: @item PATTERN (@var{i})
1767: An expression for the side effect performed by this insn.
1768:
1769: @item REG_NOTES (@var{i})
1770: A list (chain of @samp{expr_list} expressions) giving information
1771: about the usage of registers in this insn. This list is set up by the
1772: @code{flow} pass; it is a null pointer until then.
1773:
1774: @item LOG_LINKS (@var{i})
1775: A list (chain of @samp{insn_list} expressions) of previous ``related''
1776: insns: insns which store into registers values that are used for the
1777: first time in this insn. (An additional constraint is that neither a
1778: jump nor a label may come between the related insns). This list is
1779: set up by the @code{flow} pass; it is a null pointer until then.
1780:
1781: @item INSN_CODE (@var{i})
1782: An integer that says which pattern in the machine description matches
1783: this insn, or -1 if the matching has not yet been attempted.
1784:
1785: Such matching is never attempted and this field is not used on an insn
1786: whose pattern consists of a single @samp{use}, @samp{clobber},
1787: @samp{asm}, @samp{addr_vec} or @samp{addr_diff_vec} expression.
1788: @end table
1789:
1790: The @code{LOG_LINKS} field of an insn is a chain of @samp{insn_list}
1791: expressions. Each of these has two operands: the first is an insn,
1792: and the second is another @samp{insn_list} expression (the next one in
1793: the chain). The last @samp{insn_list} in the chain has a null pointer
1794: as second operand. The significant thing about the chain is which
1795: insns apepar in it (as first operands of @samp{insn_list}
1796: expressions). Their order is not significant.
1797:
1798: The @code{REG_NOTES} field of an insn is a similar chain but of
1799: @samp{expr_list} expressions instead of @samp{insn_list}. The first
1800: operand is a @samp{reg} rtx. Its presence in the list can have three
1801: possible meanings, distinguished by a value that is stored in the
1802: machine-mode field of the @samp{expr_list} because that is a
1803: conveniently available space, but that is not really a machine mode.
1804: These values belong to the C type @code{enum reg_note} and there are
1805: three of them:
1806:
1807: @table @code
1808: @item REG_DEAD
1809: The @samp{reg} listed dies in this insn; that is to say, altering
1810: the value immediately after this insn would not affect the future
1811: behavior of the program.
1812:
1813: @item REG_INC
1814: The @samp{reg} listed is incremented (or decremented; at this level
1815: there is no distinction) by an embedded side effect inside this insn.
1816:
1817: @item REG_CONST
1818: The @samp{reg} listed has a value that could safely be replaced
1819: everywhere by the value that this insn copies into it. (``Safety''
1820: here refers to the data flow of the program; such replacement may
1821: require reloading into registers for some of the insns in which
1822: the @samp{reg} is replaced.)
1823:
1824: @item REG_WAS_0
1825: The @samp{reg} listed contained zero before this insn. You can rely
1826: on this note if it is present; its absence implies nothing.
1827: @end table
1828:
1829: (The only difference between the expression codes @samp{insn_list} and
1830: @samp{expr_list} is that the first operand of an @samp{insn_list} is
1831: assumed to be an insn and is printed in debugging dumps as the insn's
1832: unique id; the first operand of an @samp{expr_list} is printed in the
1833: ordinary way as an expression.)
1834:
1835: @node Sharing,, Insns, RTL
1836: @section Structure Sharing Assumptions
1837:
1838: The compiler assumes that certain kinds of RTL expressions are unique;
1839: there do not exist two distinct objects representing the same value.
1840: In other cases, it makes an opposite assumption: that no RTL expression
1841: object of a certain kind appears in more than one place in the
1842: containing structure.
1843:
1844: These assumptions refer to a single function; except for the RTL
1845: objects that describe global variables and external functions,
1846: no RTL objects are common to two functions.
1847:
1848: @itemize @bullet
1849: @item
1850: Each pseudo-register has only a single @samp{reg} object to represent it,
1851: and therefore only a single machine mode.
1852:
1853: @item
1854: For any symbolic label, there is only one @samp{symbol_ref} object
1855: referring to it.
1856:
1857: @item
1858: There is only one @samp{const_int} expression with value zero,
1859: and only one with value one.
1860:
1861: @item
1862: There is only one @samp{pc} expression.
1863:
1864: @item
1865: There is only one @samp{cc0} expression.
1866:
1867: @item
1868: There is only one @samp{const_double} expression with mode
1869: @code{SFmode} and value zero, and only one with mode @code{DFmode} and
1870: value zero.
1871:
1872: @item
1873: No @samp{label_ref} appears in more than one place in the RTL structure;
1874: in other words, it is safe to do a tree-walk of all the insns in the function
1875: and assume that each time a @samp{label_ref} is seen it is distinct from all
1876: other @samp{label_refs} seen.
1877:
1878: @item
1879: Aside from the cases listed above, the only kind of expression
1880: object that may appear in more than one place is the @samp{mem}
1881: object that describes a stack slot or a static variable.
1882: @end itemize
1883:
1884: @node Machine Desc, Machine Macros, RTL, Top
1885: @chapter Machine Descriptions
1886:
1887: A machine description has two parts: a file of instruction patterns
1888: (@file{.md} file) and a C header file of macro definitions.
1889:
1890: The @file{.md} file for a target machine contains a pattern for each
1891: instruction that the target machine supports (or at least each instruction
1892: that is worth telling the compiler about). It may also contain comments.
1893: A semicolon causes the rest of the line to be a comment, unless the semicolon
1894: is inside a quoted string.
1895:
1896: See the next chapter for information on the C header file.
1897:
1898: @menu
1899: * Patterns:: How to write instruction patterns.
1900: * Example:: Example of an instruction pattern.
1901: * Constraints:: When not all operands are general operands.
1902: * Standard Names:: Names mark patterns to use for code generation.
1903: * Dependent Patterns:: Having one pattern may make you need another.
1904: @end menu
1905:
1906: @node Patterns, Example, Machine Desc, Machine Desc
1907: @section Instruction Patterns
1908:
1909: Each instruction pattern contains an incomplete RTL expression, with pieces
1910: to be filled in later, operand constraints that restrict how the pieces can
1911: be filled in, and an output pattern or C code to generate the assembler
1912: output, all wrapped up in a @samp{define_insn} expression.
1913:
1914: Sometimes an insn can match more than one instruction pattern. Then the
1915: pattern that appears first in the machine description is the one used.
1916: Therefore, more specific patterns should usually go first in the
1917: description.
1918:
1919: The @samp{define_insn} expression contains four operands:
1920:
1921: @enumerate
1922: @item
1923: An optional name. The presence of a name indicate that this instruction
1924: pattern can perform a certain standard job for the RTL-generation
1925: pass of the compiler. This pass knows certain names and will use
1926: the instruction patterns with those names, if the names are defined
1927: in the machine description.
1928:
1929: The absence of a name is indicated by writing an empty string
1930: where the name should go. Nameless instruction patterns are never
1931: used for generating RTL code, but they may permit several simpler insns
1932: to be combined later on.
1933:
1934: Names that are not thus known and used in RTL-generation have no
1935: effect; they are equivalent to no name at all.
1936:
1937: @item
1938: The recognition template. This is a vector of incomplete RTL
1939: expressions which show what the instruction should look like. It is
1940: incomplete because it may contain @samp{match_operand} and
1941: @samp{match_dup} expressions that stand for operands of the
1942: instruction.
1943:
1944: If the vector has only one element, that element is what the
1945: instruction should look like. If the vector has multiple elements,
1946: then the instruction looks like a @samp{parallel} expression
1947: containing that many elements as described.
1948:
1949: @item
1950: A condition. This is a string which contains a C expression that is
1951: the final test to decide whether an insn body matches this pattern.
1952:
1953: For a named pattern, the condition (if present) may not depend on
1954: the data in the insn being matched, but only the target-machine-type
1955: flags. The compiler needs to test these conditions during
1956: initialization in order to learn exactly which named instructions are
1957: available in a particular run.
1958:
1959: For nameless patterns, the condition is applied only when matching an
1960: individual insn, and only after the insn has matched the pattern's
1961: recognition template. The insn's operands may be found in the vector
1962: @code{operands}.
1963:
1964: @item
1965: A string that says how to output matching insns as assembler code. In
1966: the simpler case, the string is an output template, much like a
1967: @code{printf} control string. @samp{%} in the string specifies where
1968: to insert the operands of the instruction; the @samp{%} is followed by
1969: a single-digit operand number.
1970:
1971: @samp{%c@var{digit}} can be used to subtitute an operand that is a
1972: constant value without the syntax that normally indicates an immediate
1973: operand.
1974:
1975: @samp{%a@var{digit}} can be used to substitute an operand as if it
1976: were a memory reference, with the actual operand treated as the address.
1977: This may be useful when outputting a ``load address'' instruction,
1978: because often the assembler syntax for such an instruction requires
1979: you to write the operand as if it were a memory reference.
1980:
1981: The template may generate multiple assembler instructions.
1982: Write the text for the instructions, with @samp{\;} between them.
1983:
1984: If the output control string starts with a @samp{*}, then it is not an
1985: output template but rather a piece of C program that should compute a
1986: template. It should execute a @code{return} statement to return the
1987: template-string you want. Most such templates use C string literals,
1988: which require doublequote characters to delimit them. To include
1989: these doublequote characters in the string, prefix each one with
1990: @samp{\}.
1991:
1992: The operands may be found in the array @code{operands}, whose C
1993: data type is @code{rtx []}.
1994:
1995: It is possible to output an assembler instruction and then go on to
1996: output or compute more of them, using the subroutine
1997: @code{output_asm_insn}. This receives two arguments: a
1998: template-string and a vector of operands. The vector may be
1999: @code{operands}, or it may be another array of @code{rtx} that you
2000: declare locally and initialize yourself.
2001: @end enumerate
2002:
2003: The recognition template is used also, for named patterns, for
2004: constructing insns. Construction involves substituting specified
2005: operands into a copy of the template. Matching involves determining
2006: the values that serve as the operands in the insn being matched. Both
2007: of these activities are controlled by two special expression types
2008: that direct matching and substitution of the operands.
2009:
2010: @table @code
2011: @item (match_operand:@var{m} @var{n} @var{testfn} @var{constraint})
2012: This expression is a placeholder for operand number @var{n} of
2013: the insn. When constructing an insn, operand number @var{n}
2014: will be substituted at this point. When matching an insn, whatever
2015: appears at this position in the insn will be taken as operand
2016: number @var{n}; but it must satisfy @var{testfn} or this instruction
2017: pattern will not match at all.
2018:
2019: Operand numbers must be chosen consecutively counting from zero in
2020: each instruction pattern. There may be only one @samp{match_operand}
2021: expression in the pattern for each expression number, and they must
2022: appear in order of increasing expression number.
2023:
2024: @var{testfn} is a string that is the name of a C function that accepts
2025: two arguments, a machine mode and an expression. During matching,
2026: the function will be called with @var{m} as the mode argument
2027: and the putative operand as the other argument. If it returns zero,
2028: this instruction pattern fails to match. @var{testfn} may be
2029: an empty string; then it means no test is to be done on the operand.
2030:
2031: Most often, @var{testfn} is @code{"general_operand"}. It checks
2032: that the putative operand is either a constant, a register or a
2033: memory reference, and that it is valid for mode @var{m}.
2034:
2035: @var{constraint} is explained later.
2036:
2037: @item (match_dup @var{n})
2038: This expression is also a placeholder for operand number @var{n}.
2039: It is used when the operand needs to appear more than once in the
2040: insn.
2041:
2042: In construction, @samp{match_dup} behaves exactly like
2043: @var{match_operand}: the operand is substituted into the insn being
2044: constructed. But in matching, @samp{match_dup} behaves differently.
2045: It assumes that operand number @var{n} has already been determined by
2046: a @samp{match_operand} apparing earlier in the recognition template,
2047: and it matches only an identical-looking expression.
2048:
2049: @item (address (match_operand:@var{m} @var{n} "address_operand" ""))
2050: This complex of expressions is a placeholder for an operand number
2051: @var{n} in a ``load address'' instruction: an operand which specifies
2052: a memory location in the usual way, but for which the actual operand
2053: value used is the address of the location, not the contents of the
2054: location.
2055:
2056: @samp{address} expressions never appear in RTL code, only in machine
2057: descriptions. And they are used only in machine descriptions that do
2058: not use the operand constraint feature. When operand constraints are
2059: in use, the letter @samp{p} in the constraint serves this purpose.
2060:
2061: @var{m} is the machine mode of the @emph{memory location being
2062: addressed}, not the machine mode of the address itself. That mode is
2063: always the same on a given target machine (it is @code{Pmode}, which
2064: normally is @code{SImode}), so there is no point in mentioning it;
2065: thus, no machine mode is written in the @samp{address} expression. If
2066: some day support is added for machines in which addresses of different
2067: kinds of objects appear differently or are used differently (such as
2068: the PDP-10), different formats would perhaps need different machine
2069: modes and these modes might be written in the @samp{address}
2070: expression.
2071: @end table
2072:
2073: @node Example, Constraints, Patterns, Machine Desc
2074: @section Example of @samp{define_insn}
2075:
2076: Here is an actual example of an instruction pattern, for the 68000/68020.
2077:
2078: @example
2079: (define_insn "tstsi"
2080: [(set (cc0)
2081: (match_operand:SI 0 "general_operand" "rm"))]
2082: ""
2083: "*
2084: @{ if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
2085: return \"tstl %0\";
2086: return \"cmpl #0,%0\"; @}")
2087: @end example
2088:
2089: This is an instruction that sets the condition codes based on the value of
2090: a general operand. It has no condition, so any insn whose RTL description
2091: has the form shown may be handled according to this pattern. The name
2092: @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
2093: pass that, when it is necessary to test such a value, an insn to do so
2094: can be constructed using this pattern.
2095:
2096: The output control string is a piece of C code which chooses which
2097: output template to return based on the kind of operand and the specific
2098: type of CPU for which code is being generated.
2099:
2100: @samp{"rm"} is an operand constraint. Its meaning is explained below.
2101:
2102: @node Constraints, Standard Names, Example, Machine Desc
2103: @section Operand Constraints
2104:
2105: Each @samp{match_operand} in an instruction pattern can specify a
2106: constraint for the type of operands allowed. Constraints can say whether
2107: an operand may be in a register, and which kinds of register; whether the
2108: operand can be a memory reference, and which kinds of address; whether the
2109: operand may be an immediate constant, and which possible values it may
2110: have. Constraints can also require two operands to match.
2111:
2112: @menu
2113: * Simple Constraints:: Basic use of constraints.
2114: * Multi-alternative:: When an insn has two alternative constraint-patterns.
2115: * Class Preferences:: Constraints guide which hard register to put things in.
2116: * Modifiers:: More precise control over effects of constraints.
2117: * No Constraints:: Describing a clean machine without constraints.
2118: @end menu
2119:
2120: @node Simple Constraints, Multi-Alternative, Constraints, Constraints
2121: @subsection Simple Constraints
2122:
2123: The simplest kind of constraint is a string full of letters, each of
2124: which describes one kind of operand that is permitted. Here are
2125: the letters that are allowed:
2126:
2127: @table @samp
2128: @item m
2129: A memory operand is allowed, with any kind of address that the machine
2130: supports in general.
2131:
2132: @item o
2133: A memory operand is allowed, but only if the address is @dfn{offsetable}.
2134: This means that adding a small integer (actually, the width in bytes of the
2135: operand, as determined by its machine mode) may be added to the address
2136: and the result is also a valid memory address. For example, an address
2137: which is constant is offsetable; so is an address that is the sum of
2138: a register and a constant (as long as a slightly larger constant is also
2139: within the range of address-offsets supported by the machine); but an
2140: autoincrement or autodecrement address is not offsetable. More complicated
2141: indirect/indexed addresses may or may not be offsetable depending on the
2142: other addressing modes that the machine supports.
2143:
2144: @item <
2145: A memory operand with autodecrement addressing (either predecrement or
2146: postdecrement) is allowed.
2147:
2148: @item >
2149: A memory operand with autoincrement addressing (either preincrement or
2150: postincrement) is allowed.
2151:
2152: @item r
2153: A register operand is allowed provided that it is in a general register.
2154:
2155: @item d
2156: @itemx a
2157: @itemx f
2158: @itemx @dots{}
2159: Other letters can be defined in machine-dependent fashion to stand for
2160: particular classes of registers. @samp{d}, @samp{a} and @samp{f} are
2161: defined on the 68000/68020 to stand for data, address and floating point
2162: registers.
2163:
2164: @item i
2165: An immediate integer operand (one with constant value) is allowed.
2166:
2167: @item I
2168: @item J
2169: @item K
2170: @itemx @dots{}
2171: Other letters in the range @samp{I} through @samp{M} may be defined in a
2172: machine-dependent fashion to permit immediate integer operands with
2173: explicit integer values in specified ranges. For example, on the 68000,
2174: @samp{I} is defined to stand for the range of values 1 to 8. This is the
2175: range permitted as a shift count in the shift instructions.
2176:
2177: @item F
2178: An immediate floating operand (expression code @samp{const_double}) is
2179: allowed.
2180:
2181: @item G
2182: @itemx H
2183: @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
2184: permit immediate floating operands in particular ranges of values.
2185:
2186: @item s
2187: An immediate integer operand whose value is not an explicit integer is
2188: allowed. This might appear strange; if an insn allows a constant operand
2189: with a value not known at compile time, it certainly must allow any known
2190: value. So why use @samp{s} instead of @samp{i}? Sometimes it allows
2191: better code to be generated. For example, on the 68000 in a fullword
2192: instruction it is possible to use an immediate operand; but if the
2193: immediate value is between -32 and 31, better code results from loading the
2194: value into a register and using the register. This is because the load
2195: into the register can be done with a @samp{moveq} instruction. We arrange
2196: for this to happen by defining the letter @samp{K} to mean ``any integer
2197: outside the range -32 to 31'', and then specifying @samp{Ks} in the operand
2198: constraints.
2199:
2200: @item g
2201: Any register, memory or immediate integer operand is allowed, except for
2202: registers that are not general registers.
2203:
2204: @item @r{@var{n}, a digit}
2205: An operand identical to operand number @var{n} is allowed.
2206: If a digit is used together with letters, the digit should come last.
2207:
2208: @item p
2209: An operand that is a valid memory address is allowed. This is
2210: for ``load address'' and ``push address'' instructions.
2211:
2212: If @samp{p} is used in the constraint, the test-function in the
2213: @samp{match_operand} must be @code{address_operand}.
2214: @end table
2215:
2216: In order to have valid assembler code, each operand must satisfy
2217: its constraint. But a failure to do so does not prevent the pattern
2218: from applying to an insn. Instead, it directs the compiler to modify
2219: the code such that the constraint will be satisfied. Usually this is
2220: done by copying an operand into a register.
2221:
2222: Contrast, therefore, the two instruction patterns that follow:
2223:
2224: @example
2225: (define_insn ""
2226: [(set (match_operand:SI 0 "general_operand" "r")
2227: (plus:SI (match_dup 0)
2228: (match_operand:SI 1 "general_operand" "r")))]
2229: ""
2230: "@dots{}")
2231: @end example
2232:
2233: @noindent
2234: which has two operands, one of which must appear in two places, and
2235:
2236: @example
2237: (define_insn ""
2238: [(set (match_operand:SI 0 "general_operand" "r")
2239: (plus:SI (match_operand:SI 1 "general_operand" "0")
2240: (match_operand:SI 2 "general_operand" "r")))]
2241: ""
2242: "@dots{}")
2243: @end example
2244:
2245: @noindent
2246: which has three operands, two of which are required by a constraint to be
2247: identical. If we are considering an insn of the form
2248:
2249: @example
2250: (insn @var{n} @var{prev} @var{next}
2251: (set (reg:SI 3)
2252: (plus:SI (reg:SI 6) (reg:SI 109)))
2253: @dots{})
2254: @end example
2255:
2256: @noindent
2257: the first pattern would not apply at all, because this insn does not
2258: contain two identical subexpressions in the right place. The pattern would
2259: say, ``That does not look like an add instruction; try other patterns.''
2260: The second pattern would say, ``Yes, that's an add instruction, but there
2261: is something wrong with it.'' It would direct the reload pass of the
2262: compiler to generate additional insns to make the constraint true. The
2263: results might look like this:
2264:
2265: @example
2266: (insn @var{n2} @var{prev} @var{n}
2267: (set (reg:SI 3) (reg:SI 6))
2268: @dots{})
2269:
2270: (insn @var{n} @var{n2} @var{next}
2271: (set (reg:SI 3)
2272: (plus:SI (reg:SI 3) (reg:SI 109)))
2273: @dots{})
2274: @end example
2275:
2276: Because insns that don't fit the constraints are fixed up by loading
2277: operands into registers, every instruction pattern's constraints must
2278: permit the case where all the operands are in registers. It need not
2279: permit all classes of registers; the compiler knows how to copy registers
2280: into other registers of the proper class in order to make an instruction
2281: valid. But if no registers are permitted, the compiler will be stymied: it
2282: does not know how to save a register in memory in order to make an
2283: instruction valid. Instruction patterns that reject registers can be
2284: made valid by attaching a condition-expression that refuses to match
2285: an insn at all if the crucial operand is a register.
2286:
2287: @node Multi-Alternative, Class Preferences, Simple Constraints, Constraints
2288: @subsection Multiple Alternative Constraints
2289:
2290: Sometimes a single instruction has multiple alternative sets of possible
2291: operands. For example, on the 68000, a logical-or instruction can combine
2292: register or an immediate value into memory, or it can combine any kind of
2293: operand into a register; but it cannot combine one memory location into
2294: another.
2295:
2296: These constraints are represented as multiple alternatives. An alternative
2297: can be described by a series of letters for each operand. The overall
2298: constraint for an operand is made from the letters for this operand
2299: from the first alternative, a comma, the letters for this operand from
2300: the second alternative, a comma, and so on until the last alternative.
2301: Here is how it is done for fullword logical-or on the 68000:
2302:
2303: @example
2304: (define_insn "iorsi3"
2305: [(set (match_operand:SI 0 "general_operand" "=%m,d")
2306: (ior:SI (match_operand:SI 1 "general_operand" "0,0")
2307: (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
2308: @dots{})
2309: @end example
2310:
2311: The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
2312: operand 1 (meaning it must match operand 0), and @samp{dKs} for operand 2.
2313: The second alternative has @samp{d} (data register) for operand 0, @samp{0}
2314: for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and @samp{%} in
2315: the constraint for operand 0 are not part of any alternative; their meaning
2316: is explained in the next section.
2317:
2318: If all the operands fit any one alternative, the instruction is valid.
2319: Otherwise, for each alternative, the compiler counts how many instructions
2320: must be added to copy the operands so that that alternative applies.
2321: The alternative requiring the least copying is chosen. If two alternatives
2322: need the same amount of copying, the one that comes first is chosen.
2323: These choices can be altered with the @samp{?} and @samp{!} characters:
2324:
2325: @table @samp
2326: @item ?
2327: Disparage slightly the alternative that the @samp{?} appears in,
2328: as a choice when no alternative applies exactly. The compiler regards
2329: this alternative as one unit more costly for each @samp{?} that appears
2330: in it.
2331:
2332: @item !
2333: Disparage severely the alternative that the @samp{!} appears in.
2334: When operands must be copied into registers, the compiler will
2335: never choose this alternative as the one to strive for.
2336: @end table
2337:
2338: @node Class Preferences, Modifiers, Multi-Alternative, Constraints
2339: @subsection Register Class Preferences
2340:
2341: The operand constraints have another function: they enable the compiler
2342: to decide which kind of hardware register a pseudo register is best
2343: allocated to. The compiler examines the constraints that apply to the
2344: insns that use the pseudo register, looking for the machine-dependent
2345: letters such as @samp{d} and @samp{a} that specify classes of registers.
2346: The pseudo register is put in whichever class gets the most ``votes''.
2347: The constraint letters @samp{g} and @samp{r} also vote: they vote in
2348: favor of a general register. The machine description says which registers
2349: are considered general.
2350:
2351: Of course, on some machines all registers are equivalent, and no register
2352: classes are defined. Then none of this complexity is relevant.
2353:
2354: @node Modifiers, No Constraints, Class Preferences, Constraints
2355: @subsection Constraint Modifier Characters
2356:
2357: @table @samp
2358: @item =
2359: Means that this operand is written by the instruction, but its previous
2360: value is not used.
2361:
2362: @item +
2363: Means that this operand is both read and written by the instruction.
2364:
2365: When the compiler fixes up the operands to satisfy the constraints,
2366: it needs to know which operands are inputs to the instruction and
2367: which are outputs from it. @samp{=} identifies an output; @samp{+}
2368: identifies an operand that is both input and output; all other operands
2369: are assumed to be input only.
2370:
2371: @item %
2372: Declares the instruction to be commutative for operands 1 and 2.
2373: This means that the compiler may interchange operands 1 and 2
2374: if that will make the operands fit their constraints.
2375:
2376: @item #
2377: Says that all following characters, up to the next comma, are to be ignored
2378: as a constraint. They are significant only for choosing register preferences.
2379:
2380: @item *
2381: Says that the following character should be ignored when choosing
2382: register preferences. @samp{*} has no effect on the meaning of
2383: the constraint as a constraint.
2384: @end table
2385:
2386: @node No Constraints,, Modifiers, Constraints
2387: @subsection Not Using Constraints
2388:
2389: Some machines are so clean that operand constraints are not required. For
2390: example, on the Vax, an operand valid in one context is valid in any other
2391: context. On such a machine, every operand constraint would be @samp{"g"},
2392: excepting only operands of ``load address'' instructions which are
2393: written as if they referred to a memory location's contents but actual
2394: refer to its address. They would have constraint @samp{"p"}.
2395:
2396: For such machines, instead of writing @samp{"g"} and @samp{"p"} for all
2397: the constraints, you can choose to write a description with empty constraints.
2398: Then you write @samp{""} for the constraint in every @samp{match_operand}.
2399: Address operands are identified by writing an @samp{address} expression
2400: around the @samp{match_operand}, not by their constraints.
2401:
2402: When the machine description has just empty constraints, certain parts
2403: of compilation are skipped, making the compiler faster.
2404:
2405: @node Standard Names, Dependent Patterns, Constraints, Machine Desc
2406: @section Standard Insn Names
2407:
2408: Here is a table of the instruction names that are meaningful in the RTL
2409: generation pass of the compiler. Giving one of these names to an
2410: instruction pattern tells the RTL generation pass that it can use the
2411: pattern in to accomplish a certain task.
2412:
2413: @table @samp
2414: @item mov@var{m}
2415: Here @var{m} is a two-letter machine mode name, in lower case. This
2416: instruction pattern moves data with that machine mode from operand 1 to
2417: operand 0. For example, @samp{movsi} moves full-word data.
2418:
2419: If operand 0 is a @samp{subreg} with mode @var{m} of a register whose
2420: natural mode is wider than @var{m}, the effect of this instruction is
2421: to store the specified value in the part of the register that corresponds
2422: to mode @var{m}. The effect on the rest of the register is undefined.
2423:
2424: @item movstrict@var{m}
2425: Like @samp{mov@var{m}} except that if operand 0 is a @samp{subreg}
2426: with mode @var{m} of a register whose natural mode is wider,
2427: the @samp{movstrict@var{m}} instruction is guaranteed not to alter
2428: any of the register except the part which belongs to mode @var{m}.
2429:
2430: @item add@var{m}3
2431: Add operand 2 and operand 1, storing the result in operand 0. All operands
2432: must have mode @var{m}. This can be used even on two-address machines, by
2433: means of constraints requiring operands 1 and 0 to be the same location.
2434:
2435: @item sub@var{m}3
2436: @itemx mul@var{m}3
2437: @itemx umul@var{m}3
2438: @itemx div@var{m}3
2439: @itemx udiv@var{m}3
2440: @itemx mod@var{m}3
2441: @itemx umod@var{m}3
2442: @itemx and@var{m}3
2443: @itemx ior@var{m}3
2444: @itemx xor@var{m}3
2445: Similar, for other arithmetic operations.
2446:
2447: @item andcb@var{m}3
2448: Bitwise logical-and operand 1 with the complement of operand 2
2449: and store the result in operand 0.
2450:
2451: @item mulhisi3
2452: Multiply operands 1 and 2, which have mode @code{HImode}, and store
2453: a @code{SImode} product in operand 0.
2454:
2455: @item mulqihi3
2456: @itemx mulsidi3
2457: Similar widening-multiplication instructions of other widths.
2458:
2459: @item umulqihi3
2460: @item umulhisi3
2461: @item umulsidi3
2462: Similar widening-multiplication instructions that do unsigned
2463: multiplication.
2464:
2465: @item divmod@var{m}4
2466: Signed division that produces both a quotient and a remainder.
2467: Operand 1 is divided by operand 2 to produce a quotient stored
2468: in operand 0 and a remainder stored in operand 3.
2469:
2470: @item udivmod@var{m}4
2471: Similar, but does unsigned division.
2472:
2473: @item divmod@var{m}@var{n}4
2474: Like @samp{divmod@var{m}4} except that only the dividend has mode
2475: @var{m}; the divisor, quotient and remainder have mode @var{n}.
2476: For example, the Vax has a @samp{divmoddisi4} instruction
2477: (but it is omitted from the machine description, because it
2478: is so slow that it is faster to compute remainders by the
2479: circumlocution that the compiler will use if this instruction is
2480: not available).
2481:
2482: @item ashl@var{m}3
2483: Arithmetic-shift operand 1 left by a number of bits specified by
2484: operand 2, and store the result in operand 0. Operand 2 has
2485: mode @code{SImode}, not mode @var{m}.
2486:
2487: @item ashr@var{m}3
2488: @itemx lshl@var{m}3
2489: @itemx lshr@var{m}3
2490: @itemx rotl@var{m}3
2491: @itemx rotr@var{m}3
2492: Other shift and rotate instructions.
2493:
2494: @item neg@var{m}2
2495: Negate operand 1 and store the result in operand 0.
2496:
2497: @item abs@var{m}2
2498: Store the absolute value of operand 1 into operand 0.
2499:
2500: @item sqrt@var{m}2
2501: Store the square root of operand 1 into operand 0.
2502:
2503: @item one_cmpl@var{m}2
2504: Store the bitwise-complement of operand 1 into operand 0.
2505:
2506: @item cmp@var{m}
2507: Compare operand 0 and operand 1, and set the condition codes.
2508:
2509: @item tst@var{m}
2510: Compare operand 0 against zero, and set the condition codes.
2511:
2512: @item movstr@var{m}
2513: Block move instruction. The addresses of the destination and source
2514: strings are the first two operands, and both are in mode @code{Pmode}.
2515: The number of bytes to move is the third operand, in mode @var{m}.
2516:
2517: @item cmpstr@var{m}
2518: Block compare instruction, with operands like @samp{movstr@var{m}}
2519: except that the two memory blocks are compared byte by byte
2520: in lexicographic order. The effect of the instruction is to set
2521: the condition codes.
2522:
2523: @item float@var{m}@var{n}2
2524: Convert operand 1 (valid for floating point mode @var{m}) to fixed
2525: point mode @var{n} and store in operand 0 (which has mode @var{n}).
2526:
2527: @item fix@var{m}@var{n}2
2528: Convert operand 1 (valid for fixed point mode @var{m}) to floating
2529: point mode @var{n} and store in operand 0 (which has mode @var{n}).
2530:
2531: @item trunc@var{m}@var{n}
2532: Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
2533: store in operand 0 (which has mode @var{n}). Both modes must be fixed
2534: point or both floating point.
2535:
2536: @item extend@var{m}@var{n}
2537: Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
2538: store in operand 0 (which has mode @var{n}). Both modes must be fixed
2539: point or both floating point.
2540:
2541: @item zero_extend@var{m}@var{n}
2542: Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
2543: store in operand 0 (which has mode @var{n}). Both modes must be fixed
2544: point.
2545:
2546: @item extv
2547: Extract a bit-field from operand 1 (a register or memory operand),
2548: where operand 2 specifies the width in bits and operand 3 the starting
2549: bit, and store it in operand 0. Operand 0 must have @code{Simode}.
2550: Operand 1 may have mode @code{QImode} or @code{SImode}; often
2551: @code{SImode} is allowed only for registers. Operands 2 and 3 must be
2552: valid for @code{SImode}.
2553:
2554: The RTL generation pass generates this instruction only with constants
2555: for operands 2 and 3.
2556:
2557: The bit-field value is sign-extended to a full word integer
2558: before it is stored in operand 0.
2559:
2560: @item extzv
2561: Like @samp{extv} except that the bit-field value is zero-extended.
2562:
2563: @item insv
2564: Store operand 3 (which must be valid for @code{SImode}) into a
2565: bit-field in operand 0, where operand 1 specifies the width in bits
2566: and operand 2 the starting bit. Operand 0 may have mode @code{QImode}
2567: or @code{SImode}; often @code{SImode} is allowed only for registers.
2568: Operands 1 and 2 must be valid for @code{SImode}.
2569:
2570: The RTL generation pass generates this instruction only with constants
2571: for operands 1 and 2.
2572:
2573: @item s@var{cond}@var{m}
2574: Store zero or -1 in the operand (with mode @var{m}) according to the
2575: condition codes. Value stored is -1 iff the condition @var{cond} is
2576: true. @var{cond} is the name of a comparison operation rtx code, such
2577: as @samp{eq}, @samp{lt} or @samp{leu}.
2578:
2579: @item b@var{cond}
2580: Conditional branch instruction. Operand 0 is a @samp{label_ref}
2581: that refers to the label to jump to. Jump if the condition codes
2582: meet condition @var{cond}.
2583:
2584: @item call
2585: Subroutine call instruction. Operand 1 is the number of arguments
2586: and operand 0 is the function to call. Operand 1 should be a @samp{mem}
2587: rtx whose address is the address of the function.
2588:
2589: @item return
2590: Subroutine return instruction. This instruction pattern name should be
2591: defined only if a single instruction can do all the work of returning
2592: from a function.
2593:
2594: @item tablejump
2595: @item case@var{m}
2596: @end table
2597:
2598: @node Dependent Patterns,, Standard Names, Machine Desc
2599: @section Patterns Require Other Patterns
2600:
2601: Every machine description must have a named pattern for each of the
2602: conditional branch names @samp{b@var{cond}}. The recognition template
2603: must always have the form
2604:
2605: @example
2606: (set (pc)
2607: (if_then_else (@var{cond} (cc0) (const_int 0))
2608: (label_ref (match_operand 0 "" ""))
2609: (pc)))
2610: @end example
2611:
2612: @noindent
2613: In addition, every machine description must have an anonymous pattern
2614: for each of the possible reverse-conditional branches. These patterns
2615: look like
2616:
2617: @example
2618: (set (pc)
2619: (if_then_else (@var{cond} (cc0) (const_int 0))
2620: (pc)
2621: (label_ref (match_operand 0 "" ""))))
2622: @end example
2623:
2624: @noindent
2625: They are necessary because jump optimization can turn direct-conditional
2626: branches into reverse-conditional branches.
2627:
2628: The compiler does more with RTL than just create it from patterns
2629: and recognize the patterns: it can perform arithmetic expression codes
2630: when constant values for their operands can be determined. As a result,
2631: sometimes having one pattern can require other patterns. For example, the
2632: Vax has no `and' instruction, but it has `and not' instructions. Here
2633: is the definition of one of them:
2634:
2635: @example
2636: (define_insn "andcbsi2"
2637: [(set (match_operand:SI 0 "general_operand" "")
2638: (and:SI (match_dup 0)
2639: (not:SI (match_operand:SI
2640: 1 "general_operand" ""))))]
2641: ""
2642: "bicl2 %1,%0")
2643: @end example
2644:
2645: @noindent
2646: If operand 1 is an explicit integer constant, an instruction constructed
2647: using that pattern can end up looking like
2648:
2649: @example
2650: (set (reg:SI 41)
2651: (and:SI (reg:SI 41)
2652: (const_int 0xffff7fff)))
2653: @end example
2654:
2655: @noindent
2656: (where the integer constant is the one's complement of what
2657: appeared in the original instruction).
2658:
2659: To avoid a fatal error, the compiler must have a pattern that recognizes
2660: such an instruction. Here is what is used:
2661:
2662: @example
2663: (define_insn ""
2664: [(set (match_operand:SI 0 "general_operand" "")
2665: (and:SI (match_dup 0)
2666: (match_operand:SI 1 "general_operand" "")))]
2667: "GET_CODE (operands[1]) == CONST_INT"
2668: "*
2669: { operands[1]
2670: = gen_rtx (CONST_INT, VOIDmode, ~INTVAL (operands[1]));
2671: return \"bicl2 %1,%0\";
2672: }")
2673: @end example
2674:
2675: @noindent
2676: Whereas a pattern to match a general `and' instruction is impossible to
2677: support on the Vax, this pattern is possible because it matches only a
2678: constant second argument: a special case that can be output as an `and not'
2679: instruction.
2680:
2681: @node Machine Macros,, Machine Desc, Top
2682: @chapter Machine Description Macros
2683:
2684: The other half of the machine description is a C header file conventionally
2685: given the name @file{tm-@var{machine}.h}. The file @file{tm.h} should be a
2686: link to it. The header file @file{config.h} includes @file{tm.h} and most
2687: compiler source files include @file{config.h}.
2688:
2689: @menu
2690: * Run-time Target:: Defining -m switches like -m68000 and -m68020.
2691: * Storage Layout:: Defining sizes and alignments of data types.
2692: * Registers:: Naming and describing the hardware registers.
2693: * Register Classes:: Defining the classes of hardware registers.
2694: * Stack Layout:: Defining which way the stack grows and by how much.
2695: * Addressing Modes:: Defining addressing modes valid for memory operands.
2696: * Condition Code:: Defining how insns update the condition code.
2697: * Assembler Format:: Defining how to write insns and pseudo-ops to output.
2698: * Misc:: Everything else.
2699: @end menu
2700:
2701: @node Run-time Target, Storage Layout, Machine Macros, Machine Macros
2702: @section Run-time Target Specification
2703:
2704: @table @code
2705: @item CPP_PREDEFINES
2706: Define this to be a string constant containing @samp{-D} switches
2707: to define the predefined macros that identify this machine and system.
2708:
2709: For example, on the Sun, one can use the value
2710:
2711: @example
2712: "-Dmc68000 -Dsun"
2713: @end example
2714:
2715: @item extern int target_flags;
2716: This declaration should be present.
2717:
2718: @item TARGET_@dots{}
2719: This series of macros is to allow compiler command arguments to
2720: enable or disable the use of optional features of the target machine.
2721: For example, one machine description serves both the 68000 and
2722: the 68020; a command argument tells the compiler whether it should
2723: use 68020-only instructions or not. This command argument works
2724: by means of a macro @code{TARGET_68020} that tests a bit in
2725: @code{target_flags}.
2726:
2727: Define a macro @code{TARGET_@var{featurename}} for each such option.
2728: Its definition should test a bit in @code{target_flags}; for example:
2729:
2730: @example
2731: #define TARGET_68020 (target_flags & 1)
2732: @end example
2733:
2734: One place where these macros are used is in the condition-expressions
2735: of instruction patterns. Note how @code{TARGET_68020} appears
2736: frequently in the 68000 machine description file, @file{m68000.md}.
2737: Another place they are used is in the definitions of the other
2738: macros in the @file{tm-@var{machine}.h} file.
2739:
2740: @item TARGET_SWITCHES
2741: This macro defines names of command switches to set and clear
2742: bits in @code{target_flags}. Its definition is an initializer
2743: with a subgrouping for each command switches.
2744:
2745: Each subgrouping contains a string constant, that defines the switch
2746: name, and a number, which contains the bits to set in
2747: @code{target_flags}. A negative number says to clear bits instead;
2748: the negative of the number is which bits to clear. The actual switch
2749: name is made by appending @samp{-m} to the specified name.
2750:
2751: One of the subgroupings should have a null string. The number in
2752: this grouping is the default value for @code{target_flags}. Any
2753: target switches act starting with that value.
2754:
2755: Here is an example which defines @samp{-m68000} and @samp{-m68020}
2756: with opposite meanings, and picks the latter as the default:
2757:
2758: @example
2759: #define TARGET_SWITCHES \
2760: @{ @{ "68020", 1@}, \
2761: @{ "68000", -1@}, \
2762: @{ "", 1@}@}
2763: @end example
2764: @end table
2765:
2766: @node Storage Layout, Registers, Run-time Target, Machine Macros
2767: @section Storage Layout
2768:
2769: @table @code
2770: @item BITS_BIG_ENDIAN
2771: Define this macro if the most significant bit in a byte has the lowest
2772: number. This means that bit-field instructions count from the most
2773: significant bit. If the machine has no bit-field instructions, this
2774: macro is irrelevant.
2775:
2776: @item BYTES_BIG_ENDIAN
2777: Define this macro if the most significant byte in a word has the
2778: lowest number.
2779:
2780: @item WORDS_BIG_ENDIAN
2781: Define this macro if, in a multiword object, the most signficant
2782: word has the lowest number.
2783:
2784: @item BITS_PER_UNIT
2785: Number of bits in an addressable storage unit (byte); normally 8.
2786:
2787: @item BITS_PER_WORD
2788: Number of bits in a word; normally 32.
2789:
2790: @item UNITS_PER_WORD
2791: Number of storage units in a word; normally 4.
2792:
2793: @item POINTER_SIZE
2794: Width of a pointer, in bits.
2795:
2796: @item PARM_BOUNDARY
2797: Alignment required for pointers, in bits.
2798:
2799: @item FUNCTION_BOUNDARY
2800: Alignment required for a function entry point, in bits.
2801:
2802: @item BIGGEST_ALIGNMENT
2803: Biggest alignment that anything can require on this machine, in bits.
2804:
2805: @item STRICT_ALIGNMENT
2806: Define this if instructions will fail to work if given data not
2807: on the nominal alignment. If instructions will merely go slower
2808: in that case, do not define this macro.
2809: @end table
2810:
2811: @node Registers, Register Classes, Storage Layout, Machine Macros
2812: @section Register Usage
2813:
2814: @table @code
2815: @item FIRST_PSEUDO_REGISTER
2816: Number of hardware registers known to the compiler. They receive
2817: numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
2818: pseudo register's number really is assigned the number7
2819: @code{FIRST_PSEUDO_REGISTER}.
2820:
2821: @item FIXED_REGISTERS
2822: An initializer that says which registers are used for fixed purposes
2823: all throughout the compiled code and are therefore not available for
2824: general allocation. These would inclue the stack pointer, the frame
2825: pointer, the program counter on machines where that is considered one
2826: of the addressable registers, and any other numbered register with a
2827: standard use.
2828:
2829: This information is expressed as a sequence of numbers, separated by
2830: commas and surrounded by braces. The @var{n}th number is 1 if
2831: register @var{n} is fixed, 0 otherwise
2832:
2833: @item CALL_USED_REGISTERS
2834: Like @code{FIXED_REGISTERS} but has 1 for each register that is
2835: clobbered (in general) by function calls as well as for fixed
2836: registers. This macro therefore identifies the registers that are not
2837: available for general allocation of values that must live across
2838: function calls.
2839:
2840: If a registers has 0 in @code{CALL_USED_REGISTERS}, the compiler
2841: automatically saves it on function entry and restores it on function
2842: exit, if the register is used within the function.
2843:
2844: @item HARD_REGNO_REGS (@var{regno}, @var{mode})
2845: A C expression for the number of consecutive hard registers, starting
2846: at register number @var{regno}, required to hold a value of mode
2847: @var{mode}.
2848:
2849: On a machine where all registers are exactly one word, a suitable
2850: definition of this macro is
2851:
2852: @example
2853: #define HARD_REGNO_NREGS(REGNO, MODE) \
2854: ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \
2855: / UNITS_PER_WORD))
2856: @end example
2857:
2858: @item HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
2859: A C expression that is nonzero if it is permissible to store a value
2860: of mode @var{mode} in hard register number @var{regno} (or in several
2861: registers starting with that one). For a machine where all registers
2862: are equivalent, a suitable definition is
2863:
2864: @example
2865: #define HARD_REGNO_MODE_OK(REGNO, MODE) 1
2866: @end example
2867:
2868: It is not necessary for this macro to check for fixed register numbers
2869: because the allocation mechanism considers them to be always occupied.
2870:
2871: @item MODES_TIEABLE_P (@var{mode1}, @var{mode2})
2872: A C expression that is nonzero if it is desirable to choose register
2873: allocation so as to avoid move instructions between a value of mode
2874: @var{mode1} and a value of mode @var{mode2}.
2875:
2876: If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
2877: @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different
2878: for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1},
2879: @var{mode2})} must be zero.
2880:
2881: @item PC_REGNUM
2882: If the program counter has a register number, define this as that
2883: register number. Otherwise, do not define it.
2884:
2885: @item STACK_POINTER_REGNUM
2886: The register number of the stack pointer register, which must also be
2887: a fixed register according to @code{FIXED_REGISTERS}. On many
2888: machines, the hardware determines which register this is.
2889:
2890: @item FRAME_POINTER_REGNUM
2891: The register number of the frame pointer register, which is used to
2892: access automatic variables in the stack frame. It must also described
2893: in @code{FIXED_REGISTERS} as a fixed register. On some machines, the
2894: hardware determines which register this is. On other machines, you
2895: can choose any register you wish for this purpose.
2896:
2897: @item ARG_POINTER_REGNUM
2898: The register number of the arg pointer register, which is used to
2899: access the function's argument list. On some machines, this is the
2900: same as the frame pointer register. On some machines, the hardware
2901: determines which register this is. On other machines, you can choose
2902: any register you wish for this purpose. It must in any case be a
2903: fixed register according to @code{FIXED_REGISTERS}.
2904:
2905: @item STATIC_CHAIN_REGNUM
2906: The register number used for passing a function's static chain
2907: pointer. This is needed for languages such as Pascal and Algol where
2908: functions defined within other functions can access the local
2909: variables of the outer functions; it is not currently used because C
2910: does not provide this feature.
2911:
2912: The static chain register need not be a fixed register.
2913:
2914: @item FUNCTION_VALUE_REGNUM
2915: The register number used for returning values from a function. This
2916: must be one of the call-used registers (since function calls alter
2917: it!) but should not be a fixed register. When the value being
2918: returned has a multi-word machine mode, multiple consecutive registers
2919: starting with the specified one are used.
2920:
2921: @item STRUCT_VALUE_REGNUM
2922: When a function's value's mode is @code{BLKmode}, the value is not returned
2923: in the register @code{FUNCTION_VALUE_REGNUM}. Instead, the caller passes
2924: the address of a block of memory in which the value should be stored.
2925: @code{STRUCT_VALUE_REGNUM} is the register in which this address is passed.
2926: @end table
2927:
2928: @node Register Classes, Stack Layout, Registers, Machine Macros
2929: @section Register Classes
2930:
2931: On many machines, the numbered registers are not all equivalent.
2932: For example, certain registers may not be allowed for indexed addressing;
2933: certain registers may not be allowed in some instructions. These machine
2934: restrictions are described to the compiler using @dfn{register classes}.
2935:
2936: You define a number of register classes, giving each one a name and saying
2937: which of the registers belong to it. Then you can specify register classes
2938: that are allowed as operands to particular instruction patterns.
2939:
2940: In general, each register will belong to several classes. In fact, one
2941: class must be named @code{ALL_REGS} and contain all the registers. Another
2942: class must be named @code{NO_REGS} and contain no registers. Often the
2943: union of two classes will be another class; however, this is not required.
2944:
2945: One of the classes must be named @code{GENERAL_REGS}. There is nothing
2946: terribly special about the name, but the operand constraint letters
2947: @samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is
2948: the same as @code{ALL_REGS}, just define it as a macro which expands
2949: to @code{ALL_REGS}.
2950:
2951: The way classes other than @code{GENERAL_REGS} are specified in operand
2952: constraints is through machine-dependent operand constraint letters.
2953: You can define such letters to correspond to various classes, then use
2954: them in operand constraints.
2955:
2956: You must also specify certain redundant information about the register
2957: classes: for each class, which classes contain it and which ones are
2958: contained in it; for each pair of classes, the largest class contained
2959: in their union.
2960:
2961: @table @code
2962: @item enum reg_class
2963: An enumeral type that must be defined with all the register class names
2964: as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS}
2965: must be the last register class, followed by one more enumeral value,
2966: @code{LIM_REG_CLASSES}, which is not a register class but rather
2967: tells how many classes there are.
2968:
2969: Each register class has a number, which is the value of casting
2970: the class name to type @code{int}. The number serves as an index
2971: in many of the tables described below.
2972:
2973: @item REG_CLASS_NAMES
2974: An initializer containing the names of the register classes as C string
2975: constants. These names are used in writing some of the debugging dumps.
2976:
2977: @item REG_CLASS_CONTENTS
2978: An initializer containing the contents of the register classes, as integers
2979: which are bit masks. The @var{n}th integer specifies the contents of class
2980: @var{n}. The way the integer @var{mask} is interpreted is that
2981: register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
2982:
2983: When the machine has more than 32 registers, an integer does not suffice.
2984: Then the integers are replaced by sub-initializers, braced groupings containing
2985: several integers. Each sub-initializer must be suitable as an initializer
2986: for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
2987:
2988: @item REGNO_REG_CLASS (@var{regno})
2989: A C expression whose value is a register class containing hard register
2990: @var{regno}. In general there is more that one such class; choose a class
2991: which is @dfn{minimal}, meaning that no smaller class also contains the
2992: register.
2993:
2994: @item REG_CLASS_SUPERCLASSES
2995: A two-level initializer that says, for each class, which classes contain
2996: it. The @var{n}th element of the initializer is a sub-initializer for
2997: class @var{n}; it contains the names of the othe classes that contain class
2998: @var{n} (but not the name of class @var{n} itself), followed by
2999: @code{LIM_REG_CLASSES} to mark the end of the element.
3000:
3001: @item REG_CLASS_SUBCLASSES
3002: Similar to @code{REG_CLASS_SUPERCLASSES}, except that element @var{n} lists
3003: the classes @emph{contained in} class @var{n}, followed once again by
3004: @code{LIM_REG_CLASSES} to mark the end of the element.
3005:
3006: @item REG_CLASS_SUBUNION
3007: An two-level initializer for a two-dimensional array. The element
3008: (@var{m}, @var{n}) of this array must be a class that is ``close to''
3009: being the union of classes @var{m} and @var{n}. If there is a class
3010: that is exactly that union, use it; otherwise, choose some smaller
3011: class, preferably as large as possible but certainly not containing
3012: any register that is neither in class @var{m} nor in class @var{n}.
3013:
3014: @item INDEX_REG_CLASS
3015: A macro whose definition is the name of the class to which a valid index
3016: register must belong.
3017:
3018: @item REG_CLASS_FROM_LETTER (@var{char})
3019: A C expression which defines the machine-dependent operand constraint
3020: letters for register classes. If @var{char} is such a letter, the value
3021: should be the register class corresponding to it. Otherwise, the value
3022: should be @code{NO_REGS}.
3023:
3024: @item REGNO_OK_FOR_CLASS_P (@var{regno}, @var{class})
3025: A C expression which is nonzero if register number @var{regno} is a hard
3026: register belonging to class @var{class}. The expression is always zero if
3027: @var{regno} is a pseudo register.
3028:
3029: @item REG_OK_FOR_CLASS_P (@var{reg}, @var{class})
3030: A C expression which is nonzero if @var{reg} (an rtx assumed to have
3031: code @samp{reg}) belongs to class @var{class}.
3032:
3033: What about pseudo registers? There are two alternatives, and the machine
3034: description header file must be able to do either one on command. If the
3035: macro @code{REG_OK_STRICT} is defined, this macro should be defined to
3036: reject all pseudo registers (return 0 for them). Otherwise, this macro
3037: should be defined to accept all pseudo registers (return 1 for them).
3038:
3039: Some source files of the compiler define @code{REG_OK_STRICT} before
3040: including the machine description header file, while others do not,
3041: according to the needs of that part of the compiler.
3042:
3043: @item PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
3044: A C expression that places additional restrictions on the register class
3045: to use when it is necessary to copy value @var{x} into a register in class
3046: @var{class}. The value is a register class; perhaps @var{class}, or perhaps
3047: another, smaller class. @var{class} is always safe as a value. In fact,
3048: the definition
3049:
3050: @example
3051: #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
3052: @end example
3053:
3054: @noindent
3055: is always safe. However, sometimes returning a more restrictive class
3056: makes better code. For example, on the 68000, when @var{x} is an
3057: integer constant that is in range for a @samp{moveq} instruction,
3058: the value of this macro is always @code{DATA_REGS} as long as
3059: @var{class} includes the data registers. Requiring a data register
3060: guarantees that a @samp{moveq} will be used.
3061: @end table
3062:
3063: Two other special macros
3064:
3065: @table @code
3066: @item CONST_OK_FOR_LETTER_P (@var{value}, @var{c})
3067: A C expression that defines the machine-dependent operand constraint letters
3068: that specify particular ranges of integer values. If @var{c} is one
3069: of those letters, the expression should check that @var{value}, an integer,
3070: is in the appropriate range and return 1 if so, 0 otherwise. If @var{c} is
3071: not one of those letters, the value should be 0 regardless of @var{value}.
3072:
3073: @item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c})
3074: A C expression that defines the machine-dependent operand constraint
3075: letters that specify particular ranges of floating values. If @var{c} is
3076: one of those letters, the expression should check that @var{value}, an rtx
3077: of code @samp{const_double}, is in the appropriate range and return 1 if
3078: so, 0 otherwise. If @var{c} is not one of those letters, the value should
3079: be 0 regardless of @var{value}.
3080: @end table
3081:
3082: @node Stack Layout, Addressing Modes, Register Classes, Machine Macros
3083: @section Describing Stack Layout
3084:
3085: @table @code
3086: @item STACK_GROWS_DOWNWARD
3087: Define this macro if pushing a word onto the stack moves the stack
3088: pointer to a smaller address. The definition is irrelevant because the
3089: compiler checks this macro with @code{#ifdef}.
3090:
3091: @item FRAME_GROWS_DOWNWARD
3092: Define this macro if the addresses of local variable slots are at negative
3093: offsets from the frame pointer.
3094:
3095: @item STARTING_FRAME_OFFSET
3096: Offset from the frame pointer to the first local variable slot to be allocated.
3097:
3098: If @code{FRAME_GROWS_DOWNWARD}, the next slot's offset is found by
3099: subtracting the length of the first slot from @code{STARTING_FRAME_OFFSET}.
3100: Otherwise, it is found by adding the length of the first slot to
3101: the value @code{STARTING_FRAME_OFFSET}.
3102:
3103: @item PUSH_ROUNDING (@var{npushed})
3104: A C expression that is the number of bytes actually pushed onto the
3105: stack when an instruction attempts to push @var{npushed} bytes.
3106:
3107: On some machines, the definition
3108:
3109: @example
3110: #define PUSH_ROUNDING(BYTES) (BYTES)
3111: @end example
3112:
3113: @noindent
3114: will suffice. But on other machines, instructions that appear
3115: to push one byte actually push two bytes in an attempt to maintain
3116: alignment. Then the definition should be
3117:
3118: @example
3119: #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
3120: @end example
3121:
3122: @item FIRST_PARM_OFFSET
3123: Offset from the argument pointer register to the first argument's address.
3124:
3125: @item RETURN_POPS_ARGS
3126: Define this macro if returning from a function automatically pops the
3127: function's arguments. Do not define it if the caller must pop them.
3128:
3129: @item FUNCTION_PROLOGUE (@var{file}, @var{size})
3130: A C compound statement that outputs the assembler code for entry to a
3131: function. The prologue is responsible for setting up the stack frame,
3132: initializing the frame pointer register, saving registers that must be
3133: saved, and allocating @var{size} additional bytes of storage for the local
3134: variables. @var{size} is an integer. @var{file} is a stdio stream to
3135: which the assembler code should be output.
3136:
3137: The label for the beginning of the function need not be output by this
3138: macro. That has already been done when the macro is run.
3139:
3140: To determine which registers to save, the macro can refer to the array
3141: @code{regs_ever_live}: element @var{r} is nonzero if hard register @var{r}
3142: is used anywhere within the function. This implies the function prologue
3143: should save register @var{r}, but not if it is one of the call-used
3144: registers.
3145:
3146: @item FUNCTION_EPILOGUE (@var{file}, @var{size})
3147: A C compound statement that outputs the assembler code for exit from a
3148: function. The epilogue is responsible for restoring the saved
3149: registers and stack pointer to their values when the function was
3150: called, and returning control to the caller. This macro takes the
3151: same arguments as the macro @code{FUNCTION_PROLOGUE}, and the
3152: registers to restore are determined from @code{regs_ever_live} and
3153: @code{CALL_USED_REGISTERS} in the same way.
3154:
3155: On some machines, there is a single instruction that does all the work of
3156: returning from the function. On these machines, give that instruction the
3157: name @samp{return} and do not define the macro @code{FUNCTION_EPILOGUE} at
3158: all.
3159: @end table
3160:
3161: @node Addressing Modes, Misc, Stack Layout, Machine Macros
3162: @section Addressing Modes
3163:
3164: @table @code
3165: @item HAVE_POST_INCREMENT
3166: Define this macro if the machine supports post-increment addressing.
3167:
3168: @item HAVE_PRE_INCREMENT
3169: @itemx HAVE_POST_DECREMENT
3170: @itemx HAVE_PRE_DECREMENT
3171: Similar for other kinds of addressing.
3172:
3173: @item CONSTANT_ADDRESS_P (@var{x})
3174: A C expression that is 1 if the rtx @var{x} is a constant whose value
3175: is an integer. This includes integers whose values are not explicitly
3176: known, such as @samp{symbol_ref} and @samp{label_ref} expressions
3177: and @samp{const} arithmetic expressions.
3178:
3179: @item MAX_REGS_PER_ADDRESS
3180: A number, the maximum number of registers that can appear in a valid
3181: memory address.
3182:
3183: @item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label})
3184: A C compound statement with a conditional @code{goto @var{label};}
3185: executed if @var{x} (an rtx) is a legitimate memory address on
3186: the target machine for a memory operand of mode @var{mode}.
3187:
3188: It usually pays to define several simpler macros to serve as
3189: subroutines for this one. Otherwise it may be too complicated
3190: to understand.
3191:
3192: @item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win})
3193: A C compound statement that attempts to replace @var{x} with a valid
3194: memory address for an operand of mode @var{mode}. @var{win} will be
3195: a C statement label elsewhere in the code; the macro definition
3196: may use
3197:
3198: @example
3199: GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win});
3200: @end example
3201:
3202: @noindent
3203: to avoid further processing if the address has become legitimate.
3204:
3205: @var{x} will always be the result of a call to @code{break_out_memory_refs},
3206: and @var{oldx} will be the operand that was given to that function to produce
3207: @var{x}.
3208:
3209: The code generated by this macro should not alter the substructure of @var{x}.
3210: If it transforms @var{x} into a more legitimate form, it should assign @var{x}
3211: (which will always be a C variable) a new value.
3212:
3213: It is not necessary for this macro to come up with a legitimate address.
3214: The compiler has standard ways of doing so in all cases. In fact, it is
3215: safe for this macro to do nothing. But often a machine-dependent strategy
3216: can generate better code.
3217: @end table
3218:
3219: @node Misc, Condition Code, Addressing Modes, Machine Macros
3220: @section Miscellaneous Parameters
3221:
3222: @table @code
3223: @item CASE_VECTOR_MODE
3224: An alias for a machine mode name. This is the machine mode that elements
3225: of a jump-table should have.
3226:
3227: @item CASE_VECTOR_PC_RELATIVE
3228: Define this macro if jump-tables should contain relative addresses.
3229:
3230: @item IMPLICIT_FIX_EXPR
3231: An alias for a tree code that should be used by default for conversion
3232: of floating point values to fixed point. Normally, @code{FIX_ROUND_EXPR}
3233: is used.
3234:
3235: @item EASY_DIV_EXPR
3236: An alias for a tree code that is the easiest kind of division to compile
3237: code for in the general case. It may be @code{TRUNC_DIV_EXPR},
3238: @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or @code{ROUND_DIV_EXPR}.
3239: These differ in how they round the result to an integer.
3240: @code{EASY_DIV_EXPR} is used when it is permissible to use any of those
3241: kinds of division and the choice should be made on the basis of efficiency.
3242:
3243: @item MOVE_MAX
3244: The maximum number of bytes that a single instruction can move quickly
3245: from memory to memory.
3246:
3247: @item SLOW_ZERO_EXTEND
3248: Define this macro if zero-extension (of chars or shorts to integers)
3249: can be done faster if the destination is a register that is known to be zero.
3250:
3251: @item SHIFT_COUNT_TRUNCATED
3252: Define this macro if shift instructions ignore all but the lowest few
3253: bits of the shift count. It implies that a sign-extend or zero-extend
3254: instruction for the shift count can be omitted.
3255:
3256: @item TRULY_NOOP_TRUNCATON (@var{outprec}, @var{inprec})
3257: A C expression which is nonzero if on this machine it is safe to
3258: ``convert'' an integer of @var{inprec} bits to one of @var{outprec} bits
3259: (where @var{outprec} is smaller than @var{inprec}) by merely operating
3260: on it as if it had only @var{inprec} bits.
3261:
3262: On many machines, this expression can be 1.
3263:
3264: @item Pmode
3265: An alias for the machine mode for pointers. Normally the definition can be
3266:
3267: @example
3268: #define Pmode SImode
3269: @end example
3270:
3271: @item FUNCTION_MODE
3272: An alias for the machine mode used for memory references to functions being
3273: called, in @samp{call} RTL expressions. On most machines this should be
3274: @code{QImode}.
3275:
3276: @item CONST_COST (@var{x}, @var{code})
3277: A part of a C @code{switch} statement that describes the relative costs of
3278: constant RTL expressions. It must contain @code{case} labels for
3279: expression codes @samp{const_int}, @samp{const}, @samp{symbol_ref},
3280: @samp{label_ref} and @code{const_double}. Each case must ultimately reach
3281: a @code{return} statement to return the relative cost of the use of that
3282: kind of constant value in an expression. The cost may depend on the
3283: precise value of the constant, which is available for examination in
3284: @var{x}.
3285:
3286: @var{code} is the expression code---redundant, since it can be obtained with
3287: @code{GET_CODE (@var{x})}.
3288: @end table
3289:
3290: @node Condition Code, Assembler Format, Misc, Machine Macros
3291: @section Condition Code Information
3292:
3293: The file @file{conditions.h} defines a variable @code{cc_status} to
3294: describe how the condition code was computed (in case the interpretation of
3295: the condition code depends on the instruction that it was set by). This
3296: variable contains the RTL expressions on which the condition code is
3297: currently based, and several standard flags.
3298:
3299: Sometimes additional machine-specific flags must be defined in the machine
3300: description header file. It can also add additional machine-specific
3301: information by defining @code{CC_STATUS_MDEP}.
3302:
3303: @table @code
3304: @item CC_STATUS_MDEP
3305: A type, with which the @code{mdep} component of @code{cc_status} should
3306: be declared. It defaults to @code{int}.
3307:
3308: @item CC_STATUS_MDEP_INIT
3309: A C expression for the initial value of the @code{mdep} field.
3310: It defaults to 0.
3311:
3312: @item NOTICE_UPDATE_CC (@var{exp})
3313: A C compound statement to set the components of @code{cc_status}
3314: appropriately for an insn whose body is @var{exp}. It is this
3315: macro's responsibility to recognize insns that set the condition code
3316: as a byproduct of other activity as well as those that explicitly
3317: set @code{(cc0)}.
3318:
3319: If there are insn that do not set the condition code but do alter other
3320: machine registers, this macro must check to see whether they invalidate the
3321: expressions that the condition code is recorded as reflecting. For
3322: example, on the 68000, insns that store in address registers do not set the
3323: condition code, which means that usually @code{NOTICE_UPDATE_CC} can leave
3324: @code{cc_status} unaltered for such insns. But suppose that the previous
3325: insn set the condition code based on location @code{a4@@(102)} and the
3326: current insn stores a new value in @code{a4}. Although the condition code
3327: is not changed by this, it will no longer be true that it reflects the
3328: contents of @code{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter
3329: @code{cc_status} in this case to say that nothing is known about the
3330: condition code value.
3331: @end table
3332:
3333: @node Assembler Format,, Condition Code, Machine Macros
3334: @section Output of Assembler Code
3335:
3336: @table @code
3337: @item TEXT_SECTION_ASM_OP
3338: A C string constant for the assembler operation that should precede
3339: instructions and read-only data. Normally @code{".text"} is right.
3340:
3341: @item DATA_SECTION_ASM_OP
3342: A C string constant for the assembler operation to identify the following
3343: data as writable initialized data. Normally @code{".data"} is right.
3344:
3345: @item REGISTER_NAMES
3346: A C initializer containing the assembler's names for the machine registers,
3347: each one as a C string constant. This is what translates register numbers
3348: in the compiler into assembler language.
3349:
3350: @item DBX_REGISTER_NUMBER (@var{regno})
3351: A C expression that returns the DBX register number for the compiler register
3352: number @var{regno}. In simple cases, the value of this expression may be
3353: @var{regno} itself. But sometimes there are some registers that the compiler
3354: knows about and DBX does not, or vice versa. In such cases, some register
3355: may need to have one number in the compiler and another for DBX.
3356:
3357: @item ASM_OUTPUT_DOUBLE (@var{file}, @var{value})
3358: A C statement to output to the stdio stream @var{file} an assembler
3359: instruction to assemble a @code{double} constant whose value is
3360: @var{value}. @var{value} will be a C expression of type @code{double}.
3361:
3362: @item ASM_OUTPUT_FLOAT (@var{file}, @var{value})
3363: A C statement to output to the stdio stream @var{file} an assembler
3364: instruction to assemble a @code{float} constant whose value is @var{value}.
3365: @var{value} will be a C expression of type @code{float}.
3366:
3367: @item ASM_OUTPUT_SKIP (@var{file}, @var{nbytes})
3368: A C statement to output to the stdio stream @var{file} an assembler
3369: instruction to advance the location counter by @var{nbytes} bytes.
3370: @var{nbytes} will be a C expression of type @code{int}.
3371:
3372: @item ASM_OUTPUT_ALIGN (@var{file}, @var{power})
3373: A C statement to output to the stdio stream @var{file} an assembler
3374: instruction to advance the location counter to a multiple of 2 to the
3375: @var{power} bytes. @var{power} will be a C expression of type @code{int}.
3376:
3377: @item ASM_INT_OP
3378: A C string constant for the assembler operation that assembles constants of
3379: C type @code{int}. A space must follow the operation name. Normally
3380: @code{".long@ "}.
3381:
3382: @item ASM_SHORT_OP
3383: @itemx ASM_CHAR_OP
3384: Likewise, for C types @code{short} and @code{char}. Normally @code{".word@ "}
3385: and @code{".byte@ "}.
3386:
3387: @item TARGET_BELL
3388: A C constant expression for the integer value for escape sequence @samp{\a}.
3389:
3390: @item TARGET_BS
3391: @itemx TARGET_TAB
3392: @itemx TARGET_NEWLINE
3393: C constant expressions for the integer values for escape sequences
3394: @samp{\b}, @samp{\t} and @samp{\n}.
3395:
3396: @item TARGET_VT
3397: @itemx TARGET_FF
3398: @itemx TARGET_CR
3399: C constant expressions for the integer values for escape sequences
3400: @samp{\v}, @samp{\f} and @samp{\r}.
3401:
3402: @item PRINT_OPERAND (@var{file}, @var{x})
3403: A C compound statement to output to stdio stream @var{file}
3404: the assembler syntax for an instruction operand @var{x}.
3405: @var{x} is an RTL expression.
3406:
3407: If @var{x} is a register, this macro should print the register's name. The
3408: names can be found in an array @code{reg_names} whose type is @code{char
3409: *[]}. @code{reg_names} is initialized from @code{REGISTER_NAMES}.
3410:
3411: @item PRINT_OPERAND_ADDRESS (@var{file}, @var{x})
3412: A C compound statement to output to stdio stream @var{file} the assembler
3413: syntax for an instruction operand that is a memory reference whose address
3414: is @var{x}. @var{x} is an RTL expression.
3415: @end table
3416:
3417: @contents
3418: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.