source: trunk/third/gcc/gcc.info-15 @ 8834

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