![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-13 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / cc|
Return to gcc.info-13 CVS log | Up to [Apple XNU] / GNUtools / cc |
1.1 root 1: This is Info file gcc.info, produced by Makeinfo-1.54 from the input
2: file gcc.texi.
3:
4: This file documents the use and the internals of the GNU compiler.
5:
6: Published by the Free Software Foundation 675 Massachusetts Avenue
7: Cambridge, MA 02139 USA
8:
9: Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
10:
11: Permission is granted to make and distribute verbatim copies of this
12: manual provided the copyright notice and this permission notice are
13: preserved on all copies.
14:
15: Permission is granted to copy and distribute modified versions of
16: this manual under the conditions for verbatim copying, provided also
17: that the sections entitled "GNU General Public License" and "Protect
18: Your Freedom--Fight `Look And Feel'" are included exactly as in the
19: original, and provided that the entire resulting derived work is
20: distributed under the terms of a permission notice identical to this
21: one.
22:
23: Permission is granted to copy and distribute translations of this
24: manual into another language, under the above conditions for modified
25: versions, except that the sections entitled "GNU General Public
26: License" and "Protect Your Freedom--Fight `Look And Feel'", and this
27: permission notice, may be included in translations approved by the Free
28: Software Foundation instead of in the original English.
29:
30:
31: File: gcc.info, Node: Insns, Next: Calls, Prev: Assembler, Up: RTL
32:
33: Insns
34: =====
35:
36: The RTL representation of the code for a function is a doubly-linked
37: chain of objects called "insns". Insns are expressions with special
38: codes that are used for no other purpose. Some insns are actual
39: instructions; others represent dispatch tables for `switch' statements;
40: others represent labels to jump to or various sorts of declarative
41: information.
42:
43: In addition to its own specific data, each insn must have a unique
44: id-number that distinguishes it from all other insns in the current
45: function (after delayed branch scheduling, copies of an insn with the
46: same id-number may be present in multiple places in a function, but
47: these copies will always be identical and will only appear inside a
48: `sequence'), and chain pointers to the preceding and following insns.
49: These three fields occupy the same position in every insn, independent
50: of the expression code of the insn. They could be accessed with `XEXP'
51: and `XINT', but instead three special macros are always used:
52:
53: `INSN_UID (I)'
54: Accesses the unique id of insn I.
55:
56: `PREV_INSN (I)'
57: Accesses the chain pointer to the insn preceding I. If I is the
58: first insn, this is a null pointer.
59:
60: `NEXT_INSN (I)'
61: Accesses the chain pointer to the insn following I. If I is the
62: last insn, this is a null pointer.
63:
64: The first insn in the chain is obtained by calling `get_insns'; the
65: last insn is the result of calling `get_last_insn'. Within the chain
66: delimited by these insns, the `NEXT_INSN' and `PREV_INSN' pointers must
67: always correspond: if INSN is not the first insn,
68:
69: NEXT_INSN (PREV_INSN (INSN)) == INSN
70:
71: is always true and if INSN is not the last insn,
72:
73: PREV_INSN (NEXT_INSN (INSN)) == INSN
74:
75: is always true.
76:
77: After delay slot scheduling, some of the insns in the chain might be
78: `sequence' expressions, which contain a vector of insns. The value of
79: `NEXT_INSN' in all but the last of these insns is the next insn in the
80: vector; the value of `NEXT_INSN' of the last insn in the vector is the
81: same as the value of `NEXT_INSN' for the `sequence' in which it is
82: contained. Similar rules apply for `PREV_INSN'.
83:
84: This means that the above invariants are not necessarily true for
85: insns inside `sequence' expressions. Specifically, if INSN is the
86: first insn in a `sequence', `NEXT_INSN (PREV_INSN (INSN))' is the insn
87: containing the `sequence' expression, as is the value of `PREV_INSN
88: (NEXT_INSN (INSN))' is INSN is the last insn in the `sequence'
89: expression. You can use these expressions to find the containing
90: `sequence' expression.
91:
92: Every insn has one of the following six expression codes:
93:
94: `insn'
95: The expression code `insn' is used for instructions that do not
96: jump and do not do function calls. `sequence' expressions are
97: always contained in insns with code `insn' even if one of those
98: insns should jump or do function calls.
99:
100: Insns with code `insn' have four additional fields beyond the three
101: mandatory ones listed above. These four are described in a table
102: below.
103:
104: `jump_insn'
105: The expression code `jump_insn' is used for instructions that may
106: jump (or, more generally, may contain `label_ref' expressions). If
107: there is an instruction to return from the current function, it is
108: recorded as a `jump_insn'.
109:
110: `jump_insn' insns have the same extra fields as `insn' insns,
111: accessed in the same way and in addition contains a field
112: `JUMP_LABEL' which is defined once jump optimization has completed.
113:
114: For simple conditional and unconditional jumps, this field
115: contains the `code_label' to which this insn will (possibly
116: conditionally) branch. In a more complex jump, `JUMP_LABEL'
117: records one of the labels that the insn refers to; the only way to
118: find the others is to scan the entire body of the insn.
119:
120: Return insns count as jumps, but since they do not refer to any
121: labels, they have zero in the `JUMP_LABEL' field.
122:
123: `call_insn'
124: The expression code `call_insn' is used for instructions that may
125: do function calls. It is important to distinguish these
126: instructions because they imply that certain registers and memory
127: locations may be altered unpredictably.
128:
129: A `call_insn' insn may be preceded by insns that contain a single
130: `use' expression and be followed by insns the contain a single
131: `clobber' expression. If so, these `use' and `clobber'
132: expressions are treated as being part of the function call. There
133: must not even be a `note' between the `call_insn' and the `use' or
134: `clobber' insns for this special treatment to take place. This is
135: somewhat of a kludge and will be removed in a later version of GNU
136: CC.
137:
138: `call_insn' insns have the same extra fields as `insn' insns,
139: accessed in the same way.
140:
141: `code_label'
142: A `code_label' insn represents a label that a jump insn can jump
143: to. It contains two special fields of data in addition to the
144: three standard ones. `CODE_LABEL_NUMBER' is used to hold the
145: "label number", a number that identifies this label uniquely among
146: all the labels in the compilation (not just in the current
147: function). Ultimately, the label is represented in the assembler
148: output as an assembler label, usually of the form `LN' where N is
149: the label number.
150:
151: When a `code_label' appears in an RTL expression, it normally
152: appears within a `label_ref' which represents the address of the
153: label, as a number.
154:
155: The field `LABEL_NUSES' is only defined once the jump optimization
156: phase is completed and contains the number of times this label is
157: referenced in the current function.
158:
159: `barrier'
160: Barriers are placed in the instruction stream when control cannot
161: flow past them. They are placed after unconditional jump
162: instructions to indicate that the jumps are unconditional and
163: after calls to `volatile' functions, which do not return (e.g.,
164: `exit'). They contain no information beyond the three standard
165: fields.
166:
167: `note'
168: `note' insns are used to represent additional debugging and
169: declarative information. They contain two nonstandard fields, an
170: integer which is accessed with the macro `NOTE_LINE_NUMBER' and a
171: string accessed with `NOTE_SOURCE_FILE'.
172:
173: If `NOTE_LINE_NUMBER' is positive, the note represents the
174: position of a source line and `NOTE_SOURCE_FILE' is the source
175: file name that the line came from. These notes control generation
176: of line number data in the assembler output.
177:
178: Otherwise, `NOTE_LINE_NUMBER' is not really a line number but a
179: code with one of the following values (and `NOTE_SOURCE_FILE' must
180: contain a null pointer):
181:
182: `NOTE_INSN_DELETED'
183: Such a note is completely ignorable. Some passes of the
184: compiler delete insns by altering them into notes of this
185: kind.
186:
187: `NOTE_INSN_BLOCK_BEG'
188: `NOTE_INSN_BLOCK_END'
189: These types of notes indicate the position of the beginning
190: and end of a level of scoping of variable names. They
191: control the output of debugging information.
192:
193: `NOTE_INSN_LOOP_BEG'
194: `NOTE_INSN_LOOP_END'
195: These types of notes indicate the position of the beginning
196: and end of a `while' or `for' loop. They enable the loop
197: optimizer to find loops quickly.
198:
199: `NOTE_INSN_LOOP_CONT'
200: Appears at the place in a loop that `continue' statements
201: jump to.
202:
203: `NOTE_INSN_LOOP_VTOP'
204: This note indicates the place in a loop where the exit test
205: begins for those loops in which the exit test has been
206: duplicated. This position becomes another virtual start of
207: the loop when considering loop invariants.
208:
209: `NOTE_INSN_FUNCTION_END'
210: Appears near the end of the function body, just before the
211: label that `return' statements jump to (on machine where a
212: single instruction does not suffice for returning). This
213: note may be deleted by jump optimization.
214:
215: `NOTE_INSN_SETJMP'
216: Appears following each call to `setjmp' or a related function.
217:
218: These codes are printed symbolically when they appear in debugging
219: dumps.
220:
221: The machine mode of an insn is normally `VOIDmode', but some phases
222: use the mode for various purposes; for example, the reload pass sets it
223: to `HImode' if the insn needs reloading but not register elimination
224: and `QImode' if both are required. The common subexpression
225: elimination pass sets the mode of an insn to `QImode' when it is the
226: first insn in a block that has already been processed.
227:
228: Here is a table of the extra fields of `insn', `jump_insn' and
229: `call_insn' insns:
230:
231: `PATTERN (I)'
232: An expression for the side effect performed by this insn. This
233: must be one of the following codes: `set', `call', `use',
234: `clobber', `return', `asm_input', `asm_output', `addr_vec',
235: `addr_diff_vec', `trap_if', `unspec', `unspec_volatile',
236: `parallel', or `sequence'. If it is a `parallel', each element of
237: the `parallel' must be one these codes, except that `parallel'
238: expressions cannot be nested and `addr_vec' and `addr_diff_vec'
239: are not permitted inside a `parallel' expression.
240:
241: `INSN_CODE (I)'
242: An integer that says which pattern in the machine description
243: matches this insn, or -1 if the matching has not yet been
244: attempted.
245:
246: Such matching is never attempted and this field remains -1 on an
247: insn whose pattern consists of a single `use', `clobber',
248: `asm_input', `addr_vec' or `addr_diff_vec' expression.
249:
250: Matching is also never attempted on insns that result from an `asm'
251: statement. These contain at least one `asm_operands' expression.
252: The function `asm_noperands' returns a non-negative value for such
253: insns.
254:
255: In the debugging output, this field is printed as a number
256: followed by a symbolic representation that locates the pattern in
257: the `md' file as some small positive or negative offset from a
258: named pattern.
259:
260: `LOG_LINKS (I)'
261: A list (chain of `insn_list' expressions) giving information about
262: dependencies between instructions within a basic block. Neither a
263: jump nor a label may come between the related insns.
264:
265: `REG_NOTES (I)'
266: A list (chain of `expr_list' and `insn_list' expressions) giving
267: miscellaneous information about the insn. It is often information
268: pertaining to the registers used in this insn.
269:
270: The `LOG_LINKS' field of an insn is a chain of `insn_list'
271: expressions. Each of these has two operands: the first is an insn, and
272: the second is another `insn_list' expression (the next one in the
273: chain). The last `insn_list' in the chain has a null pointer as second
274: operand. The significant thing about the chain is which insns appear
275: in it (as first operands of `insn_list' expressions). Their order is
276: not significant.
277:
278: This list is originally set up by the flow analysis pass; it is a
279: null pointer until then. Flow only adds links for those data
280: dependencies which can be used for instruction combination. For each
281: insn, the flow analysis pass adds a link to insns which store into
282: registers values that are used for the first time in this insn. The
283: instruction scheduling pass adds extra links so that every dependence
284: will be represented. Links represent data dependencies,
285: antidependencies and output dependencies; the machine mode of the link
286: distinguishes these three types: antidependencies have mode
287: `REG_DEP_ANTI', output dependencies have mode `REG_DEP_OUTPUT', and
288: data dependencies have mode `VOIDmode'.
289:
290: The `REG_NOTES' field of an insn is a chain similar to the
291: `LOG_LINKS' field but it includes `expr_list' expressions in addition
292: to `insn_list' expressions. There are several kinds of register notes,
293: which are distinguished by the machine mode, which in a register note
294: is really understood as being an `enum reg_note'. The first operand OP
295: of the note is data whose meaning depends on the kind of note.
296:
297: The macro `REG_NOTE_KIND (X)' returns the kind of register note.
298: Its counterpart, the macro `PUT_REG_NOTE_KIND (X, NEWKIND)' sets the
299: register note type of X to be NEWKIND.
300:
301: Register notes are of three classes: They may say something about an
302: input to an insn, they may say something about an output of an insn, or
303: they may create a linkage between two insns. There are also a set of
304: values that are only used in `LOG_LINKS'.
305:
306: These register notes annotate inputs to an insn:
307:
308: `REG_DEAD'
309: The value in OP dies in this insn; that is to say, altering the
310: value immediately after this insn would not affect the future
311: behavior of the program.
312:
313: This does not necessarily mean that the register OP has no useful
314: value after this insn since it may also be an output of the insn.
315: In such a case, however, a `REG_DEAD' note would be redundant and
316: is usually not present until after the reload pass, but no code
317: relies on this fact.
318:
319: `REG_INC'
320: The register OP is incremented (or decremented; at this level
321: there is no distinction) by an embedded side effect inside this
322: insn. This means it appears in a `post_inc', `pre_inc',
323: `post_dec' or `pre_dec' expression.
324:
325: `REG_NONNEG'
326: The register OP is known to have a nonnegative value when this
327: insn is reached. This is used so that decrement and branch until
328: zero instructions, such as the m68k dbra, can be matched.
329:
330: The `REG_NONNEG' note is added to insns only if the machine
331: description has a `decrement_and_branch_until_zero' pattern.
332:
333: `REG_NO_CONFLICT'
334: This insn does not cause a conflict between OP and the item being
335: set by this insn even though it might appear that it does. In
336: other words, if the destination register and OP could otherwise be
337: assigned the same register, this insn does not prevent that
338: assignment.
339:
340: Insns with this note are usually part of a block that begins with a
341: `clobber' insn specifying a multi-word pseudo register (which will
342: be the output of the block), a group of insns that each set one
343: word of the value and have the `REG_NO_CONFLICT' note attached,
344: and a final insn that copies the output to itself with an attached
345: `REG_EQUAL' note giving the expression being computed. This block
346: is encapsulated with `REG_LIBCALL' and `REG_RETVAL' notes on the
347: first and last insns, respectively.
348:
349: `REG_LABEL'
350: This insn uses OP, a `code_label', but is not a `jump_insn'. The
351: presence of this note allows jump optimization to be aware that OP
352: is, in fact, being used.
353:
354: The following notes describe attributes of outputs of an insn:
355:
356: `REG_EQUIV'
357: `REG_EQUAL'
358: This note is only valid on an insn that sets only one register and
359: indicates that that register will be equal to OP at run time; the
360: scope of this equivalence differs between the two types of notes.
361: The value which the insn explicitly copies into the register may
362: look different from OP, but they will be equal at run time. If the
363: output of the single `set' is a `strict_low_part' expression, the
364: note refers to the register that is contained in `SUBREG_REG' of
365: the `subreg' expression.
366:
367: For `REG_EQUIV', the register is equivalent to OP throughout the
368: entire function, and could validly be replaced in all its
369: occurrences by OP. ("Validly" here refers to the data flow of the
370: program; simple replacement may make some insns invalid.) For
371: example, when a constant is loaded into a register that is never
372: assigned any other value, this kind of note is used.
373:
374: When a parameter is copied into a pseudo-register at entry to a
375: function, a note of this kind records that the register is
376: equivalent to the stack slot where the parameter was passed.
377: Although in this case the register may be set by other insns, it
378: is still valid to replace the register by the stack slot
379: throughout the function.
380:
381: In the case of `REG_EQUAL', the register that is set by this insn
382: will be equal to OP at run time at the end of this insn but not
383: necessarily elsewhere in the function. In this case, OP is
384: typically an arithmetic expression. For example, when a sequence
385: of insns such as a library call is used to perform an arithmetic
386: operation, this kind of note is attached to the insn that produces
387: or copies the final value.
388:
389: These two notes are used in different ways by the compiler passes.
390: `REG_EQUAL' is used by passes prior to register allocation (such as
391: common subexpression elimination and loop optimization) to tell
392: them how to think of that value. `REG_EQUIV' notes are used by
393: register allocation to indicate that there is an available
394: substitute expression (either a constant or a `mem' expression for
395: the location of a parameter on the stack) that may be used in
396: place of a register if insufficient registers are available.
397:
398: Except for stack homes for parameters, which are indicated by a
399: `REG_EQUIV' note and are not useful to the early optimization
400: passes and pseudo registers that are equivalent to a memory
401: location throughout there entire life, which is not detected until
402: later in the compilation, all equivalences are initially indicated
403: by an attached `REG_EQUAL' note. In the early stages of register
404: allocation, a `REG_EQUAL' note is changed into a `REG_EQUIV' note
405: if OP is a constant and the insn represents the only set of its
406: destination register.
407:
408: Thus, compiler passes prior to register allocation need only check
409: for `REG_EQUAL' notes and passes subsequent to register allocation
410: need only check for `REG_EQUIV' notes.
411:
412: `REG_UNUSED'
413: The register OP being set by this insn will not be used in a
414: subsequent insn. This differs from a `REG_DEAD' note, which
415: indicates that the value in an input will not be used subsequently.
416: These two notes are independent; both may be present for the same
417: register.
418:
419: `REG_WAS_0'
420: The single output of this insn contained zero before this insn.
421: OP is the insn that set it to zero. You can rely on this note if
422: it is present and OP has not been deleted or turned into a `note';
423: its absence implies nothing.
424:
425: These notes describe linkages between insns. They occur in pairs:
426: one insn has one of a pair of notes that points to a second insn, which
427: has the inverse note pointing back to the first insn.
428:
429: `REG_RETVAL'
430: This insn copies the value of a multi-insn sequence (for example, a
431: library call), and OP is the first insn of the sequence (for a
432: library call, the first insn that was generated to set up the
433: arguments for the library call).
434:
435: Loop optimization uses this note to treat such a sequence as a
436: single operation for code motion purposes and flow analysis uses
437: this note to delete such sequences whose results are dead.
438:
439: A `REG_EQUAL' note will also usually be attached to this insn to
440: provide the expression being computed by the sequence.
441:
442: `REG_LIBCALL'
443: This is the inverse of `REG_RETVAL': it is placed on the first
444: insn of a multi-insn sequence, and it points to the last one.
445:
446: `REG_CC_SETTER'
447: `REG_CC_USER'
448: On machines that use `cc0', the insns which set and use `cc0' set
449: and use `cc0' are adjacent. However, when branch delay slot
450: filling is done, this may no longer be true. In this case a
451: `REG_CC_USER' note will be placed on the insn setting `cc0' to
452: point to the insn using `cc0' and a `REG_CC_SETTER' note will be
453: placed on the insn using `cc0' to point to the insn setting `cc0'.
454:
455: These values are only used in the `LOG_LINKS' field, and indicate
456: the type of dependency that each link represents. Links which indicate
457: a data dependence (a read after write dependence) do not use any code,
458: they simply have mode `VOIDmode', and are printed without any
459: descriptive text.
460:
461: `REG_DEP_ANTI'
462: This indicates an anti dependence (a write after read dependence).
463:
464: `REG_DEP_OUTPUT'
465: This indicates an output dependence (a write after write
466: dependence).
467:
468: For convenience, the machine mode in an `insn_list' or `expr_list'
469: is printed using these symbolic codes in debugging dumps.
470:
471: The only difference between the expression codes `insn_list' and
472: `expr_list' is that the first operand of an `insn_list' is assumed to
473: be an insn and is printed in debugging dumps as the insn's unique id;
474: the first operand of an `expr_list' is printed in the ordinary way as
475: an expression.
476:
477:
478: File: gcc.info, Node: Calls, Next: Sharing, Prev: Insns, Up: RTL
479:
480: RTL Representation of Function-Call Insns
481: =========================================
482:
483: Insns that call subroutines have the RTL expression code `call_insn'.
484: These insns must satisfy special rules, and their bodies must use a
485: special RTL expression code, `call'.
486:
487: A `call' expression has two operands, as follows:
488:
489: (call (mem:FM ADDR) NBYTES)
490:
491: Here NBYTES is an operand that represents the number of bytes of
492: argument data being passed to the subroutine, FM is a machine mode
493: (which must equal as the definition of the `FUNCTION_MODE' macro in the
494: machine description) and ADDR represents the address of the subroutine.
495:
496: For a subroutine that returns no value, the `call' expression as
497: shown above is the entire body of the insn, except that the insn might
498: also contain `use' or `clobber' expressions.
499:
500: For a subroutine that returns a value whose mode is not `BLKmode',
501: the value is returned in a hard register. If this register's number is
502: R, then the body of the call insn looks like this:
503:
504: (set (reg:M R)
505: (call (mem:FM ADDR) NBYTES))
506:
507: This RTL expression makes it clear (to the optimizer passes) that the
508: appropriate register receives a useful value in this insn.
509:
510: When a subroutine returns a `BLKmode' value, it is handled by
511: passing to the subroutine the address of a place to store the value.
512: So the call insn itself does not "return" any value, and it has the
513: same RTL form as a call that returns nothing.
514:
515: On some machines, the call instruction itself clobbers some register,
516: for example to contain the return address. `call_insn' insns on these
517: machines should have a body which is a `parallel' that contains both
518: the `call' expression and `clobber' expressions that indicate which
519: registers are destroyed. Similarly, if the call instruction requires
520: some register other than the stack pointer that is not explicitly
521: mentioned it its RTL, a `use' subexpression should mention that
522: register.
523:
524: Functions that are called are assumed to modify all registers listed
525: in the configuration macro `CALL_USED_REGISTERS' (*note Register
526: Basics::.) and, with the exception of `const' functions and library
527: calls, to modify all of memory.
528:
529: Insns containing just `use' expressions directly precede the
530: `call_insn' insn to indicate which registers contain inputs to the
531: function. Similarly, if registers other than those in
532: `CALL_USED_REGISTERS' are clobbered by the called function, insns
533: containing a single `clobber' follow immediately after the call to
534: indicate which registers.
535:
536:
537: File: gcc.info, Node: Sharing, Next: Reading RTL, Prev: Calls, Up: RTL
538:
539: Structure Sharing Assumptions
540: =============================
541:
542: The compiler assumes that certain kinds of RTL expressions are
543: unique; there do not exist two distinct objects representing the same
544: value. In other cases, it makes an opposite assumption: that no RTL
545: expression object of a certain kind appears in more than one place in
546: the containing structure.
547:
548: These assumptions refer to a single function; except for the RTL
549: objects that describe global variables and external functions, and a
550: few standard objects such as small integer constants, no RTL objects
551: are common to two functions.
552:
553: * Each pseudo-register has only a single `reg' object to represent
554: it, and therefore only a single machine mode.
555:
556: * For any symbolic label, there is only one `symbol_ref' object
557: referring to it.
558:
559: * There is only one `const_int' expression with value 0, only one
560: with value 1, and only one with value -1. Some other integer
561: values are also stored uniquely.
562:
563: * There is only one `pc' expression.
564:
565: * There is only one `cc0' expression.
566:
567: * There is only one `const_double' expression with value 0 for each
568: floating point mode. Likewise for values 1 and 2.
569:
570: * No `label_ref' or `scratch' appears in more than one place in the
571: RTL structure; in other words, it is safe to do a tree-walk of all
572: the insns in the function and assume that each time a `label_ref'
573: or `scratch' is seen it is distinct from all others that are seen.
574:
575: * Only one `mem' object is normally created for each static variable
576: or stack slot, so these objects are frequently shared in all the
577: places they appear. However, separate but equal objects for these
578: variables are occasionally made.
579:
580: * When a single `asm' statement has multiple output operands, a
581: distinct `asm_operands' expression is made for each output operand.
582: However, these all share the vector which contains the sequence of
583: input operands. This sharing is used later on to test whether two
584: `asm_operands' expressions come from the same statement, so all
585: optimizations must carefully preserve the sharing if they copy the
586: vector at all.
587:
588: * No RTL object appears in more than one place in the RTL structure
589: except as described above. Many passes of the compiler rely on
590: this by assuming that they can modify RTL objects in place without
591: unwanted side-effects on other insns.
592:
593: * During initial RTL generation, shared structure is freely
594: introduced. After all the RTL for a function has been generated,
595: all shared structure is copied by `unshare_all_rtl' in
596: `emit-rtl.c', after which the above rules are guaranteed to be
597: followed.
598:
599: * During the combiner pass, shared structure within an insn can exist
600: temporarily. However, the shared structure is copied before the
601: combiner is finished with the insn. This is done by calling
602: `copy_rtx_if_shared', which is a subroutine of `unshare_all_rtl'.
603:
604:
605: File: gcc.info, Node: Reading RTL, Prev: Sharing, Up: RTL
606:
607: Reading RTL
608: ===========
609:
610: To read an RTL object from a file, call `read_rtx'. It takes one
611: argument, a stdio stream, and returns a single RTL object.
612:
613: Reading RTL from a file is very slow. This is no currently not a
614: problem because reading RTL occurs only as part of building the
615: compiler.
616:
617: People frequently have the idea of using RTL stored as text in a
618: file as an interface between a language front end and the bulk of GNU
619: CC. This idea is not feasible.
620:
621: GNU CC was designed to use RTL internally only. Correct RTL for a
622: given program is very dependent on the particular target machine. And
623: the RTL does not contain all the information about the program.
624:
625: The proper way to interface GNU CC to a new language front end is
626: with the "tree" data structure. There is no manual for this data
627: structure, but it is described in the files `tree.h' and `tree.def'.
628:
629:
630: File: gcc.info, Node: Machine Desc, Next: Target Macros, Prev: RTL, Up: Top
631:
632: Machine Descriptions
633: ********************
634:
635: A machine description has two parts: a file of instruction patterns
636: (`.md' file) and a C header file of macro definitions.
637:
638: The `.md' file for a target machine contains a pattern for each
639: instruction that the target machine supports (or at least each
640: instruction that is worth telling the compiler about). It may also
641: contain comments. A semicolon causes the rest of the line to be a
642: comment, unless the semicolon is inside a quoted string.
643:
644: See the next chapter for information on the C header file.
645:
646: * Menu:
647:
648: * Patterns:: How to write instruction patterns.
649: * Example:: An explained example of a `define_insn' pattern.
650: * RTL Template:: The RTL template defines what insns match a pattern.
651: * Output Template:: The output template says how to make assembler code
652: from such an insn.
653: * Output Statement:: For more generality, write C code to output
654: the assembler code.
655: * Constraints:: When not all operands are general operands.
656: * Standard Names:: Names mark patterns to use for code generation.
657: * Pattern Ordering:: When the order of patterns makes a difference.
658: * Dependent Patterns:: Having one pattern may make you need another.
659: * Jump Patterns:: Special considerations for patterns for jump insns.
660: * Insn Canonicalizations::Canonicalization of Instructions
661: * Peephole Definitions::Defining machine-specific peephole optimizations.
662: * Expander Definitions::Generating a sequence of several RTL insns
663: for a standard operation.
664: * Insn Splitting:: Splitting Instructions into Multiple Instructions
665: * Insn Attributes:: Specifying the value of attributes for generated insns.
666:
667:
668: File: gcc.info, Node: Patterns, Next: Example, Up: Machine Desc
669:
670: Everything about Instruction Patterns
671: =====================================
672:
673: Each instruction pattern contains an incomplete RTL expression, with
674: pieces to be filled in later, operand constraints that restrict how the
675: pieces can be filled in, and an output pattern or C code to generate
676: the assembler output, all wrapped up in a `define_insn' expression.
677:
678: A `define_insn' is an RTL expression containing four or five
679: operands:
680:
681: 1. An optional name. The presence of a name indicate that this
682: instruction pattern can perform a certain standard job for the
683: RTL-generation pass of the compiler. This pass knows certain
684: names and will use the instruction patterns with those names, if
685: the names are defined in the machine description.
686:
687: The absence of a name is indicated by writing an empty string
688: where the name should go. Nameless instruction patterns are never
689: used for generating RTL code, but they may permit several simpler
690: insns to be combined later on.
691:
692: Names that are not thus known and used in RTL-generation have no
693: effect; they are equivalent to no name at all.
694:
695: 2. The "RTL template" (*note RTL Template::.) is a vector of
696: incomplete RTL expressions which show what the instruction should
697: look like. It is incomplete because it may contain
698: `match_operand', `match_operator', and `match_dup' expressions
699: that stand for operands of the instruction.
700:
701: If the vector has only one element, that element is the template
702: for the instruction pattern. If the vector has multiple elements,
703: then the instruction pattern is a `parallel' expression containing
704: the elements described.
705:
706: 3. A condition. This is a string which contains a C expression that
707: is the final test to decide whether an insn body matches this
708: pattern.
709:
710: For a named pattern, the condition (if present) may not depend on
711: the data in the insn being matched, but only the
712: target-machine-type flags. The compiler needs to test these
713: conditions during initialization in order to learn exactly which
714: named instructions are available in a particular run.
715:
716: For nameless patterns, the condition is applied only when matching
717: an individual insn, and only after the insn has matched the
718: pattern's recognition template. The insn's operands may be found
719: in the vector `operands'.
720:
721: 4. The "output template": a string that says how to output matching
722: insns as assembler code. `%' in this string specifies where to
723: substitute the value of an operand. *Note Output Template::.
724:
725: When simple substitution isn't general enough, you can specify a
726: piece of C code to compute the output. *Note Output Statement::.
727:
728: 5. Optionally, a vector containing the values of attributes for insns
729: matching this pattern. *Note Insn Attributes::.
730:
731:
732: File: gcc.info, Node: Example, Next: RTL Template, Prev: Patterns, Up: Machine Desc
733:
734: Example of `define_insn'
735: ========================
736:
737: Here is an actual example of an instruction pattern, for the
738: 68000/68020.
739:
740: (define_insn "tstsi"
741: [(set (cc0)
742: (match_operand:SI 0 "general_operand" "rm"))]
743: ""
744: "*
745: { if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
746: return \"tstl %0\";
747: return \"cmpl #0,%0\"; }")
748:
749: This is an instruction that sets the condition codes based on the
750: value of a general operand. It has no condition, so any insn whose RTL
751: description has the form shown may be handled according to this
752: pattern. The name `tstsi' means "test a `SImode' value" and tells the
753: RTL generation pass that, when it is necessary to test such a value, an
754: insn to do so can be constructed using this pattern.
755:
756: The output control string is a piece of C code which chooses which
757: output template to return based on the kind of operand and the specific
758: type of CPU for which code is being generated.
759:
760: `"rm"' is an operand constraint. Its meaning is explained below.
761:
762:
763: File: gcc.info, Node: RTL Template, Next: Output Template, Prev: Example, Up: Machine Desc
764:
765: RTL Template
766: ============
767:
768: The RTL template is used to define which insns match the particular
769: pattern and how to find their operands. For named patterns, the RTL
770: template also says how to construct an insn from specified operands.
771:
772: Construction involves substituting specified operands into a copy of
773: the template. Matching involves determining the values that serve as
774: the operands in the insn being matched. Both of these activities are
775: controlled by special expression types that direct matching and
776: substitution of the operands.
777:
778: `(match_operand:M N PREDICATE CONSTRAINT)'
779: This expression is a placeholder for operand number N of the insn.
780: When constructing an insn, operand number N will be substituted
781: at this point. When matching an insn, whatever appears at this
782: position in the insn will be taken as operand number N; but it
783: must satisfy PREDICATE or this instruction pattern will not match
784: at all.
785:
786: Operand numbers must be chosen consecutively counting from zero in
787: each instruction pattern. There may be only one `match_operand'
788: expression in the pattern for each operand number. Usually
789: operands are numbered in the order of appearance in `match_operand'
790: expressions.
791:
792: PREDICATE is a string that is the name of a C function that
793: accepts two arguments, an expression and a machine mode. During
794: matching, the function will be called with the putative operand as
795: the expression and M as the mode argument (if M is not specified,
796: `VOIDmode' will be used, which normally causes PREDICATE to accept
797: any mode). If it returns zero, this instruction pattern fails to
798: match. PREDICATE may be an empty string; then it means no test is
799: to be done on the operand, so anything which occurs in this
800: position is valid.
801:
802: Most of the time, PREDICATE will reject modes other than M--but
803: not always. For example, the predicate `address_operand' uses M
804: as the mode of memory ref that the address should be valid for.
805: Many predicates accept `const_int' nodes even though their mode is
806: `VOIDmode'.
807:
808: CONSTRAINT controls reloading and the choice of the best register
809: class to use for a value, as explained later (*note
810: Constraints::.).
811:
812: People are often unclear on the difference between the constraint
813: and the predicate. The predicate helps decide whether a given
814: insn matches the pattern. The constraint plays no role in this
815: decision; instead, it controls various decisions in the case of an
816: insn which does match.
817:
818: On CISC machines, the most common PREDICATE is
819: `"general_operand"'. This function checks that the putative
820: operand is either a constant, a register or a memory reference,
821: and that it is valid for mode M.
822:
823: For an operand that must be a register, PREDICATE should be
824: `"register_operand"'. Using `"general_operand"' would be valid,
825: since the reload pass would copy any non-register operands through
826: registers, but this would make GNU CC do extra work, it would
827: prevent invariant operands (such as constant) from being removed
828: from loops, and it would prevent the register allocator from doing
829: the best possible job. On RISC machines, it is usually most
830: efficient to allow PREDICATE to accept only objects that the
831: constraints allow.
832:
833: For an operand that must be a constant, you must be sure to either
834: use `"immediate_operand"' for PREDICATE, or make the instruction
835: pattern's extra condition require a constant, or both. You cannot
836: expect the constraints to do this work! If the constraints allow
837: only constants, but the predicate allows something else, the
838: compiler will crash when that case arises.
839:
840: `(match_scratch:M N CONSTRAINT)'
841: This expression is also a placeholder for operand number N and
842: indicates that operand must be a `scratch' or `reg' expression.
843:
844: When matching patterns, this is completely equivalent to
845:
846: (match_operand:M N "scratch_operand" PRED)
847:
848: but, when generating RTL, it produces a (`scratch':M) expression.
849:
850: If the last few expressions in a `parallel' are `clobber'
851: expressions whose operands are either a hard register or
852: `match_scratch', the combiner can add them when necessary. *Note
853: Side Effects::.
854:
855: `(match_dup N)'
856: This expression is also a placeholder for operand number N. It is
857: used when the operand needs to appear more than once in the insn.
858:
859: In construction, `match_dup' acts just like `match_operand': the
860: operand is substituted into the insn being constructed. But in
861: matching, `match_dup' behaves differently. It assumes that operand
862: number N has already been determined by a `match_operand'
863: appearing earlier in the recognition template, and it matches only
864: an identical-looking expression.
865:
866: `(match_operator:M N PREDICATE [OPERANDS...])'
867: This pattern is a kind of placeholder for a variable RTL expression
868: code.
869:
870: When constructing an insn, it stands for an RTL expression whose
871: expression code is taken from that of operand N, and whose
872: operands are constructed from the patterns OPERANDS.
873:
874: When matching an expression, it matches an expression if the
875: function PREDICATE returns nonzero on that expression *and* the
876: patterns OPERANDS match the operands of the expression.
877:
878: Suppose that the function `commutative_operator' is defined as
879: follows, to match any expression whose operator is one of the
880: commutative arithmetic operators of RTL and whose mode is MODE:
881:
882: int
883: commutative_operator (x, mode)
884: rtx x;
885: enum machine_mode mode;
886: {
887: enum rtx_code code = GET_CODE (x);
888: if (GET_MODE (x) != mode)
889: return 0;
890: return (GET_RTX_CLASS (code) == 'c'
891: || code == EQ || code == NE);
892: }
893:
894: Then the following pattern will match any RTL expression consisting
895: of a commutative operator applied to two general operands:
896:
897: (match_operator:SI 3 "commutative_operator"
898: [(match_operand:SI 1 "general_operand" "g")
899: (match_operand:SI 2 "general_operand" "g")])
900:
901: Here the vector `[OPERANDS...]' contains two patterns because the
902: expressions to be matched all contain two operands.
903:
904: When this pattern does match, the two operands of the commutative
905: operator are recorded as operands 1 and 2 of the insn. (This is
906: done by the two instances of `match_operand'.) Operand 3 of the
907: insn will be the entire commutative expression: use `GET_CODE
908: (operands[3])' to see which commutative operator was used.
909:
910: The machine mode M of `match_operator' works like that of
911: `match_operand': it is passed as the second argument to the
912: predicate function, and that function is solely responsible for
913: deciding whether the expression to be matched "has" that mode.
914:
915: When constructing an insn, argument 3 of the gen-function will
916: specify the operation (i.e. the expression code) for the
917: expression to be made. It should be an RTL expression, whose
918: expression code is copied into a new expression whose operands are
919: arguments 1 and 2 of the gen-function. The subexpressions of
920: argument 3 are not used; only its expression code matters.
921:
922: When `match_operator' is used in a pattern for matching an insn,
923: it usually best if the operand number of the `match_operator' is
924: higher than that of the actual operands of the insn. This improves
925: register allocation because the register allocator often looks at
926: operands 1 and 2 of insns to see if it can do register tying.
927:
928: There is no way to specify constraints in `match_operator'. The
929: operand of the insn which corresponds to the `match_operator'
930: never has any constraints because it is never reloaded as a whole.
931: However, if parts of its OPERANDS are matched by `match_operand'
932: patterns, those parts may have constraints of their own.
933:
934: `(match_op_dup:M N[OPERANDS...])'
935: Like `match_dup', except that it applies to operators instead of
936: operands. When constructing an insn, operand number N will be
937: substituted at this point. But in matching, `match_op_dup' behaves
938: differently. It assumes that operand number N has already been
939: determined by a `match_operator' appearing earlier in the
940: recognition template, and it matches only an identical-looking
941: expression.
942:
943: `(match_parallel N PREDICATE [SUBPAT...])'
944: This pattern is a placeholder for an insn that consists of a
945: `parallel' expression with a variable number of elements. This
946: expression should only appear at the top level of an insn pattern.
947:
948: When constructing an insn, operand number N will be substituted at
949: this point. When matching an insn, it matches if the body of the
950: insn is a `parallel' expression with at least as many elements as
951: the vector of SUBPAT expressions in the `match_parallel', if each
952: SUBPAT matches the corresponding element of the `parallel', *and*
953: the function PREDICATE returns nonzero on the `parallel' that is
954: the body of the insn. It is the responsibility of the predicate
955: to validate elements of the `parallel' beyond those listed in the
956: `match_parallel'.
957:
958: A typical use of `match_parallel' is to match load and store
959: multiple expressions, which can contains a variable number of
960: elements in a `parallel'. For example,
961:
962: (define_insn ""
963: [(match_parallel 0 "load_multiple_operation"
964: [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
965: (match_operand:SI 2 "memory_operand" "m"))
966: (use (reg:SI 179))
967: (clobber (reg:SI 179))])]
968: ""
969: "loadm 0,0,%1,%2")
970:
971: This example comes from `a29k.md'. The function
972: `load_multiple_operations' is defined in `a29k.c' and checks that
973: subsequent elements in the `parallel' are the same as the `set' in
974: the pattern, except that they are referencing subsequent registers
975: and memory locations.
976:
977: An insn that matches this pattern might look like:
978:
979: (parallel
980: [(set (reg:SI 20) (mem:SI (reg:SI 100)))
981: (use (reg:SI 179))
982: (clobber (reg:SI 179))
983: (set (reg:SI 21)
984: (mem:SI (plus:SI (reg:SI 100)
985: (const_int 4))))
986: (set (reg:SI 22)
987: (mem:SI (plus:SI (reg:SI 100)
988: (const_int 8))))])
989:
990: `(match_par_dup N [SUBPAT...])'
991: Like `match_op_dup', but for `match_parallel' instead of
992: `match_operator'.
993:
994: `(address (match_operand:M N "address_operand" ""))'
995: This complex of expressions is a placeholder for an operand number
996: N in a "load address" instruction: an operand which specifies a
997: memory location in the usual way, but for which the actual operand
998: value used is the address of the location, not the contents of the
999: location.
1000:
1001: `address' expressions never appear in RTL code, only in machine
1002: descriptions. And they are used only in machine descriptions that
1003: do not use the operand constraint feature. When operand
1004: constraints are in use, the letter `p' in the constraint serves
1005: this purpose.
1006:
1007: M is the machine mode of the *memory location being addressed*,
1008: not the machine mode of the address itself. That mode is always
1009: the same on a given target machine (it is `Pmode', which normally
1010: is `SImode'), so there is no point in mentioning it; thus, no
1011: machine mode is written in the `address' expression. If some day
1012: support is added for machines in which addresses of different
1013: kinds of objects appear differently or are used differently (such
1014: as the PDP-10), different formats would perhaps need different
1015: machine modes and these modes might be written in the `address'
1016: expression.
1017:
1018:
1019: File: gcc.info, Node: Output Template, Next: Output Statement, Prev: RTL Template, Up: Machine Desc
1020:
1021: Output Templates and Operand Substitution
1022: =========================================
1023:
1024: The "output template" is a string which specifies how to output the
1025: assembler code for an instruction pattern. Most of the template is a
1026: fixed string which is output literally. The character `%' is used to
1027: specify where to substitute an operand; it can also be used to identify
1028: places where different variants of the assembler require different
1029: syntax.
1030:
1031: In the simplest case, a `%' followed by a digit N says to output
1032: operand N at that point in the string.
1033:
1034: `%' followed by a letter and a digit says to output an operand in an
1035: alternate fashion. Four letters have standard, built-in meanings
1036: described below. The machine description macro `PRINT_OPERAND' can
1037: define additional letters with nonstandard meanings.
1038:
1039: `%cDIGIT' can be used to substitute an operand that is a constant
1040: value without the syntax that normally indicates an immediate operand.
1041:
1042: `%nDIGIT' is like `%cDIGIT' except that the value of the constant is
1043: negated before printing.
1044:
1045: `%aDIGIT' can be used to substitute an operand as if it were a
1046: memory reference, with the actual operand treated as the address. This
1047: may be useful when outputting a "load address" instruction, because
1048: often the assembler syntax for such an instruction requires you to
1049: write the operand as if it were a memory reference.
1050:
1051: `%lDIGIT' is used to substitute a `label_ref' into a jump
1052: instruction.
1053:
1054: `%=' outputs a number which is unique to each instruction in the
1055: entire compilation. This is useful for making local labels to be
1056: referred to more than once in a single template that generates multiple
1057: assembler instructions.
1058:
1059: `%' followed by a punctuation character specifies a substitution that
1060: does not use an operand. Only one case is standard: `%%' outputs a `%'
1061: into the assembler code. Other nonstandard cases can be defined in the
1062: `PRINT_OPERAND' macro. You must also define which punctuation
1063: characters are valid with the `PRINT_OPERAND_PUNCT_VALID_P' macro.
1064:
1065: The template may generate multiple assembler instructions. Write
1066: the text for the instructions, with `\;' between them.
1067:
1068: When the RTL contains two operands which are required by constraint
1069: to match each other, the output template must refer only to the
1070: lower-numbered operand. Matching operands are not always identical,
1071: and the rest of the compiler arranges to put the proper RTL expression
1072: for printing into the lower-numbered operand.
1073:
1074: One use of nonstandard letters or punctuation following `%' is to
1075: distinguish between different assembler languages for the same machine;
1076: for example, Motorola syntax versus MIT syntax for the 68000. Motorola
1077: syntax requires periods in most opcode names, while MIT syntax does
1078: not. For example, the opcode `movel' in MIT syntax is `move.l' in
1079: Motorola syntax. The same file of patterns is used for both kinds of
1080: output syntax, but the character sequence `%.' is used in each place
1081: where Motorola syntax wants a period. The `PRINT_OPERAND' macro for
1082: Motorola syntax defines the sequence to output a period; the macro for
1083: MIT syntax defines it to do nothing.
1084:
1085: As a special case, a template consisting of the single character `#'
1086: instructs the compiler to first split the insn, and then output the
1087: resulting instructions separately. This helps eliminate redundancy in
1088: the output templates. If you have a `define_insn' that needs to emit
1089: multiple assembler instructions, and there is an matching `define_split'
1090: already defined, then you can simply use `#' as the output template
1091: instead of writing an output template that emits the multiple assembler
1092: instructions.
1093:
1094: If `ASSEMBLER_DIALECT' is defined, templates may contain strings of
1095: the form `{option0|option1|option2}' which represent variants of
1096: assembler language syntax. *Note Instruction Output::.
1097:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.