![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to rtl.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to rtl.texi CVS log | Up to [GCC 2.x] / gcc |
1.1 root 1: @c Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc.
2: @c This is part of the GCC manual.
3: @c For copying conditions, see the file gcc.texi.
4:
5: @ifset INTERNALS
6: @node RTL, Machine Desc, Passes, Top
7: @chapter RTL Representation
8: @cindex RTL representation
9: @cindex representation of RTL
10: @cindex Register Transfer Language (RTL)
11:
12: Most of the work of the compiler is done on an intermediate representation
13: called register transfer language. In this language, the instructions to be
14: output are described, pretty much one by one, in an algebraic form that
15: describes what the instruction does.
16:
17: RTL is inspired by Lisp lists. It has both an internal form, made up of
18: structures that point at other structures, and a textual form that is used
19: in the machine description and in printed debugging dumps. The textual
20: form uses nested parentheses to indicate the pointers in the internal form.
21:
22: @menu
23: * RTL Objects:: Expressions vs vectors vs strings vs integers.
24: * Accessors:: Macros to access expression operands or vector elts.
25: * Flags:: Other flags in an RTL expression.
26: * Machine Modes:: Describing the size and format of a datum.
27: * Constants:: Expressions with constant values.
28: * Regs and Memory:: Expressions representing register contents or memory.
29: * Arithmetic:: Expressions representing arithmetic on other expressions.
30: * Comparisons:: Expressions representing comparison of expressions.
31: * Bit Fields:: Expressions representing bit-fields in memory or reg.
32: * Conversions:: Extending, truncating, floating or fixing.
33: * RTL Declarations:: Declaring volatility, constancy, etc.
34: * Side Effects:: Expressions for storing in registers, etc.
35: * Incdec:: Embedded side-effects for autoincrement addressing.
36: * Assembler:: Representing @code{asm} with operands.
37: * Insns:: Expression types for entire insns.
38: * Calls:: RTL representation of function call insns.
39: * Sharing:: Some expressions are unique; others *must* be copied.
40: @end menu
41:
42: @node RTL Objects, Accessors, RTL, RTL
43: @section RTL Object Types
44: @cindex RTL object types
45:
46: @cindex RTL integers
47: @cindex RTL strings
48: @cindex RTL vectors
49: @cindex RTL expression
50: @cindex RTX (See RTL)
51: RTL uses four kinds of objects: expressions, integers, strings and vectors.
52: Expressions are the most important ones. An RTL expression (``RTX'', for
53: short) is a C structure, but it is usually referred to with a pointer; a
54: type that is given the typedef name @code{rtx}.
55:
56: An integer is simply an @code{int}; their written form uses decimal digits.
57:
58: A string is a sequence of characters. In core it is represented as a
59: @code{char *} in usual C fashion, and it is written in C syntax as well.
60: However, strings in RTL may never be null. If you write an empty string in
61: a machine description, it is represented in core as a null pointer rather
62: than as a pointer to a null character. In certain contexts, these null
63: pointers instead of strings are valid. Within RTL code, strings are most
64: commonly found inside @code{symbol_ref} expressions, but they appear in
65: other contexts in the RTL expressions that make up machine descriptions.
66:
67: A vector contains an arbitrary number of pointers to expressions. The
68: number of elements in the vector is explicitly present in the vector.
69: The written form of a vector consists of square brackets
70: (@samp{[@dots{}]}) surrounding the elements, in sequence and with
71: whitespace separating them. Vectors of length zero are not created;
72: null pointers are used instead.
73:
74: @cindex expression codes
75: @cindex codes, RTL expression
76: @findex GET_CODE
77: @findex PUT_CODE
78: Expressions are classified by @dfn{expression codes} (also called RTX
79: codes). The expression code is a name defined in @file{rtl.def}, which is
80: also (in upper case) a C enumeration constant. The possible expression
81: codes and their meanings are machine-independent. The code of an RTX can
82: be extracted with the macro @code{GET_CODE (@var{x})} and altered with
83: @code{PUT_CODE (@var{x}, @var{newcode})}.
84:
85: The expression code determines how many operands the expression contains,
86: and what kinds of objects they are. In RTL, unlike Lisp, you cannot tell
87: by looking at an operand what kind of object it is. Instead, you must know
88: from its context---from the expression code of the containing expression.
89: For example, in an expression of code @code{subreg}, the first operand is
90: to be regarded as an expression and the second operand as an integer. In
91: an expression of code @code{plus}, there are two operands, both of which
92: are to be regarded as expressions. In a @code{symbol_ref} expression,
93: there is one operand, which is to be regarded as a string.
94:
95: Expressions are written as parentheses containing the name of the
96: expression type, its flags and machine mode if any, and then the operands
97: of the expression (separated by spaces).
98:
99: Expression code names in the @samp{md} file are written in lower case,
100: but when they appear in C code they are written in upper case. In this
101: manual, they are shown as follows: @code{const_int}.
102:
103: @cindex (nil)
104: @cindex nil
105: In a few contexts a null pointer is valid where an expression is normally
106: wanted. The written form of this is @code{(nil)}.
107:
108: @node Accessors, Flags, RTL Objects, RTL
109: @section Access to Operands
110: @cindex accessors
111: @cindex access to operands
112: @cindex operand access
113:
114: @cindex RTL format
115: For each expression type @file{rtl.def} specifies the number of contained
116: objects and their kinds, with four possibilities: @samp{e} for expression
117: (actually a pointer to an expression), @samp{i} for integer, @samp{s} for
118: string, and @samp{E} for vector of expressions. The sequence of letters
119: for an expression code is called its @dfn{format}. Thus, the format of
120: @code{subreg} is @samp{ei}.@refill
121:
122: @cindex RTL format characters
123: A few other format characters are used occasionally:
124:
125: @table @code
126: @item u
127: @samp{u} is equivalent to @samp{e} except that it is printed differently
128: in debugging dumps. It is used for pointers to insns.
129:
130: @item n
131: @samp{n} is equivalent to @samp{i} except that it is printed differently
132: in debugging dumps. It is used for the line number or code number of a
133: @code{note} insn.
134:
135: @item S
136: @samp{S} indicates a string which is optional. In the RTL objects in
137: core, @samp{S} is equivalent to @samp{s}, but when the object is read,
138: from an @samp{md} file, the string value of this operand may be omitted.
139: An omitted string is taken to be the null string.
140:
141: @item V
142: @samp{V} indicates a vector which is optional. In the RTL objects in
143: core, @samp{V} is equivalent to @samp{E}, but when the object is read
144: from an @samp{md} file, the vector value of this operand may be omitted.
145: An omitted vector is effectively the same as a vector of no elements.
146:
147: @item 0
148: @samp{0} means a slot whose contents do not fit any normal category.
149: @samp{0} slots are not printed at all in dumps, and are often used in
150: special ways by small parts of the compiler.
151: @end table
152:
153: There are macros to get the number of operands, the format, and the
154: class of an expression code:
155:
156: @table @code
157: @findex GET_RTX_LENGTH
158: @item GET_RTX_LENGTH (@var{code})
159: Number of operands of an RTX of code @var{code}.
160:
161: @findex GET_RTX_FORMAT
162: @item GET_RTX_FORMAT (@var{code})
163: The format of an RTX of code @var{code}, as a C string.
164:
165: @findex GET_RTX_CLASS
166: @cindex classes of RTX codes
167: @item GET_RTX_CLASS (@var{code})
168: A single character representing the type of RTX operation that code
169: @var{code} performs.
170:
171: The following classes are defined:
172:
173: @table @code
174: @item o
175: An RTX code that represents an actual object, such as @code{reg} or
176: @code{mem}. @code{subreg} is not in this class.
177:
178: @item <
179: An RTX code for a comparison. The codes in this class are
180: @code{NE}, @code{EQ}, @code{LE}, @code{LT}, @code{GE}, @code{GT},
181: @code{LEU}, @code{LTU}, @code{GEU}, @code{GTU}.@refill
182:
183: @item 1
184: An RTX code for a unary arithmetic operation, such as @code{neg}.
185:
186: @item c
187: An RTX code for a commutative binary operation, other than @code{NE}
188: and @code{EQ} (which have class @samp{<}).
189:
190: @item 2
191: An RTX code for a noncommutative binary operation, such as @code{MINUS}.
192:
193: @item b
194: An RTX code for a bitfield operation (@code{ZERO_EXTRACT} and
195: @code{SIGN_EXTRACT}).
196:
197: @item 3
198: An RTX code for other three input operations, such as @code{IF_THEN_ELSE}.
199:
200: @item i
201: An RTX code for a machine insn (@code{INSN}, @code{JUMP_INSN}, and
202: @code{CALL_INSN}).@refill
203:
204: @item m
205: An RTX code for something that matches in insns, such as @code{MATCH_DUP}.
206:
207: @item x
208: All other RTX codes.
209: @end table
210: @end table
211:
212: @findex XEXP
213: @findex XINT
214: @findex XSTR
215: Operands of expressions are accessed using the macros @code{XEXP},
216: @code{XINT} and @code{XSTR}. Each of these macros takes two arguments: an
217: expression-pointer (RTX) and an operand number (counting from zero).
218: Thus,@refill
219:
220: @example
221: XEXP (@var{x}, 2)
222: @end example
223:
224: @noindent
225: accesses operand 2 of expression @var{x}, as an expression.
226:
227: @example
228: XINT (@var{x}, 2)
229: @end example
230:
231: @noindent
232: accesses the same operand as an integer. @code{XSTR}, used in the same
233: fashion, would access it as a string.
234:
235: Any operand can be accessed as an integer, as an expression or as a string.
236: You must choose the correct method of access for the kind of value actually
237: stored in the operand. You would do this based on the expression code of
238: the containing expression. That is also how you would know how many
239: operands there are.
240:
241: For example, if @var{x} is a @code{subreg} expression, you know that it has
242: two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
243: and @code{XINT (@var{x}, 1)}. If you did @code{XINT (@var{x}, 0)}, you
244: would get the address of the expression operand but cast as an integer;
245: that might occasionally be useful, but it would be cleaner to write
246: @code{(int) XEXP (@var{x}, 0)}. @code{XEXP (@var{x}, 1)} would also
247: compile without error, and would return the second, integer operand cast as
248: an expression pointer, which would probably result in a crash when
249: accessed. Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
250: but this will access memory past the end of the expression with
251: unpredictable results.@refill
252:
253: Access to operands which are vectors is more complicated. You can use the
254: macro @code{XVEC} to get the vector-pointer itself, or the macros
255: @code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
256: vector.
257:
258: @table @code
259: @findex XVEC
260: @item XVEC (@var{exp}, @var{idx})
261: Access the vector-pointer which is operand number @var{idx} in @var{exp}.
262:
263: @findex XVECLEN
264: @item XVECLEN (@var{exp}, @var{idx})
265: Access the length (number of elements) in the vector which is
266: in operand number @var{idx} in @var{exp}. This value is an @code{int}.
267:
268: @findex XVECEXP
269: @item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
270: Access element number @var{eltnum} in the vector which is
271: in operand number @var{idx} in @var{exp}. This value is an RTX.
272:
273: It is up to you to make sure that @var{eltnum} is not negative
274: and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
275: @end table
276:
277: All the macros defined in this section expand into lvalues and therefore
278: can be used to assign the operands, lengths and vector elements as well as
279: to access them.
280:
281: @node Flags, Machine Modes, Accessors, RTL
282: @section Flags in an RTL Expression
283: @cindex flags in RTL expression
284:
285: RTL expressions contain several flags (one-bit bit-fields) that are used
286: in certain types of expression. Most often they are accessed with the
287: following macros:
288:
289: @table @code
290: @findex MEM_VOLATILE_P
291: @cindex @code{mem} and @samp{/v}
292: @cindex @code{volatil}, in @code{mem}
293: @cindex @samp{/v} in RTL dump
294: @item MEM_VOLATILE_P (@var{x})
295: In @code{mem} expressions, nonzero for volatile memory references.
296: Stored in the @code{volatil} field and printed as @samp{/v}.
297:
298: @findex MEM_IN_STRUCT_P
299: @cindex @code{mem} and @samp{/s}
300: @cindex @code{in_struct}, in @code{mem}
301: @cindex @samp{/s} in RTL dump
302: @item MEM_IN_STRUCT_P (@var{x})
303: In @code{mem} expressions, nonzero for reference to an entire
304: structure, union or array, or to a component of one. Zero for
305: references to a scalar variable or through a pointer to a scalar.
306: Stored in the @code{in_struct} field and printed as @samp{/s}.
307:
308: @findex REG_LOOP_TEST_P
309: @cindex @code{reg} and @samp{/s}
310: @cindex @code{in_struct}, in @code{reg}
311: @item REG_LOOP_TEST_P
312: In @code{reg} expressions, nonzero if this register's entire life is
313: contained in the exit test code for some loop. Stored in the
314: @code{in_struct} field and printed as @samp{/s}.
315:
316: @findex REG_USERVAR_P
317: @cindex @code{reg} and @samp{/v}
318: @cindex @code{volatil}, in @code{reg}
319: @item REG_USERVAR_P (@var{x})
320: In a @code{reg}, nonzero if it corresponds to a variable present in
321: the user's source code. Zero for temporaries generated internally by
322: the compiler. Stored in the @code{volatil} field and printed as
323: @samp{/v}.
324:
325: @cindex @samp{/i} in RTL dump
326: @findex REG_FUNCTION_VALUE_P
327: @cindex @code{reg} and @samp{/i}
328: @cindex @code{integrated}, in @code{reg}
329: @item REG_FUNCTION_VALUE_P (@var{x})
330: Nonzero in a @code{reg} if it is the place in which this function's
331: value is going to be returned. (This happens only in a hard
332: register.) Stored in the @code{integrated} field and printed as
333: @samp{/i}.
334:
335: The same hard register may be used also for collecting the values of
336: functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
337: in this kind of use.
338:
339: @findex RTX_UNCHANGING_P
340: @cindex @code{reg} and @samp{/u}
341: @cindex @code{mem} and @samp{/u}
342: @cindex @code{unchanging}, in @code{reg} and @code{mem}
343: @cindex @samp{/u} in RTL dump
344: @item RTX_UNCHANGING_P (@var{x})
345: Nonzero in a @code{reg} or @code{mem} if the value is not changed.
346: (This flag is not set for memory references via pointers to constants.
347: Such pointers only guarantee that the object will not be changed
348: explicitly by the current function. The object might be changed by
349: other functions or by aliasing.) Stored in the
350: @code{unchanging} field and printed as @samp{/u}.
351:
352: @findex RTX_INTEGRATED_P
353: @cindex @code{integrated}, in @code{insn}
354: @item RTX_INTEGRATED_P (@var{insn})
355: Nonzero in an insn if it resulted from an in-line function call.
356: Stored in the @code{integrated} field and printed as @samp{/i}. This
357: may be deleted; nothing currently depends on it.
358:
359: @findex SYMBOL_REF_USED
360: @cindex @code{used}, in @code{symbol_ref}
361: @item SYMBOL_REF_USED (@var{x})
362: In a @code{symbol_ref}, indicates that @var{x} has been used. This is
363: normally only used to ensure that @var{x} is only declared external
364: once. Stored in the @code{used} field.
365:
366: @findex SYMBOL_REF_FLAG
367: @cindex @code{symbol_ref} and @samp{/v}
368: @cindex @code{volatil}, in @code{symbol_ref}
369: @item SYMBOL_REF_FLAG (@var{x})
370: In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
371: Stored in the @code{volatil} field and printed as @samp{/v}.
372:
373: @findex LABEL_OUTSIDE_LOOP_P
374: @cindex @code{label_ref} and @samp{/s}
375: @cindex @code{in_struct}, in @code{label_ref}
376: @item LABEL_OUTSIDE_LOOP_P
377: In @code{label_ref} expressions, nonzero if this is a reference to a
378: label that is outside the innermost loop containing the reference to the
379: label. Stored in the @code{in_struct} field and printed as @samp{/s}.
380:
381: @findex INSN_DELETED_P
382: @cindex @code{volatil}, in @code{insn}
383: @item INSN_DELETED_P (@var{insn})
384: In an insn, nonzero if the insn has been deleted. Stored in the
385: @code{volatil} field and printed as @samp{/v}.
386:
387: @findex INSN_ANNULLED_BRANCH_P
388: @cindex @code{insn} and @samp{/u}
389: @cindex @code{unchanging}, in @code{insn}
390: @item INSN_ANNULLED_BRANCH_P (@var{insn})
391: In an @code{insn} in the delay slot of a branch insn, indicates that an
392: annulling branch should be used. See the discussion under
393: @code{sequence} below. Stored in the @code{unchanging} field and printed
394: as @samp{/u}.
395:
396: @findex INSN_FROM_TARGET_P
397: @cindex @code{insn} and @samp{/s}
398: @cindex @code{in_struct}, in @code{insn}
399: @cindex @samp{/s} in RTL dump
400: @item INSN_FROM_TARGET_P (@var{insn})
401: In an @code{insn} in a delay slot of a branch, indicates that the insn
402: is from the target of the branch. If the branch insn has
403: @code{INSN_ANNULLED_BRANCH_P} set, this insn should only be executed if
404: the branch is taken. For annulled branches with this bit clear, the
405: insn should be executed only if the branch is not taken. Stored in the
406: @code{in_struct} field and printed as @samp{/s}.
407:
408: @findex CONSTANT_POOL_ADDRESS_P
409: @cindex @code{symbol_ref} and @samp{/u}
410: @cindex @code{unchanging}, in @code{symbol_ref}
411: @item CONSTANT_POOL_ADDRESS_P (@var{x})
412: Nonzero in a @code{symbol_ref} if it refers to part of the current
413: function's ``constants pool''. These are addresses close to the
414: beginning of the function, and GNU CC assumes they can be addressed
415: directly (perhaps with the help of base registers). Stored in the
416: @code{unchanging} field and printed as @samp{/u}.
417:
418: @findex CONST_CALL_P
419: @cindex @code{call_insn} and @samp{/u}
420: @cindex @code{unchanging}, in @code{call_insn}
421: @item CONST_CALL_P (@var{x})
422: In a @code{call_insn}, indicates that the insn represents a call to a const
423: function. Stored in the @code{unchanging} field and printed as @samp{/u}.
424:
425: @findex LABEL_PRESERVE_P
426: @cindex @code{code_label} and @samp{/i}
427: @cindex @code{in_struct}, in @code{code_label}
428: @item LABEL_PRESERVE_P (@var{x})
429: In a @code{code_label}, indicates that the label can never be deleted.
430: Labels referenced by a a non-local goto will have this bit set. Stored
431: in the @code{in_struct} field and printed as @samp{/s}.
432:
433: @findex SCHED_GROUP_P
434: @cindex @code{insn} and @samp{/i}
435: @cindex @code{in_struct}, in @code{insn}
436: @item SCHED_GROUP_P (@var{insn})
437: During instruction scheduling, in an insn, indicates that the previous insn
438: must be scheduled together with this insn. This is used to ensure that
439: certain groups of instructions will not be split up by the instruction
440: scheduling pass, for example, @code{use} insns before a @code{call_insn} may
441: not be separated from the @code{call_insn}. Stored in the @code{in_struct}
442: field and printed as @samp{/s}.
443: @end table
444:
445: These are the fields which the above macros refer to:
446:
447: @table @code
448: @findex used
449: @item used
450: Normally, this flag is used only momentarily, at the end of RTL
451: generation for a function, to count the number of times an expression
452: appears in insns. Expressions that appear more than once are copied,
453: according to the rules for shared structure (@pxref{Sharing}).
454:
455: In a @code{symbol_ref}, it indicates that an external declaration for
456: the symbol has already been written.
457:
458: In a @code{reg}, it is used by the leaf register renumbering code to ensure
459: that each register is only renumbered once.
460:
461: @findex volatil
462: @item volatil
463: This flag is used in @code{mem},@code{symbol_ref} and @code{reg}
464: expressions and in insns. In RTL dump files, it is printed as
465: @samp{/v}.
466:
467: @cindex volatile memory references
468: In a @code{mem} expression, it is 1 if the memory reference is volatile.
469: Volatile memory references may not be deleted, reordered or combined.
470:
471: In a @code{symbol_ref} expression, it is used for machine-specific
472: purposes.
473:
474: In a @code{reg} expression, it is 1 if the value is a user-level variable.
475: 0 indicates an internal compiler temporary.
476:
477: In an insn, 1 means the insn has been deleted.
478:
479: @findex in_struct
480: @item in_struct
481: In @code{mem} expressions, it is 1 if the memory datum referred to is
482: all or part of a structure or array; 0 if it is (or might be) a scalar
483: variable. A reference through a C pointer has 0 because the pointer
484: might point to a scalar variable. This information allows the compiler
485: to determine something about possible cases of aliasing.
486:
487: In an insn in the delay slot of a branch, 1 means that this insn is from
488: the target of the branch.
489:
490: During instruction scheduling, in an insn, 1 means that this insn must be
491: scheduled as part of a group together with the previous insn.
492:
493: In @code{reg} expressions, it is 1 if the register has its entire life
494: contained within the test expression of some loopl.
495:
496: In @code{label_ref} expressions, 1 means that the referenced label is
497: outside the innermost loop containing the insn in which the @code{label_ref}
498: was found.
499:
500: In @code{code_label} expressions, it is 1 if the label may never be deleted.
501: This is used for labels which are the target of non-local gotos.
502:
503: In an RTL dump, this flag is represented as @samp{/s}.
504:
505: @findex unchanging
506: @item unchanging
507: In @code{reg} and @code{mem} expressions, 1 means
508: that the value of the expression never changes.
509:
510: In an insn, 1 means that this is an annulling branch.
511:
512: In a @code{symbol_ref} expression, 1 means that this symbol addresses
513: something in the per-function constants pool.
514:
515: In a @code{call_insn}, 1 means that this instruction is a call to a
516: const function.
517:
518: In an RTL dump, this flag is represented as @samp{/u}.
519:
520: @findex integrated
521: @item integrated
522: In some kinds of expressions, including insns, this flag means the
523: rtl was produced by procedure integration.
524:
525: In a @code{reg} expression, this flag indicates the register
526: containing the value to be returned by the current function. On
527: machines that pass parameters in registers, the same register number
528: may be used for parameters as well, but this flag is not set on such
529: uses.
530: @end table
531:
532: @node Machine Modes, Constants, Flags, RTL
533: @section Machine Modes
534: @cindex machine modes
535:
536: @findex enum machine_mode
537: A machine mode describes a size of data object and the representation used
538: for it. In the C code, machine modes are represented by an enumeration
539: type, @code{enum machine_mode}, defined in @file{machmode.def}. Each RTL
540: expression has room for a machine mode and so do certain kinds of tree
541: expressions (declarations and types, to be precise).
542:
543: In debugging dumps and machine descriptions, the machine mode of an RTL
544: expression is written after the expression code with a colon to separate
545: them. The letters @samp{mode} which appear at the end of each machine mode
546: name are omitted. For example, @code{(reg:SI 38)} is a @code{reg}
547: expression with machine mode @code{SImode}. If the mode is
548: @code{VOIDmode}, it is not written at all.
549:
550: Here is a table of machine modes. The term ``byte'' below refers to an
551: object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
552:
553: @table @code
554: @findex QImode
555: @item QImode
556: ``Quarter-Integer'' mode represents a single byte treated as an integer.
557:
558: @findex HImode
559: @item HImode
560: ``Half-Integer'' mode represents a two-byte integer.
561:
562: @findex PSImode
563: @item PSImode
564: ``Partial Single Integer'' mode represents an integer which occupies
565: four bytes but which doesn't really use all four. On some machines,
566: this is the right mode to use for pointers.
567:
568: @findex SImode
569: @item SImode
570: ``Single Integer'' mode represents a four-byte integer.
571:
572: @findex PDImode
573: @item PDImode
574: ``Partial Double Integer'' mode represents an integer which occupies
575: eight bytes but which doesn't really use all eight. On some machines,
576: this is the right mode to use for certain pointers.
577:
578: @findex DImode
579: @item DImode
580: ``Double Integer'' mode represents an eight-byte integer.
581:
582: @findex TImode
583: @item TImode
584: ``Tetra Integer'' (?) mode represents a sixteen-byte integer.
585:
586: @findex SFmode
587: @item SFmode
588: ``Single Floating'' mode represents a single-precision (four byte) floating
589: point number.
590:
591: @findex DFmode
592: @item DFmode
593: ``Double Floating'' mode represents a double-precision (eight byte) floating
594: point number.
595:
596: @findex XFmode
597: @item XFmode
598: ``Extended Floating'' mode represents a triple-precision (twelve byte)
599: floating point number. This mode is used for IEEE extended floating
600: point.
601:
602: @findex TFmode
603: @item TFmode
604: ``Tetra Floating'' mode represents a quadruple-precision (sixteen byte)
605: floating point number.
606:
607: @findex CCmode
608: @item CCmode
609: ``Condition Code'' mode represents the value of a condition code, which
610: is a machine-specific set of bits used to represent the result of a
611: comparison operation. Other machine-specific modes may also be used for
612: the condition code. These modes are not used on machines that use
613: @code{cc0} (see @pxref{Condition Code}).
614:
615: @findex BLKmode
616: @item BLKmode
617: ``Block'' mode represents values that are aggregates to which none of
618: the other modes apply. In RTL, only memory references can have this mode,
619: and only if they appear in string-move or vector instructions. On machines
620: which have no such instructions, @code{BLKmode} will not appear in RTL.
621:
622: @findex VOIDmode
623: @item VOIDmode
624: Void mode means the absence of a mode or an unspecified mode.
625: For example, RTL expressions of code @code{const_int} have mode
626: @code{VOIDmode} because they can be taken to have whatever mode the context
627: requires. In debugging dumps of RTL, @code{VOIDmode} is expressed by
628: the absence of any mode.
629:
630: @findex SCmode
631: @findex DCmode
632: @findex XCmode
633: @findex TCmode
634: @item SCmode, DCmode, XCmode, TCmode
635: These modes stand for a complex number represented as a pair of
636: floating point values. The values are in @code{SFmode}, @code{DFmode},
637: @code{XFmode}, and @code{TFmode}, respectively. Since C does not
638: support complex numbers, these machine modes are only partially
639: implemented.
640: @end table
641:
642: The machine description defines @code{Pmode} as a C macro which expands
643: into the machine mode used for addresses. Normally this is the mode
644: whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
645:
646: The only modes which a machine description @i{must} support are
647: @code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
648: @code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
649: The compiler will attempt to use @code{DImode} for 8-byte structures and
650: unions, but this can be prevented by overriding the definition of
651: @code{MAX_FIXED_MODE_SIZE}. Alternatively, you can have the compiler
652: use @code{TImode} for 16-byte structures and unions. Likewise, you can
653: arrange for the C type @code{short int} to avoid using @code{HImode}.
654:
655: @cindex mode classes
656: Very few explicit references to machine modes remain in the compiler and
657: these few references will soon be removed. Instead, the machine modes
658: are divided into mode classes. These are represented by the enumeration
659: type @code{enum mode_class} defined in @file{machmode.h}. The possible
660: mode classes are:
661:
662: @table @code
663: @findex MODE_INT
664: @item MODE_INT
665: Integer modes. By default these are @code{QImode}, @code{HImode},
666: @code{SImode}, @code{DImode}, and @code{TImode}.
667:
668: @findex MODE_PARTIAL_INT
669: @item MODE_PARTIAL_INT
670: The ``partial integer'' modes, @code{PSImode} and @code{PDImode}.
671:
672: @findex MODE_FLOAT
673: @item MODE_FLOAT
674: floating point modes. By default these are @code{SFmode}, @code{DFmode},
675: @code{XFmode} and @code{TFmode}.
676:
677: @findex MODE_COMPLEX_INT
678: @item MODE_COMPLEX_INT
679: Complex integer modes. (These are not currently implemented).
680:
681: @findex MODE_COMPLEX_FLOAT
682: @item MODE_COMPLEX_FLOAT
683: Complex floating point modes. By default these are @code{SCmode},
684: @code{DCmode}, @code{XCmode}, and @code{TCmode}.
685:
686: @findex MODE_FUNCTION
687: @item MODE_FUNCTION
688: Algol or Pascal function variables including a static chain.
689: (These are not currently implemented).
690:
691: @findex MODE_CC
692: @item MODE_CC
693: Modes representing condition code values. These are @code{CCmode} plus
694: any modes listed in the @code{EXTRA_CC_MODES} macro. @xref{Jump Patterns},
695: also see @ref{Condition Code}.
696:
697: @findex MODE_RANDOM
698: @item MODE_RANDOM
699: This is a catchall mode class for modes which don't fit into the above
700: classes. Currently @code{VOIDmode} and @code{BLKmode} are in
701: @code{MODE_RANDOM}.
702: @end table
703:
704: Here are some C macros that relate to machine modes:
705:
706: @table @code
707: @findex GET_MODE
708: @item GET_MODE (@var{x})
709: Returns the machine mode of the RTX @var{x}.
710:
711: @findex PUT_MODE
712: @item PUT_MODE (@var{x}, @var{newmode})
713: Alters the machine mode of the RTX @var{x} to be @var{newmode}.
714:
715: @findex NUM_MACHINE_MODES
716: @item NUM_MACHINE_MODES
717: Stands for the number of machine modes available on the target
718: machine. This is one greater than the largest numeric value of any
719: machine mode.
720:
721: @findex GET_MODE_NAME
722: @item GET_MODE_NAME (@var{m})
723: Returns the name of mode @var{m} as a string.
724:
725: @findex GET_MODE_CLASS
726: @item GET_MODE_CLASS (@var{m})
727: Returns the mode class of mode @var{m}.
728:
729: @findex GET_MODE_WIDER_MODE
730: @item GET_MODE_WIDER_MODE (@var{m})
731: Returns the next wider natural mode. E.g.,
732: @code{GET_WIDER_MODE(QImode)} returns @code{HImode}.
733:
734: @findex GET_MODE_SIZE
735: @item GET_MODE_SIZE (@var{m})
736: Returns the size in bytes of a datum of mode @var{m}.
737:
738: @findex GET_MODE_BITSIZE
739: @item GET_MODE_BITSIZE (@var{m})
740: Returns the size in bits of a datum of mode @var{m}.
741:
742: @findex GET_MODE_MASK
743: @item GET_MODE_MASK (@var{m})
744: Returns a bitmask containing 1 for all bits in a word that fit within
745: mode @var{m}. This macro can only be used for modes whose bitsize is
746: less than or equal to @code{HOST_BITS_PER_INT}.
747:
748: @findex GET_MODE_ALIGNMENT
749: @item GET_MODE_ALIGNMENT (@var{m)})
750: Return the required alignment, in bits, for an object of mode @var{m}.
751:
752: @findex GET_MODE_UNIT_SIZE
753: @item GET_MODE_UNIT_SIZE (@var{m})
754: Returns the size in bytes of the subunits of a datum of mode @var{m}.
755: This is the same as @code{GET_MODE_SIZE} except in the case of complex
756: modes. For them, the unit size is the size of the real or imaginary
757: part.
758:
759: @findex GET_MODE_NUNITS
760: @item GET_MODE_NUNITS (@var{m})
761: Returns the number of units contained in a mode, i.e.,
762: @code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
763:
764: @findex GET_CLASS_NARROWEST_MODE
765: @item GET_CLASS_NARROWEST_MODE (@var{c})
766: Returns the narrowest mode in mode class @var{c}.
767: @end table
768:
769: @findex byte_mode
770: @findex word_mode
771: The global variables @code{byte_mode} and @code{word_mode} contain
772: modes whose classes are @code{MODE_INT} and whose bitsizes are
773: @code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively. On 32-bit
774: machines, these are @code{QImode} and @code{SImode}, respectively.
775:
776: @node Constants, Regs and Memory, Machine Modes, RTL
777: @section Constant Expression Types
778: @cindex RTL constants
779: @cindex RTL constant expression types
780:
781: The simplest RTL expressions are those that represent constant values.
782:
783: @table @code
784: @findex const_int
785: @item (const_int @var{i})
786: This type of expression represents the integer value @var{i}. @var{i}
787: is customarily accessed with the macro @code{INTVAL} as in
788: @code{INTVAL (@var{exp})}, which is equivalent to @code{XINT (@var{exp}, 0)}.
789:
790: Keep in mind that the result of @code{INTVAL} is an integer on the host
791: machine. If the host machine has more bits in an @code{int} than the
792: target machine has in the mode in which the constant will be used, then
793: some of the bits you get from @code{INTVAL} will be superfluous. In
794: many cases, for proper results, you must carefully disregard the values
795: of those bits.
796:
797: @findex const0_rtx
798: @findex const1_rtx
799: @findex const2_rtx
800: @findex constm1_rtx
801: There is only one expression object for the integer value zero; it is
802: the value of the variable @code{const0_rtx}. Likewise, the only
803: expression for integer value one is found in @code{const1_rtx}, the only
804: expression for integer value two is found in @code{const2_rtx}, and the
805: only expression for integer value negative one is found in
806: @code{constm1_rtx}. Any attempt to create an expression of code
807: @code{const_int} and value zero, one, two or negative one will return
808: @code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
809: @code{constm1_rtx} as appropriate.@refill
810:
811: @findex const_true_rtx
812: Similarly, there is only one object for the integer whose value is
813: @code{STORE_FLAG_VALUE}. It is found in @code{const_true_rtx}. If
814: @code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
815: @code{const1_rtx} will point to the same object. If
816: @code{STORE_FLAG_VALUE} is -1, @code{const_true_rtx} and
817: @code{constm1_rtx} will point to the same object.@refill
818:
819: @findex const_double
820: @item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{})
821: Represents either a floating-point constant of mode @var{m} or an
822: integer constant that is too large to fit into @code{HOST_BITS_PER_INT}
823: bits but small enough to fit within twice that number of bits (GNU CC
824: does not provide a mechanism to represent even larger constants). In
825: the latter case, @var{m} will be @code{VOIDmode}.
826:
827: @findex CONST_DOUBLE_MEM
828: @findex CONST_DOUBLE_CHAIN
829: @var{addr} is used to contain the @code{mem} expression that corresponds
830: to the location in memory that at which the constant can be found. If
831: it has not been allocated a memory location, but is on the chain of all
832: @code{const_double} expressions in this compilation (maintained using an
833: undisplayed field), @var{addr} contains @code{const0_rtx}. If it is not
834: on the chain, @var{addr} contains @code{cc0_rtx}. @var{addr} is
835: customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the
836: chain field via @code{CONST_DOUBLE_CHAIN}.@refill
837:
838: @findex CONST_DOUBLE_LOW
1.1.1.2 ! root 839: If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1.1 root 840: @var{i0} and @var{i1}. @var{i0} is customarily accessed with the macro
841: @code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
842:
843: If the constant is floating point (either single or double precision),
844: then the number of integers used to store the value depends on the size
845: of @code{REAL_VALUE_TYPE} (@pxref{Cross-compilation}). The integers
846: represent a @code{double}. To convert them to a @code{double}, do
847:
848: @example
849: union real_extract u;
850: bcopy (&CONST_DOUBLE_LOW (x), &u, sizeof u);
851: @end example
852:
853: @noindent
854: and then refer to @code{u.d}.
855:
856: @findex CONST0_RTX
857: @findex CONST1_RTX
858: @findex CONST2_RTX
859: The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
860: value 0 in mode @var{mode}. If mode @var{mode} is of mode class
861: @code{MODE_INT}, it returns @code{const0_rtx}. Otherwise, it returns a
862: @code{CONST_DOUBLE} expression in mode @var{mode}. Similarly, the macro
863: @code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
864: mode @var{mode} and similarly for @code{CONST2_RTX}.
865:
866: @findex const_string
867: @item (const_string @var{str})
868: Represents a constant string with value @var{str}. Currently this is
869: used only for insn attributes (@pxref{Insn Attributes}) since constant
870: strings in C are placed in memory.
871:
872: @findex symbol_ref
1.1.1.2 ! root 873: @item (symbol_ref:@var{mode} @var{symbol})
1.1 root 874: Represents the value of an assembler label for data. @var{symbol} is
875: a string that describes the name of the assembler label. If it starts
876: with a @samp{*}, the label is the rest of @var{symbol} not including
877: the @samp{*}. Otherwise, the label is @var{symbol}, usually prefixed
878: with @samp{_}.
879:
1.1.1.2 ! root 880: The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
! 881: Usually that is the only mode for which a symbol is directly valid.
! 882:
1.1 root 883: @findex label_ref
884: @item (label_ref @var{label})
885: Represents the value of an assembler label for code. It contains one
886: operand, an expression, which must be a @code{code_label} that appears
887: in the instruction sequence to identify the place where the label
888: should go.
889:
890: The reason for using a distinct expression type for code label
891: references is so that jump optimization can distinguish them.
892:
893: @item (const:@var{m} @var{exp})
894: Represents a constant that is the result of an assembly-time
895: arithmetic computation. The operand, @var{exp}, is an expression that
896: contains only constants (@code{const_int}, @code{symbol_ref} and
897: @code{label_ref} expressions) combined with @code{plus} and
898: @code{minus}. However, not all combinations are valid, since the
899: assembler cannot do arbitrary arithmetic on relocatable symbols.
900:
901: @var{m} should be @code{Pmode}.
902:
903: @findex high
904: @item (high:@var{m} @var{exp})
905: Represents the high-order bits of @var{exp}, usually a
906: @code{symbol_ref}. The number of bits is machine-dependent and is
907: normally the number of bits specified in an instruction that initializes
908: the high order bits of a register. It is used with @code{lo_sum} to
909: represent the typical two-instruction sequence used in RISC machines to
910: reference a global memory location.
911:
912: @var{m} should be @code{Pmode}.
913: @end table
914:
915: @node Regs and Memory, Arithmetic, Constants, RTL
916: @section Registers and Memory
917: @cindex RTL register expressions
918: @cindex RTL memory expressions
919:
920: Here are the RTL expression types for describing access to machine
921: registers and to main memory.
922:
923: @table @code
924: @findex reg
925: @cindex hard registers
926: @cindex pseudo registers
927: @item (reg:@var{m} @var{n})
928: For small values of the integer @var{n} (less than
929: @code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
930: register number @var{n}: a @dfn{hard register}. For larger values of
931: @var{n}, it stands for a temporary value or @dfn{pseudo register}.
932: The compiler's strategy is to generate code assuming an unlimited
933: number of such pseudo registers, and later convert them into hard
934: registers or into memory references.
935:
936: @var{m} is the machine mode of the reference. It is necessary because
937: machines can generally refer to each register in more than one mode.
938: For example, a register may contain a full word but there may be
939: instructions to refer to it as a half word or as a single byte, as
940: well as instructions to refer to it as a floating point number of
941: various precisions.
942:
943: Even for a register that the machine can access in only one mode,
944: the mode must always be specified.
945:
946: The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
947: description, since the number of hard registers on the machine is an
948: invariant characteristic of the machine. Note, however, that not
949: all of the machine registers must be general registers. All the
950: machine registers that can be used for storage of data are given
951: hard register numbers, even those that can be used only in certain
952: instructions or can hold only certain types of data.
953:
954: A hard register may be accessed in various modes throughout one
955: function, but each pseudo register is given a natural mode
956: and is accessed only in that mode. When it is necessary to describe
957: an access to a pseudo register using a nonnatural mode, a @code{subreg}
958: expression is used.
959:
960: A @code{reg} expression with a machine mode that specifies more than
961: one word of data may actually stand for several consecutive registers.
962: If in addition the register number specifies a hardware register, then
963: it actually represents several consecutive hardware registers starting
964: with the specified one.
965:
966: Each pseudo register number used in a function's RTL code is
967: represented by a unique @code{reg} expression.
968:
969: @findex FIRST_VIRTUAL_REGISTER
970: @findex LAST_VIRTUAL_REGISTER
971: Some pseudo register numbers, those within the range of
972: @code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
973: appear during the RTL generation phase and are eliminated before the
974: optimization phases. These represent locations in the stack frame that
975: cannot be determined until RTL generation for the function has been
976: completed. The following virtual register numbers are defined:
977:
978: @table @code
979: @findex VIRTUAL_INCOMING_ARGS_REGNUM
980: @item VIRTUAL_INCOMING_ARGS_REGNUM
981: This points to the first word of the incoming arguments passed on the
982: stack. Normally these arguments are placed there by the caller, but the
983: callee may have pushed some arguments that were previously passed in
984: registers.
985:
986: @cindex @code{FIRST_PARM_OFFSET} and virtual registers
987: @cindex @code{ARG_POINTER_REGNUM} and virtual registers
988: When RTL generation is complete, this virtual register is replaced
989: by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
990: value of @code{FIRST_PARM_OFFSET}.
991:
992: @findex VIRTUAL_STACK_VARS_REGNUM
993: @cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
994: @item VIRTUAL_STACK_VARS_REGNUM
995: If @code{FRAME_GROWS_DOWNWARDS} is defined, this points to immediately
996: above the first variable on the stack. Otherwise, it points to the
997: first variable on the stack.
998:
999: @cindex @code{STARTING_FRAME_OFFSET} and virtual registers
1000: @cindex @code{FRAME_POINTER_REGNUM} and virtual registers
1001: It is replaced with the sum of the register given by
1002: @code{FRAME_POINTER_REGNUM} and the value @code{STARTING_FRAME_OFFSET}.
1003:
1004: @findex VIRTUAL_STACK_DYNAMIC_REGNUM
1005: @item VIRTUAL_STACK_DYNAMIC_REGNUM
1006: This points to the location of dynamically allocated memory on the stack
1007: immediately after the stack pointer has been adjusted by the amount of
1008: memory desired.
1009:
1010: @cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
1011: @cindex @code{STACK_POINTER_REGNUM} and virtual registers
1012: It is replaced by the sum of the register given by
1013: @code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
1014:
1015: @findex VIRTUAL_OUTGOING_ARGS_REGNUM
1016: @item VIRTUAL_OUTGOING_ARGS_REGNUM
1017: This points to the location in the stack at which outgoing arguments
1018: should be written when the stack is pre-pushed (arguments pushed using
1019: push insns should always use @code{STACK_POINTER_REGNUM}).
1020:
1021: @cindex @code{STACK_POINTER_OFFSET} and virtual registers
1022: It is replaced by the sum of the register given by
1023: @code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
1024: @end table
1025:
1026: @findex subreg
1027: @item (subreg:@var{m} @var{reg} @var{wordnum})
1028: @code{subreg} expressions are used to refer to a register in a machine
1029: mode other than its natural one, or to refer to one register of
1030: a multi-word @code{reg} that actually refers to several registers.
1031:
1032: Each pseudo-register has a natural mode. If it is necessary to
1033: operate on it in a different mode---for example, to perform a fullword
1034: move instruction on a pseudo-register that contains a single
1035: byte---the pseudo-register must be enclosed in a @code{subreg}. In
1036: such a case, @var{wordnum} is zero.
1037:
1038: Usually @var{m} is at least as narrow as the mode of @var{reg}, in which
1039: case it is restricting consideration to only the bits of @var{reg} that
1040: are in @var{m}. However, sometimes @var{m} is wider than the mode of
1041: @var{reg}. These @code{subreg} expressions are often called
1042: @dfn{paradoxical}. They are used in cases where we want to refer to an
1043: object in a wider mode but do not care what value the additional bits
1044: have. The reload pass ensures that paradoxical references are only
1045: made to hard registers.
1046:
1047: The other use of @code{subreg} is to extract the individual registers of
1048: a multi-register value. Machine modes such as @code{DImode} and
1049: @code{TImode} can indicate values longer than a word, values which
1050: usually require two or more consecutive registers. To access one of the
1051: registers, use a @code{subreg} with mode @code{SImode} and a
1052: @var{wordnum} that says which register.
1053:
1054: @cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
1055: The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says
1056: that word number zero is the most significant part; otherwise, it is
1057: the least significant part.
1058:
1059: @cindex combiner pass
1060: @cindex reload pass
1061: @cindex @code{subreg}, special reload handling
1062: Between the combiner pass and the reload pass, it is possible to have a
1063: paradoxical @code{subreg} which contains a @code{mem} instead of a
1064: @code{reg} as its first operand. After the reload pass, it is also
1065: possible to have a non-paradoxical @code{subreg} which contains a
1066: @code{mem}; this usually occurs when the @code{mem} is a stack slot
1067: which replaced a pseudo register.
1068:
1069: Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
1070: using a @code{subreg}. On some machines the most significant part of a
1071: @code{DFmode} value does not have the same format as a single-precision
1072: floating value.
1073:
1074: It is also not valid to access a single word of a multi-word value in a
1075: hard register when less registers can hold the value than would be
1076: expected from its size. For example, some 32-bit machines have
1077: floating-point registers that can hold an entire @code{DFmode} value.
1078: If register 10 were such a register @code{(subreg:SI (reg:DF 10) 1)}
1079: would be invalid because there is no way to convert that reference to
1080: a single machine register. The reload pass prevents @code{subreg}
1081: expressions such as these from being formed.
1082:
1083: @findex SUBREG_REG
1084: @findex SUBREG_WORD
1085: The first operand of a @code{subreg} expression is customarily accessed
1086: with the @code{SUBREG_REG} macro and the second operand is customarily
1087: accessed with the @code{SUBREG_WORD} macro.
1088:
1089: @findex scratch
1090: @cindex scratch operands
1091: @item (scratch:@var{m})
1092: This represents a scratch register that will be required for the
1093: execution of a single instruction and not used subsequently. It is
1094: converted into a @code{reg} by either the local register allocator or
1095: the reload pass.
1096:
1097: @code{scratch} is usually present inside a @code{clobber} operation
1098: (@pxref{Side Effects}).
1099:
1100: @findex cc0
1101: @cindex condition code register
1102: @item (cc0)
1103: This refers to the machine's condition code register. It has no
1104: operands and may not have a machine mode. There are two ways to use it:
1105:
1106: @itemize @bullet
1107: @item
1108: To stand for a complete set of condition code flags. This is best on
1109: most machines, where each comparison sets the entire series of flags.
1110:
1111: With this technique, @code{(cc0)} may be validly used in only two
1112: contexts: as the destination of an assignment (in test and compare
1113: instructions) and in comparison operators comparing against zero
1114: (@code{const_int} with value zero; that is to say, @code{const0_rtx}).
1115:
1116: @item
1117: To stand for a single flag that is the result of a single condition.
1118: This is useful on machines that have only a single flag bit, and in
1119: which comparison instructions must specify the condition to test.
1120:
1121: With this technique, @code{(cc0)} may be validly used in only two
1122: contexts: as the destination of an assignment (in test and compare
1123: instructions) where the source is a comparison operator, and as the
1124: first operand of @code{if_then_else} (in a conditional branch).
1125: @end itemize
1126:
1127: @findex cc0_rtx
1128: There is only one expression object of code @code{cc0}; it is the
1129: value of the variable @code{cc0_rtx}. Any attempt to create an
1130: expression of code @code{cc0} will return @code{cc0_rtx}.
1131:
1132: Instructions can set the condition code implicitly. On many machines,
1133: nearly all instructions set the condition code based on the value that
1134: they compute or store. It is not necessary to record these actions
1135: explicitly in the RTL because the machine description includes a
1136: prescription for recognizing the instructions that do so (by means of
1137: the macro @code{NOTICE_UPDATE_CC}). @xref{Condition Code}. Only
1138: instructions whose sole purpose is to set the condition code, and
1139: instructions that use the condition code, need mention @code{(cc0)}.
1140:
1141: On some machines, the condition code register is given a register number
1142: and a @code{reg} is used instead of @code{(cc0)}. This is usually the
1143: preferable approach if only a small subset of instructions modify the
1144: condition code. Other machines store condition codes in general
1145: registers; in such cases a pseudo register should be used.
1146:
1147: Some machines, such as the Sparc and RS/6000, have two sets of
1148: arithmetic instructions, one that sets and one that does not set the
1149: condition code. This is best handled by normally generating the
1150: instruction that does not set the condition code, and making a pattern
1151: that both performs the arithmetic and sets the condition code register
1152: (which would not be @code{(cc0)} in this case). For examples, search
1153: for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
1154:
1155: @findex pc
1156: @item (pc)
1157: @cindex program counter
1158: This represents the machine's program counter. It has no operands and
1159: may not have a machine mode. @code{(pc)} may be validly used only in
1160: certain specific contexts in jump instructions.
1161:
1162: @findex pc_rtx
1163: There is only one expression object of code @code{pc}; it is the value
1164: of the variable @code{pc_rtx}. Any attempt to create an expression of
1165: code @code{pc} will return @code{pc_rtx}.
1166:
1167: All instructions that do not jump alter the program counter implicitly
1168: by incrementing it, but there is no need to mention this in the RTL.
1169:
1170: @findex mem
1171: @item (mem:@var{m} @var{addr})
1172: This RTX represents a reference to main memory at an address
1173: represented by the expression @var{addr}. @var{m} specifies how large
1174: a unit of memory is accessed.
1175: @end table
1176:
1177: @node Arithmetic, Comparisons, Regs and Memory, RTL
1178: @section RTL Expressions for Arithmetic
1179: @cindex arithmetic, in RTL
1180: @cindex math, in RTL
1181: @cindex RTL expressions for arithmetic
1182:
1183: Unless otherwise specified, all the operands of arithmetic expressions
1184: must be valid for mode @var{m}. An operand is valid for mode @var{m}
1185: if it has mode @var{m}, or if it is a @code{const_int} or
1186: @code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
1187:
1188: For commutative binary operations, constants should be placed in the
1189: second operand.
1190:
1191: @table @code
1192: @findex plus
1193: @cindex RTL addition
1194: @cindex RTL sum
1195: @item (plus:@var{m} @var{x} @var{y})
1196: Represents the sum of the values represented by @var{x} and @var{y}
1197: carried out in machine mode @var{m}.
1198:
1199: @findex lo_sum
1200: @item (lo_sum:@var{m} @var{x} @var{y})
1201: Like @code{plus}, except that it represents that sum of @var{x} and the
1202: low-order bits of @var{y}. The number of low order bits is
1203: machine-dependent but is normally the number of bits in a @code{Pmode}
1204: item minus the number of bits set by the @code{high} code
1205: (@pxref{Constants}).
1206:
1207: @var{m} should be @code{Pmode}.
1208:
1209: @findex minus
1210: @cindex RTL subtraction
1211: @cindex RTL difference
1212: @item (minus:@var{m} @var{x} @var{y})
1213: Like @code{plus} but represents subtraction.
1214:
1215: @findex compare
1216: @cindex RTL comparison
1217: @item (compare:@var{m} @var{x} @var{y})
1218: Represents the result of subtracting @var{y} from @var{x} for purposes
1219: of comparison. The result is computed without overflow, as if with
1220: infinite precision.
1221:
1222: Of course, machines can't really subtract with infinite precision.
1223: However, they can pretend to do so when only the sign of the
1224: result will be used, which is the case when the result is stored
1225: in the condition code. And that is the only way this kind of expression
1226: may validly be used: as a value to be stored in the condition codes.
1227:
1228: The mode @var{m} is not related to the modes of @var{x} and @var{y},
1229: but instead is the mode of the condition code value. If @code{(cc0)}
1230: is used, it is @code{VOIDmode}. Otherwise it is some mode in class
1231: @code{MODE_CC}, often @code{CCmode}. @xref{Condition Code}.
1232:
1233: Normally, @var{x} and @var{y} must have the same mode. Otherwise,
1234: @code{compare} is valid only if the mode of @var{x} is in class
1235: @code{MODE_INT} and @var{y} is a @code{const_int} or
1236: @code{const_double} with mode @code{VOIDmode}. The mode of @var{x}
1237: determines what mode the comparison is to be done in; thus it must not
1238: be @code{VOIDmode}.
1239:
1240: If one of the operands is a constant, it should be placed in the
1241: second operand and the comparison code adjusted as appropriate.
1242:
1243: A @code{compare} specifying two @code{VOIDmode} constants is not valid
1244: since there is no way to know in what mode the comparison is to be
1245: performed; the comparison must either be folded during the compilation
1246: or the first operand must be loaded into a register while its mode is
1247: still known.
1248:
1249: @findex neg
1250: @item (neg:@var{m} @var{x})
1251: Represents the negation (subtraction from zero) of the value represented
1252: by @var{x}, carried out in mode @var{m}.
1253:
1254: @findex mult
1255: @cindex multiplication
1256: @cindex product
1257: @item (mult:@var{m} @var{x} @var{y})
1258: Represents the signed product of the values represented by @var{x} and
1259: @var{y} carried out in machine mode @var{m}.
1260:
1261: Some machines support a multiplication that generates a product wider
1262: than the operands. Write the pattern for this as
1263:
1264: @example
1265: (mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
1266: @end example
1267:
1268: where @var{m} is wider than the modes of @var{x} and @var{y}, which need
1269: not be the same.
1270:
1271: Write patterns for unsigned widening multiplication similarly using
1272: @code{zero_extend}.
1273:
1274: @findex div
1275: @cindex division
1276: @cindex signed division
1277: @cindex quotient
1278: @item (div:@var{m} @var{x} @var{y})
1279: Represents the quotient in signed division of @var{x} by @var{y},
1280: carried out in machine mode @var{m}. If @var{m} is a floating point
1281: mode, it represents the exact quotient; otherwise, the integerized
1282: quotient.
1283:
1284: Some machines have division instructions in which the operands and
1285: quotient widths are not all the same; you should represent
1286: such instructions using @code{truncate} and @code{sign_extend} as in,
1287:
1288: @example
1289: (truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
1290: @end example
1291:
1292: @findex udiv
1293: @cindex unsigned division
1294: @cindex division
1295: @item (udiv:@var{m} @var{x} @var{y})
1296: Like @code{div} but represents unsigned division.
1297:
1298: @findex mod
1299: @findex umod
1300: @cindex remainder
1301: @cindex division
1302: @item (mod:@var{m} @var{x} @var{y})
1303: @itemx (umod:@var{m} @var{x} @var{y})
1304: Like @code{div} and @code{udiv} but represent the remainder instead of
1305: the quotient.
1306:
1307: @findex smin
1308: @findex smax
1309: @cindex signed minimum
1310: @cindex signed maximum
1311: @item (smin:@var{m} @var{x} @var{y})
1312: @itemx (smax:@var{m} @var{x} @var{y})
1313: Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
1314: @var{x} and @var{y}, interpreted as signed integers in mode @var{m}.
1315:
1316: @findex umin
1317: @findex umax
1318: @cindex unsigned minimum and maximum
1319: @item (umin:@var{m} @var{x} @var{y})
1320: @itemx (umax:@var{m} @var{x} @var{y})
1321: Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
1322: integers.
1323:
1324: @findex not
1325: @cindex complement, bitwise
1326: @cindex bitwise complement
1327: @item (not:@var{m} @var{x})
1328: Represents the bitwise complement of the value represented by @var{x},
1329: carried out in mode @var{m}, which must be a fixed-point machine mode.
1330:
1331: @findex and
1332: @cindex logical-and, bitwise
1333: @cindex bitwise logical-and
1334: @item (and:@var{m} @var{x} @var{y})
1335: Represents the bitwise logical-and of the values represented by
1336: @var{x} and @var{y}, carried out in machine mode @var{m}, which must be
1337: a fixed-point machine mode.
1338:
1339: @findex ior
1340: @cindex inclusive-or, bitwise
1341: @cindex bitwise inclusive-or
1342: @item (ior:@var{m} @var{x} @var{y})
1343: Represents the bitwise inclusive-or of the values represented by @var{x}
1344: and @var{y}, carried out in machine mode @var{m}, which must be a
1345: fixed-point mode.
1346:
1347: @findex xor
1348: @cindex exclusive-or, bitwise
1349: @cindex bitwise exclusive-or
1350: @item (xor:@var{m} @var{x} @var{y})
1351: Represents the bitwise exclusive-or of the values represented by @var{x}
1352: and @var{y}, carried out in machine mode @var{m}, which must be a
1353: fixed-point mode.
1354:
1355: @findex ashift
1356: @cindex left shift
1357: @cindex shift
1358: @cindex arithmetic shift
1359: @item (ashift:@var{m} @var{x} @var{c})
1360: Represents the result of arithmetically shifting @var{x} left by @var{c}
1361: places. @var{x} have mode @var{m}, a fixed-point machine mode. @var{c}
1362: be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
1363: mode is determined by the mode called for in the machine description
1364: entry for the left-shift instruction. For example, on the Vax, the mode
1365: of @var{c} is @code{QImode} regardless of @var{m}.
1366:
1367: @findex lshift
1368: @cindex left shift
1369: @cindex logical shift
1370: @item (lshift:@var{m} @var{x} @var{c})
1.1.1.2 ! root 1371: Like @code{ashift} but for logical left shift. @code{ashift} and
1.1 root 1372: @code{lshift} are identical operations; we customarily use @code{ashift}
1373: for both.
1374:
1375: @findex lshiftrt
1376: @cindex right shift
1377: @findex ashiftrt
1378: @item (lshiftrt:@var{m} @var{x} @var{c})
1379: @itemx (ashiftrt:@var{m} @var{x} @var{c})
1380: Like @code{lshift} and @code{ashift} but for right shift. Unlike
1381: the case for left shift, these two operations are distinct.
1382:
1383: @findex rotate
1384: @cindex rotate
1385: @cindex left rotate
1386: @findex rotatert
1387: @cindex right rotate
1388: @item (rotate:@var{m} @var{x} @var{c})
1389: @itemx (rotatert:@var{m} @var{x} @var{c})
1390: Similar but represent left and right rotate. If @var{c} is a constant,
1391: use @code{rotate}.
1392:
1393: @findex abs
1394: @cindex absolute value
1395: @item (abs:@var{m} @var{x})
1396: Represents the absolute value of @var{x}, computed in mode @var{m}.
1397:
1398: @findex sqrt
1399: @cindex square root
1400: @item (sqrt:@var{m} @var{x})
1401: Represents the square root of @var{x}, computed in mode @var{m}.
1402: Most often @var{m} will be a floating point mode.
1403:
1404: @findex ffs
1405: @item (ffs:@var{m} @var{x})
1406: Represents one plus the index of the least significant 1-bit in
1407: @var{x}, represented as an integer of mode @var{m}. (The value is
1408: zero if @var{x} is zero.) The mode of @var{x} need not be @var{m};
1409: depending on the target machine, various mode combinations may be
1410: valid.
1411: @end table
1412:
1413: @node Comparisons, Bit Fields, Arithmetic, RTL
1414: @section Comparison Operations
1415: @cindex RTL comparison operations
1416:
1417: Comparison operators test a relation on two operands and are considered
1418: to represent a machine-dependent nonzero value described by, but not
1419: necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
1420: if the relation holds, or zero if it does not. The mode of the
1421: comparison operation is independent of the mode of the data being
1422: compared. If the comparison operation is being tested (e.g., the first
1423: operand of an @code{if_then_else}), the mode must be @code{VOIDmode}.
1424: If the comparison operation is producing data to be stored in some
1425: variable, the mode must be in class @code{MODE_INT}. All comparison
1426: operations producing data must use the same mode, which is
1427: machine-specific.
1428:
1429: @cindex condition codes
1430: There are two ways that comparison operations may be used. The
1431: comparison operators may be used to compare the condition codes
1432: @code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}. Such
1433: a construct actually refers to the result of the preceding instruction
1434: in which the condition codes were set. The instructing setting the
1435: condition code must be adjacent to the instruction using the condition
1436: code; only @code{note} insns may separate them.
1437:
1438: Alternatively, a comparison operation may directly compare two data
1439: objects. The mode of the comparison is determined by the operands; they
1440: must both be valid for a common machine mode. A comparison with both
1441: operands constant would be invalid as the machine mode could not be
1442: deduced from it, but such a comparison should never exist in RTL due to
1443: constant folding.
1444:
1445: In the example above, if @code{(cc0)} were last set to
1446: @code{(compare @var{x} @var{y})}, the comparison operation is
1447: identical to @code{(eq @var{x} @var{y})}. Usually only one style
1448: of comparisons is supported on a particular machine, but the combine
1449: pass will try to merge the operations to produce the @code{eq} shown
1450: in case it exists in the context of the particular insn involved.
1451:
1452: Inequality comparisons come in two flavors, signed and unsigned. Thus,
1453: there are distinct expression codes @code{gt} and @code{gtu} for signed and
1454: unsigned greater-than. These can produce different results for the same
1455: pair of integer values: for example, 1 is signed greater-than -1 but not
1456: unsigned greater-than, because -1 when regarded as unsigned is actually
1457: @code{0xffffffff} which is greater than 1.
1458:
1459: The signed comparisons are also used for floating point values. Floating
1460: point comparisons are distinguished by the machine modes of the operands.
1461:
1462: @table @code
1463: @findex eq
1464: @cindex equal
1465: @item (eq:@var{m} @var{x} @var{y})
1466: 1 if the values represented by @var{x} and @var{y} are equal,
1467: otherwise 0.
1468:
1469: @findex ne
1470: @cindex not equal
1471: @item (ne:@var{m} @var{x} @var{y})
1472: 1 if the values represented by @var{x} and @var{y} are not equal,
1473: otherwise 0.
1474:
1475: @findex gt
1476: @cindex greater than
1477: @item (gt:@var{m} @var{x} @var{y})
1478: 1 if the @var{x} is greater than @var{y}. If they are fixed-point,
1479: the comparison is done in a signed sense.
1480:
1481: @findex gtu
1482: @cindex greater than
1483: @cindex unsigned greater than
1484: @item (gtu:@var{m} @var{x} @var{y})
1485: Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
1486:
1487: @findex lt
1488: @cindex less than
1489: @findex ltu
1490: @cindex unsigned less than
1491: @item (lt:@var{m} @var{x} @var{y})
1492: @itemx (ltu:@var{m} @var{x} @var{y})
1493: Like @code{gt} and @code{gtu} but test for ``less than''.
1494:
1495: @findex ge
1496: @cindex greater than
1497: @findex geu
1498: @cindex unsigned greater than
1499: @item (ge:@var{m} @var{x} @var{y})
1500: @itemx (geu:@var{m} @var{x} @var{y})
1501: Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
1502:
1503: @findex le
1504: @cindex less than or equal
1505: @findex leu
1506: @cindex unsigned less than
1507: @item (le:@var{m} @var{x} @var{y})
1508: @itemx (leu:@var{m} @var{x} @var{y})
1509: Like @code{gt} and @code{gtu} but test for ``less than or equal''.
1510:
1511: @findex if_then_else
1512: @item (if_then_else @var{cond} @var{then} @var{else})
1513: This is not a comparison operation but is listed here because it is
1514: always used in conjunction with a comparison operation. To be
1515: precise, @var{cond} is a comparison expression. This expression
1516: represents a choice, according to @var{cond}, between the value
1517: represented by @var{then} and the one represented by @var{else}.
1518:
1519: On most machines, @code{if_then_else} expressions are valid only
1520: to express conditional jumps.
1521:
1522: @findex cond
1523: @item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
1524: Similar to @code{if_then_else}, but more general. Each of @var{test1},
1525: @var{test2}, @dots{} is performed in turn. The result of this expression is
1526: the @var{value} corresponding to the first non-zero test, or @var{default} if
1527: none of the tests are non-zero expressions.
1528:
1529: This is currently not valid for instruction patterns and is supported only
1530: for insn attributes. @xref{Insn Attributes}.
1531: @end table
1532:
1533: @node Bit Fields, Conversions, Comparisons, RTL
1534: @section Bit Fields
1535: @cindex bit fields
1536:
1537: Special expression codes exist to represent bit-field instructions.
1538: These types of expressions are lvalues in RTL; they may appear
1539: on the left side of an assignment, indicating insertion of a value
1540: into the specified bit field.
1541:
1542: @table @code
1543: @findex sign_extract
1544: @cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
1545: @item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
1546: This represents a reference to a sign-extended bit field contained or
1547: starting in @var{loc} (a memory or register reference). The bit field
1548: is @var{size} bits wide and starts at bit @var{pos}. The compilation
1549: option @code{BITS_BIG_ENDIAN} says which end of the memory unit
1550: @var{pos} counts from.
1551:
1552: If @var{loc} is in memory, its mode must be a single-byte integer mode.
1553: If @var{loc} is in a register, the mode to use is specified by the
1554: operand of the @code{insv} or @code{extv} pattern
1555: (@pxref{Standard Names}) and is usually a full-word integer mode.
1556:
1557: The mode of @var{pos} is machine-specific and is also specified
1558: in the @code{insv} or @code{extv} pattern.
1559:
1560: The mode @var{m} is the same as the mode that would be used for
1561: @var{loc} if it were a register.
1562:
1563: @findex zero_extract
1564: @item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
1565: Like @code{sign_extract} but refers to an unsigned or zero-extended
1566: bit field. The same sequence of bits are extracted, but they
1567: are filled to an entire word with zeros instead of by sign-extension.
1568: @end table
1569:
1570: @node Conversions, RTL Declarations, Bit Fields, RTL
1571: @section Conversions
1572: @cindex conversions
1573: @cindex machine mode conversions
1574:
1575: All conversions between machine modes must be represented by
1576: explicit conversion operations. For example, an expression
1577: which is the sum of a byte and a full word cannot be written as
1578: @code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
1579: operation requires two operands of the same machine mode.
1580: Therefore, the byte-sized operand is enclosed in a conversion
1581: operation, as in
1582:
1583: @example
1584: (plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
1585: @end example
1586:
1587: The conversion operation is not a mere placeholder, because there
1588: may be more than one way of converting from a given starting mode
1589: to the desired final mode. The conversion operation code says how
1590: to do it.
1591:
1592: For all conversion operations, @var{x} must not be @code{VOIDmode}
1593: because the mode in which to do the conversion would not be known.
1594: The conversion must either be done at compile-time or @var{x}
1595: must be placed into a register.
1596:
1597: @table @code
1598: @findex sign_extend
1599: @item (sign_extend:@var{m} @var{x})
1600: Represents the result of sign-extending the value @var{x}
1601: to machine mode @var{m}. @var{m} must be a fixed-point mode
1602: and @var{x} a fixed-point value of a mode narrower than @var{m}.
1603:
1604: @findex zero_extend
1605: @item (zero_extend:@var{m} @var{x})
1606: Represents the result of zero-extending the value @var{x}
1607: to machine mode @var{m}. @var{m} must be a fixed-point mode
1608: and @var{x} a fixed-point value of a mode narrower than @var{m}.
1609:
1610: @findex float_extend
1611: @item (float_extend:@var{m} @var{x})
1612: Represents the result of extending the value @var{x}
1613: to machine mode @var{m}. @var{m} must be a floating point mode
1614: and @var{x} a floating point value of a mode narrower than @var{m}.
1615:
1616: @findex truncate
1617: @item (truncate:@var{m} @var{x})
1618: Represents the result of truncating the value @var{x}
1619: to machine mode @var{m}. @var{m} must be a fixed-point mode
1620: and @var{x} a fixed-point value of a mode wider than @var{m}.
1621:
1622: @findex float_truncate
1623: @item (float_truncate:@var{m} @var{x})
1624: Represents the result of truncating the value @var{x}
1625: to machine mode @var{m}. @var{m} must be a floating point mode
1626: and @var{x} a floating point value of a mode wider than @var{m}.
1627:
1628: @findex float
1629: @item (float:@var{m} @var{x})
1630: Represents the result of converting fixed point value @var{x},
1631: regarded as signed, to floating point mode @var{m}.
1632:
1633: @findex unsigned_float
1634: @item (unsigned_float:@var{m} @var{x})
1635: Represents the result of converting fixed point value @var{x},
1636: regarded as unsigned, to floating point mode @var{m}.
1637:
1638: @findex fix
1639: @item (fix:@var{m} @var{x})
1640: When @var{m} is a fixed point mode, represents the result of
1641: converting floating point value @var{x} to mode @var{m}, regarded as
1642: signed. How rounding is done is not specified, so this operation may
1643: be used validly in compiling C code only for integer-valued operands.
1644:
1645: @findex unsigned_fix
1646: @item (unsigned_fix:@var{m} @var{x})
1647: Represents the result of converting floating point value @var{x} to
1648: fixed point mode @var{m}, regarded as unsigned. How rounding is done
1649: is not specified.
1650:
1651: @findex fix
1652: @item (fix:@var{m} @var{x})
1653: When @var{m} is a floating point mode, represents the result of
1654: converting floating point value @var{x} (valid for mode @var{m}) to an
1655: integer, still represented in floating point mode @var{m}, by rounding
1656: towards zero.
1657: @end table
1658:
1659: @node RTL Declarations, Side Effects, Conversions, RTL
1660: @section Declarations
1661: @cindex RTL declarations
1662: @cindex declarations, RTL
1663:
1664: Declaration expression codes do not represent arithmetic operations
1665: but rather state assertions about their operands.
1666:
1667: @table @code
1668: @findex strict_low_part
1669: @cindex @code{subreg}, in @code{strict_low_part}
1670: @item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
1671: This expression code is used in only one context: operand 0 of a
1672: @code{set} expression. In addition, the operand of this expression
1673: must be a non-paradoxical @code{subreg} expression.
1674:
1675: The presence of @code{strict_low_part} says that the part of the
1676: register which is meaningful in mode @var{n}, but is not part of
1677: mode @var{m}, is not to be altered. Normally, an assignment to such
1678: a subreg is allowed to have undefined effects on the rest of the
1679: register when @var{m} is less than a word.
1680: @end table
1681:
1682: @node Side Effects, Incdec, RTL Declarations, RTL
1683: @section Side Effect Expressions
1684: @cindex RTL side effect expressions
1685:
1686: The expression codes described so far represent values, not actions.
1687: But machine instructions never produce values; they are meaningful
1688: only for their side effects on the state of the machine. Special
1689: expression codes are used to represent side effects.
1690:
1691: The body of an instruction is always one of these side effect codes;
1692: the codes described above, which represent values, appear only as
1693: the operands of these.
1694:
1695: @table @code
1696: @findex set
1697: @item (set @var{lval} @var{x})
1698: Represents the action of storing the value of @var{x} into the place
1699: represented by @var{lval}. @var{lval} must be an expression
1700: representing a place that can be stored in: @code{reg} (or
1701: @code{subreg} or @code{strict_low_part}), @code{mem}, @code{pc} or
1702: @code{cc0}.@refill
1703:
1704: If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
1705: machine mode; then @var{x} must be valid for that mode.@refill
1706:
1707: If @var{lval} is a @code{reg} whose machine mode is less than the full
1708: width of the register, then it means that the part of the register
1709: specified by the machine mode is given the specified value and the
1710: rest of the register receives an undefined value. Likewise, if
1711: @var{lval} is a @code{subreg} whose machine mode is narrower than
1712: the mode of the register, the rest of the register can be changed in
1713: an undefined way.
1714:
1715: If @var{lval} is a @code{strict_low_part} of a @code{subreg}, then the
1716: part of the register specified by the machine mode of the
1717: @code{subreg} is given the value @var{x} and the rest of the register
1718: is not changed.@refill
1719:
1720: If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
1721: be either a @code{compare} expression or a value that may have any mode.
1722: The latter case represents a ``test'' instruction. The expression
1723: @code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
1724: @code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
1725: Use the former expression to save space during the compilation.
1726:
1727: @cindex jump instructions and @code{set}
1728: @cindex @code{if_then_else} usage
1729: If @var{lval} is @code{(pc)}, we have a jump instruction, and the
1730: possibilities for @var{x} are very limited. It may be a
1731: @code{label_ref} expression (unconditional jump). It may be an
1732: @code{if_then_else} (conditional jump), in which case either the
1733: second or the third operand must be @code{(pc)} (for the case which
1734: does not jump) and the other of the two must be a @code{label_ref}
1735: (for the case which does jump). @var{x} may also be a @code{mem} or
1736: @code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
1737: @code{mem}; these unusual patterns are used to represent jumps through
1738: branch tables.@refill
1739:
1740: If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
1741: @var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
1742: valid for the mode of @var{lval}.
1743:
1744: @findex SET_DEST
1745: @findex SET_SRC
1746: @var{lval} is customarily accessed with the @code{SET_DEST} macro and
1747: @var{x} with the @code{SET_SRC} macro.
1748:
1749: @findex return
1750: @item (return)
1751: As the sole expression in a pattern, represents a return from the
1752: current function, on machines where this can be done with one
1753: instruction, such as Vaxes. On machines where a multi-instruction
1754: ``epilogue'' must be executed in order to return from the function,
1755: returning is done by jumping to a label which precedes the epilogue, and
1756: the @code{return} expression code is never used.
1757:
1758: Inside an @code{if_then_else} expression, represents the value to be
1759: placed in @code{pc} to return to the caller.
1760:
1761: Note that an insn pattern of @code{(return)} is logically equivalent to
1762: @code{(set (pc) (return))}, but the latter form is never used.
1763:
1764: @findex call
1765: @item (call @var{function} @var{nargs})
1766: Represents a function call. @var{function} is a @code{mem} expression
1767: whose address is the address of the function to be called.
1768: @var{nargs} is an expression which can be used for two purposes: on
1769: some machines it represents the number of bytes of stack argument; on
1770: others, it represents the number of argument registers.
1771:
1772: Each machine has a standard machine mode which @var{function} must
1773: have. The machine description defines macro @code{FUNCTION_MODE} to
1774: expand into the requisite mode name. The purpose of this mode is to
1775: specify what kind of addressing is allowed, on machines where the
1776: allowed kinds of addressing depend on the machine mode being
1777: addressed.
1778:
1779: @findex clobber
1780: @item (clobber @var{x})
1781: Represents the storing or possible storing of an unpredictable,
1782: undescribed value into @var{x}, which must be a @code{reg},
1783: @code{scratch} or @code{mem} expression.
1784:
1785: One place this is used is in string instructions that store standard
1786: values into particular hard registers. It may not be worth the
1787: trouble to describe the values that are stored, but it is essential to
1788: inform the compiler that the registers will be altered, lest it
1789: attempt to keep data in them across the string instruction.
1790:
1791: If @var{x} is @code{(mem:BLK (const_int 0))}, it means that all memory
1792: locations must be presumed clobbered.
1793:
1794: Note that the machine description classifies certain hard registers as
1795: ``call-clobbered''. All function call instructions are assumed by
1796: default to clobber these registers, so there is no need to use
1797: @code{clobber} expressions to indicate this fact. Also, each function
1798: call is assumed to have the potential to alter any memory location,
1799: unless the function is declared @code{const}.
1800:
1801: If the last group of expressions in a @code{parallel} are each a
1802: @code{clobber} expression whose arguments are @code{reg} or
1803: @code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
1804: phase can add the appropriate @code{clobber} expressions to an insn it
1805: has constructed when doing so will cause a pattern to be matched.
1806:
1807: This feature can be used, for example, on a machine that whose multiply
1808: and add instructions don't use an MQ register but which has an
1809: add-accumulate instruction that does clobber the MQ register. Similarly,
1810: a combined instruction might require a temporary register while the
1811: constituent instructions might not.
1812:
1813: When a @code{clobber} expression for a register appears inside a
1814: @code{parallel} with other side effects, the register allocator
1815: guarantees that the register is unoccupied both before and after that
1816: insn. However, the reload phase may allocate a register used for one of
1817: the inputs unless the @samp{&} constraint is specified for the selected
1818: alternative (@pxref{Modifiers}). You can clobber either a specific hard
1819: register, a pseudo register, or a @code{scratch} expression; in the
1820: latter two cases, GNU CC will allocate a hard register that is available
1821: there for use as a temporary.
1822:
1823: For instructions that require a temporary register, you should use
1824: @code{scratch} instead of a pseudo-register because this will allow the
1825: combiner phase to add the @code{clobber} when required. You do this by
1826: coding (@code{clobber} (@code{match_scratch} @dots{})). If you do
1827: clobber a pseudo register, use one which appears nowhere else---generate
1828: a new one each time. Otherwise, you may confuse CSE.
1829:
1830: There is one other known use for clobbering a pseudo register in a
1831: @code{parallel}: when one of the input operands of the insn is also
1832: clobbered by the insn. In this case, using the same pseudo register in
1833: the clobber and elsewhere in the insn produces the expected results.
1834:
1835: @findex use
1836: @item (use @var{x})
1837: Represents the use of the value of @var{x}. It indicates that the
1838: value in @var{x} at this point in the program is needed, even though
1839: it may not be apparent why this is so. Therefore, the compiler will
1840: not attempt to delete previous instructions whose only effect is to
1841: store a value in @var{x}. @var{x} must be a @code{reg} expression.
1842:
1843: During the delayed branch scheduling phase, @var{x} may be an insn.
1844: This indicates that @var{x} previously was located at this place in the
1845: code and its data dependencies need to be taken into account. These
1846: @code{use} insns will be deleted before the delayed branch scheduling
1847: phase exits.
1848:
1849: @findex parallel
1850: @item (parallel [@var{x0} @var{x1} @dots{}])
1851: Represents several side effects performed in parallel. The square
1852: brackets stand for a vector; the operand of @code{parallel} is a
1853: vector of expressions. @var{x0}, @var{x1} and so on are individual
1854: side effect expressions---expressions of code @code{set}, @code{call},
1855: @code{return}, @code{clobber} or @code{use}.@refill
1856:
1857: ``In parallel'' means that first all the values used in the individual
1858: side-effects are computed, and second all the actual side-effects are
1859: performed. For example,
1860:
1861: @example
1862: (parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
1863: (set (mem:SI (reg:SI 1)) (reg:SI 1))])
1864: @end example
1865:
1866: @noindent
1867: says unambiguously that the values of hard register 1 and the memory
1868: location addressed by it are interchanged. In both places where
1869: @code{(reg:SI 1)} appears as a memory address it refers to the value
1870: in register 1 @emph{before} the execution of the insn.
1871:
1872: It follows that it is @emph{incorrect} to use @code{parallel} and
1873: expect the result of one @code{set} to be available for the next one.
1874: For example, people sometimes attempt to represent a jump-if-zero
1875: instruction this way:
1876:
1877: @example
1878: (parallel [(set (cc0) (reg:SI 34))
1879: (set (pc) (if_then_else
1880: (eq (cc0) (const_int 0))
1881: (label_ref @dots{})
1882: (pc)))])
1883: @end example
1884:
1885: @noindent
1886: But this is incorrect, because it says that the jump condition depends
1887: on the condition code value @emph{before} this instruction, not on the
1888: new value that is set by this instruction.
1889:
1890: @cindex peephole optimization, RTL representation
1891: Peephole optimization, which takes place together with final assembly
1892: code output, can produce insns whose patterns consist of a @code{parallel}
1893: whose elements are the operands needed to output the resulting
1894: assembler code---often @code{reg}, @code{mem} or constant expressions.
1895: This would not be well-formed RTL at any other stage in compilation,
1896: but it is ok then because no further optimization remains to be done.
1897: However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
1898: any, must deal with such insns if you define any peephole optimizations.
1899:
1900: @findex sequence
1901: @item (sequence [@var{insns} @dots{}])
1902: Represents a sequence of insns. Each of the @var{insns} that appears
1903: in the vector is suitable for appearing in the chain of insns, so it
1904: must be an @code{insn}, @code{jump_insn}, @code{call_insn},
1905: @code{code_label}, @code{barrier} or @code{note}.
1906:
1907: A @code{sequence} RTX is never placed in an actual insn during RTL
1908: generation. It represents the sequence of insns that result from a
1909: @code{define_expand} @emph{before} those insns are passed to
1910: @code{emit_insn} to insert them in the chain of insns. When actually
1911: inserted, the individual sub-insns are separated out and the
1912: @code{sequence} is forgotten.
1913:
1914: After delay-slot scheduling is completed, an insn and all the insns that
1915: reside in its delay slots are grouped together into a @code{sequence}.
1916: The insn requiring the delay slot is the first insn in the vector;
1917: subsequent insns are to be placed in the delay slot.
1918:
1919: @code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
1920: indicate that a branch insn should be used that will conditionally annul
1921: the effect of the insns in the delay slots. In such a case,
1922: @code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
1923: the branch and should be executed only if the branch is taken; otherwise
1924: the insn should be executed only if the branch is not taken.
1925: @xref{Delay Slots}.
1926: @end table
1927:
1928: These expression codes appear in place of a side effect, as the body of
1929: an insn, though strictly speaking they do not always describe side
1930: effects as such:
1931:
1932: @table @code
1933: @findex asm_input
1934: @item (asm_input @var{s})
1935: Represents literal assembler code as described by the string @var{s}.
1936:
1937: @findex unspec
1938: @findex unspec_volatile
1939: @item (unspec [@var{operands} @dots{}] @var{index})
1.1.1.2 ! root 1940: @itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
1.1 root 1941: Represents a machine-specific operation on @var{operands}. @var{index}
1.1.1.2 ! root 1942: selects between multiple machine-specific operations.
1.1 root 1943: @code{unspec_volatile} is used for volatile operations and operations
1944: that may trap; @code{unspec} is used for other operations.
1945:
1.1.1.2 ! root 1946: These codes may appear inside a @code{pattern} of an
1.1 root 1947: insn, inside a @code{parallel}, or inside an expression.
1948:
1949: @findex addr_vec
1950: @item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
1951: Represents a table of jump addresses. The vector elements @var{lr0},
1952: etc., are @code{label_ref} expressions. The mode @var{m} specifies
1953: how much space is given to each address; normally @var{m} would be
1954: @code{Pmode}.
1955:
1956: @findex addr_diff_vec
1957: @item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}])
1958: Represents a table of jump addresses expressed as offsets from
1959: @var{base}. The vector elements @var{lr0}, etc., are @code{label_ref}
1960: expressions and so is @var{base}. The mode @var{m} specifies how much
1961: space is given to each address-difference.@refill
1962: @end table
1963:
1964: @node Incdec, Assembler, Side Effects, RTL
1965: @section Embedded Side-Effects on Addresses
1966: @cindex RTL preincrement
1967: @cindex RTL postincrement
1968: @cindex RTL predecrement
1969: @cindex RTL postdecrement
1970:
1971: Four special side-effect expression codes appear as memory addresses.
1972:
1973: @table @code
1974: @findex pre_dec
1975: @item (pre_dec:@var{m} @var{x})
1976: Represents the side effect of decrementing @var{x} by a standard
1977: amount and represents also the value that @var{x} has after being
1978: decremented. @var{x} must be a @code{reg} or @code{mem}, but most
1979: machines allow only a @code{reg}. @var{m} must be the machine mode
1980: for pointers on the machine in use. The amount @var{x} is decremented
1981: by is the length in bytes of the machine mode of the containing memory
1982: reference of which this expression serves as the address. Here is an
1983: example of its use:@refill
1984:
1985: @example
1986: (mem:DF (pre_dec:SI (reg:SI 39)))
1987: @end example
1988:
1989: @noindent
1990: This says to decrement pseudo register 39 by the length of a @code{DFmode}
1991: value and use the result to address a @code{DFmode} value.
1992:
1993: @findex pre_inc
1994: @item (pre_inc:@var{m} @var{x})
1995: Similar, but specifies incrementing @var{x} instead of decrementing it.
1996:
1997: @findex post_dec
1998: @item (post_dec:@var{m} @var{x})
1999: Represents the same side effect as @code{pre_dec} but a different
2000: value. The value represented here is the value @var{x} has @i{before}
2001: being decremented.
2002:
2003: @findex post_inc
2004: @item (post_inc:@var{m} @var{x})
2005: Similar, but specifies incrementing @var{x} instead of decrementing it.
2006: @end table
2007:
2008: These embedded side effect expressions must be used with care. Instruction
2009: patterns may not use them. Until the @samp{flow} pass of the compiler,
2010: they may occur only to represent pushes onto the stack. The @samp{flow}
2011: pass finds cases where registers are incremented or decremented in one
2012: instruction and used as an address shortly before or after; these cases are
2013: then transformed to use pre- or post-increment or -decrement.
2014:
2015: If a register used as the operand of these expressions is used in
2016: another address in an insn, the original value of the register is used.
2017: Uses of the register outside of an address are not permitted within the
2018: same insn as a use in an embedded side effect expression because such
2019: insns behave differently on different machines and hence must be treated
2020: as ambiguous and disallowed.
2021:
2022: An instruction that can be represented with an embedded side effect
2023: could also be represented using @code{parallel} containing an additional
2024: @code{set} to describe how the address register is altered. This is not
2025: done because machines that allow these operations at all typically
2026: allow them wherever a memory address is called for. Describing them as
2027: additional parallel stores would require doubling the number of entries
2028: in the machine description.
2029:
2030: @node Assembler, Insns, IncDec, RTL
2031: @section Assembler Instructions as Expressions
2032: @cindex assembler instructions in RTL
2033:
2034: @cindex @code{asm_operands}, usage
2035: The RTX code @code{asm_operands} represents a value produced by a
2036: user-specified assembler instruction. It is used to represent
2037: an @code{asm} statement with arguments. An @code{asm} statement with
2038: a single output operand, like this:
2039:
2040: @example
2041: asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
2042: @end example
2043:
2044: @noindent
2045: is represented using a single @code{asm_operands} RTX which represents
2046: the value that is stored in @code{outputvar}:
2047:
2048: @example
2049: (set @var{rtx-for-outputvar}
2050: (asm_operands "foo %1,%2,%0" "a" 0
2051: [@var{rtx-for-addition-result} @var{rtx-for-*z}]
2052: [(asm_input:@var{m1} "g")
2053: (asm_input:@var{m2} "di")]))
2054: @end example
2055:
2056: @noindent
2057: Here the operands of the @code{asm_operands} RTX are the assembler
2058: template string, the output-operand's constraint, the index-number of the
2059: output operand among the output operands specified, a vector of input
2060: operand RTX's, and a vector of input-operand modes and constraints. The
2061: mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
2062: @code{*z}.
2063:
2064: When an @code{asm} statement has multiple output values, its insn has
2065: several such @code{set} RTX's inside of a @code{parallel}. Each @code{set}
2066: contains a @code{asm_operands}; all of these share the same assembler
2067: template and vectors, but each contains the constraint for the respective
2068: output operand. They are also distinguished by the output-operand index
2069: number, which is 0, 1, @dots{} for successive output operands.
2070:
2071: @node Insns, Calls, Assembler, RTL
2072: @section Insns
2073: @cindex insns
2074:
2075: The RTL representation of the code for a function is a doubly-linked
2076: chain of objects called @dfn{insns}. Insns are expressions with
2077: special codes that are used for no other purpose. Some insns are
2078: actual instructions; others represent dispatch tables for @code{switch}
2079: statements; others represent labels to jump to or various sorts of
2080: declarative information.
2081:
2082: In addition to its own specific data, each insn must have a unique
2083: id-number that distinguishes it from all other insns in the current
2084: function (after delayed branch scheduling, copies of an insn with the
2085: same id-number may be present in multiple places in a function, but
2086: these copies will always be identical and will only appear inside a
2087: @code{sequence}), and chain pointers to the preceding and following
2088: insns. These three fields occupy the same position in every insn,
2089: independent of the expression code of the insn. They could be accessed
2090: with @code{XEXP} and @code{XINT}, but instead three special macros are
2091: always used:
2092:
2093: @table @code
2094: @findex INSN_UID
2095: @item INSN_UID (@var{i})
2096: Accesses the unique id of insn @var{i}.
2097:
2098: @findex PREV_INSN
2099: @item PREV_INSN (@var{i})
2100: Accesses the chain pointer to the insn preceding @var{i}.
2101: If @var{i} is the first insn, this is a null pointer.
2102:
2103: @findex NEXT_INSN
2104: @item NEXT_INSN (@var{i})
2105: Accesses the chain pointer to the insn following @var{i}.
2106: If @var{i} is the last insn, this is a null pointer.
2107: @end table
2108:
2109: @findex get_insns
2110: @findex get_last_insn
2111: The first insn in the chain is obtained by calling @code{get_insns}; the
2112: last insn is the result of calling @code{get_last_insn}. Within the
2113: chain delimited by these insns, the @code{NEXT_INSN} and
2114: @code{PREV_INSN} pointers must always correspond: if @var{insn} is not
2115: the first insn,
2116:
2117: @example
2118: NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
2119: @end example
2120:
2121: @noindent
2122: is always true and if @var{insn} is not the last insn,
2123:
2124: @example
2125: PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
2126: @end example
2127:
2128: @noindent
2129: is always true.
2130:
2131: After delay slot scheduling, some of the insns in the chain might be
2132: @code{sequence} expressions, which contain a vector of insns. The value
2133: of @code{NEXT_INSN} in all but the last of these insns is the next insn
2134: in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
2135: is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
2136: which it is contained. Similar rules apply for @code{PREV_INSN}.
2137:
2138: This means that the above invariants are not necessarily true for insns
2139: inside @code{sequence} expressions. Specifically, if @var{insn} is the
2140: first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
2141: is the insn containing the @code{sequence} expression, as is the value
2142: of @code{PREV_INSN (NEXT_INSN (@var{insn}))} is @var{insn} is the last
2143: insn in the @code{sequence} expression. You can use these expressions
2144: to find the containing @code{sequence} expression.@refill
2145:
2146: Every insn has one of the following six expression codes:
2147:
2148: @table @code
2149: @findex insn
2150: @item insn
2151: The expression code @code{insn} is used for instructions that do not jump
2152: and do not do function calls. @code{sequence} expressions are always
2153: contained in insns with code @code{insn} even if one of those insns
2154: should jump or do function calls.
2155:
2156: Insns with code @code{insn} have four additional fields beyond the three
2157: mandatory ones listed above. These four are described in a table below.
2158:
2159: @findex jump_insn
2160: @item jump_insn
2161: The expression code @code{jump_insn} is used for instructions that may
2162: jump (or, more generally, may contain @code{label_ref} expressions). If
2163: there is an instruction to return from the current function, it is
2164: recorded as a @code{jump_insn}.
2165:
2166: @findex JUMP_LABEL
2167: @code{jump_insn} insns have the same extra fields as @code{insn} insns,
2168: accessed in the same way and in addition contains a field
2169: @code{JUMP_LABEL} which is defined once jump optimization has completed.
2170:
2171: For simple conditional and unconditional jumps, this field contains the
2172: @code{code_label} to which this insn will (possibly conditionally)
2173: branch. In a more complex jump, @code{JUMP_LABEL} records one of the
2174: labels that the insn refers to; the only way to find the others
2175: is to scan the entire body of the insn.
2176:
2177: Return insns count as jumps, but since they do not refer to any labels,
2178: they have zero in the @code{JUMP_LABEL} field.
2179:
2180: @findex call_insn
2181: @item call_insn
2182: The expression code @code{call_insn} is used for instructions that may do
2183: function calls. It is important to distinguish these instructions because
2184: they imply that certain registers and memory locations may be altered
2185: unpredictably.
2186:
1.1.1.2 ! root 2187: A @code{call_insn} insn may be preceded by insns that contain a single
1.1 root 2188: @code{use} expression and be followed by insns the contain a single
2189: @code{clobber} expression. If so, these @code{use} and @code{clobber}
2190: expressions are treated as being part of the function call.
2191: There must not even be a @code{note} between the @code{call_insn} and
2192: the @code{use} or @code{clobber} insns for this special treatment to
2193: take place. This is somewhat of a kludge and will be removed in a later
2194: version of GNU CC.
2195:
2196: @code{call_insn} insns have the same extra fields as @code{insn} insns,
2197: accessed in the same way.
2198:
2199: @findex code_label
2200: @findex CODE_LABEL_NUMBER
2201: @item code_label
2202: A @code{code_label} insn represents a label that a jump insn can jump
2203: to. It contains two special fields of data in addition to the three
2204: standard ones. @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
2205: number}, a number that identifies this label uniquely among all the
2206: labels in the compilation (not just in the current function).
2207: Ultimately, the label is represented in the assembler output as an
2208: assembler label, usually of the form @samp{L@var{n}} where @var{n} is
2209: the label number.
2210:
2211: When a @code{code_label} appears in an RTL expression, it normally
2212: appears within a @code{label_ref} which represents the address of
2213: the label, as a number.
2214:
2215: @findex LABEL_NUSES
2216: The field @code{LABEL_NUSES} is only defined once the jump optimization
2217: phase is completed and contains the number of times this label is
2218: referenced in the current function.
2219:
2220: @findex barrier
2221: @item barrier
2222: Barriers are placed in the instruction stream when control cannot flow
2223: past them. They are placed after unconditional jump instructions to
2224: indicate that the jumps are unconditional and after calls to
2225: @code{volatile} functions, which do not return (e.g., @code{exit}).
2226: They contain no information beyond the three standard fields.
2227:
2228: @findex note
2229: @findex NOTE_LINE_NUMBER
2230: @findex NOTE_SOURCE_FILE
2231: @item note
2232: @code{note} insns are used to represent additional debugging and
2233: declarative information. They contain two nonstandard fields, an
2234: integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
2235: string accessed with @code{NOTE_SOURCE_FILE}.
2236:
2237: If @code{NOTE_LINE_NUMBER} is positive, the note represents the
2238: position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
2239: that the line came from. These notes control generation of line
2240: number data in the assembler output.
2241:
2242: Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
2243: code with one of the following values (and @code{NOTE_SOURCE_FILE}
2244: must contain a null pointer):
2245:
2246: @table @code
2247: @findex NOTE_INSN_DELETED
2248: @item NOTE_INSN_DELETED
2249: Such a note is completely ignorable. Some passes of the compiler
2250: delete insns by altering them into notes of this kind.
2251:
2252: @findex NOTE_INSN_BLOCK_BEG
2253: @findex NOTE_INSN_BLOCK_END
2254: @item NOTE_INSN_BLOCK_BEG
2255: @itemx NOTE_INSN_BLOCK_END
2256: These types of notes indicate the position of the beginning and end
2257: of a level of scoping of variable names. They control the output
2258: of debugging information.
2259:
2260: @findex NOTE_INSN_LOOP_BEG
2261: @findex NOTE_INSN_LOOP_END
2262: @item NOTE_INSN_LOOP_BEG
2263: @itemx NOTE_INSN_LOOP_END
2264: These types of notes indicate the position of the beginning and end
2265: of a @code{while} or @code{for} loop. They enable the loop optimizer
2266: to find loops quickly.
2267:
2268: @findex NOTE_INSN_LOOP_CONT
2269: @item NOTE_INSN_LOOP_CONT
2270: Appears at the place in a loop that @code{continue} statements jump to.
2271:
2272: @findex NOTE_INSN_LOOP_VTOP
2273: @item NOTE_INSN_LOOP_VTOP
2274: This note indicates the place in a loop where the exit test begins for
2275: those loops in which the exit test has been duplicated. This position
2276: becomes another virtual start of the loop when considering loop
2277: invariants.
2278:
2279: @findex NOTE_INSN_FUNCTION_END
2280: @item NOTE_INSN_FUNCTION_END
2281: Appears near the end of the function body, just before the label that
2282: @code{return} statements jump to (on machine where a single instruction
2283: does not suffice for returning). This note may be deleted by jump
2284: optimization.
2285:
2286: @findex NOTE_INSN_SETJMP
2287: @item NOTE_INSN_SETJMP
2288: Appears following each call to @code{setjmp} or a related function.
2289: @end table
2290:
2291: These codes are printed symbolically when they appear in debugging dumps.
2292: @end table
2293:
2294: @cindex @code{HImode}, in @code{insn}
2295: @cindex @code{QImode}, in @code{insn}
2296: The machine mode of an insn is normally @code{VOIDmode}, but some
2297: phases use the mode for various purposes; for example, the reload pass
2298: sets it to @code{HImode} if the insn needs reloading but not register
2299: elimination and @code{QImode} if both are required. The common
2300: subexpression elimination pass sets the mode of an insn to @code{QImode}
2301: when it is the first insn in a block that has already been processed.
2302:
2303: Here is a table of the extra fields of @code{insn}, @code{jump_insn}
2304: and @code{call_insn} insns:
2305:
2306: @table @code
2307: @findex PATTERN
2308: @item PATTERN (@var{i})
2309: An expression for the side effect performed by this insn. This must be
2310: one of the following codes: @code{set}, @code{call}, @code{use},
2311: @code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
2312: @code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
2313: @code{unspec_volatile}, or @code{parallel}. If it is a @code{parallel},
2314: each element of the @code{parallel} must be one these codes, except that
2315: @code{parallel} expressions cannot be nested and @code{addr_vec} and
2316: @code{addr_diff_vec} are not permitted inside a @code{parallel} expression.
2317:
2318: @findex INSN_CODE
2319: @item INSN_CODE (@var{i})
2320: An integer that says which pattern in the machine description matches
2321: this insn, or -1 if the matching has not yet been attempted.
2322:
2323: Such matching is never attempted and this field remains -1 on an insn
2324: whose pattern consists of a single @code{use}, @code{clobber},
2325: @code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
2326:
2327: @findex asm_noperands
2328: Matching is also never attempted on insns that result from an @code{asm}
2329: statement. These contain at least one @code{asm_operands} expression.
2330: The function @code{asm_noperands} returns a non-negative value for
2331: such insns.
2332:
2333: In the debugging output, this field is printed as a number followed by
2334: a symbolic representation that locates the pattern in the @file{md}
2335: file as some small positive or negative offset from a named pattern.
2336:
2337: @findex LOG_LINKS
2338: @item LOG_LINKS (@var{i})
2339: A list (chain of @code{insn_list} expressions) giving information about
2340: dependencies between instructions within a basic block. Neither a jump
2341: nor a label may come between the related insns.
2342:
2343: @findex REG_NOTES
2344: @item REG_NOTES (@var{i})
2345: A list (chain of @code{expr_list} and @code{insn_list} expressions)
2346: giving miscellaneous information about the insn. It is often information
2347: pertaining to the registers used in this insn.
2348: @end table
2349:
2350: The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
2351: expressions. Each of these has two operands: the first is an insn,
2352: and the second is another @code{insn_list} expression (the next one in
2353: the chain). The last @code{insn_list} in the chain has a null pointer
2354: as second operand. The significant thing about the chain is which
2355: insns appear in it (as first operands of @code{insn_list}
2356: expressions). Their order is not significant.
2357:
2358: This list is originally set up by the flow analysis pass; it is a null
2359: pointer until then. Flow only adds links for those data dependencies
2360: which can be used for instruction combination. For each insn, the flow
2361: analysis pass adds a link to insns which store into registers values
2362: that are used for the first time in this insn. The instruction
2363: scheduling pass adds extra links so that every dependence will be
2364: represented. Links represent data dependencies, antidependencies and
2365: output dependencies; the machine mode of the link distinguishes these
2366: three types: antidependencies have mode @code{REG_DEP_ANTI}, output
2367: dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have
2368: mode @code{VOIDmode}.
2369:
2370: The @code{REG_NOTES} field of an insn is a chain similar to the
2371: @code{LOG_LINKS} field but it includes @code{expr_list} expressions in
2372: addition to @code{insn_list} expressions. There are several kinds
2373: of register notes, which are distinguished by the machine mode, which
2374: in a register note is really understood as being an @code{enum reg_note}.
2375: The first operand @var{op} of the note is data whose meaning depends on
2376: the kind of note.
2377:
2378: @findex REG_NOTE_KIND
2379: @findex PUT_REG_NOTE_KIND
2380: The macro @code{REG_NOTE_KIND (@var{x})} returns the the kind of
2381: register note. Its counterpart, the macro @code{PUT_REG_NOTE_KIND
2382: (@var{x}, @var{newkind})} sets the register note type of @var{x} to be
2383: @var{newkind}.
2384:
2385: Register notes are of three classes: They may say something about an
2386: input to an insn, they may say something about an output of an insn, or
2387: they may create a linkage between two insns. There are also a set
2388: of values that are only used in @code{LOG_LINKS}.
2389:
2390: These register notes annotate inputs to an insn:
2391:
2392: @table @code
2393: @findex REG_DEAD
2394: @item REG_DEAD
2395: The value in @var{op} dies in this insn; that is to say, altering the
2396: value immediately after this insn would not affect the future behavior
2397: of the program.
2398:
2399: This does not necessarily mean that the register @var{op} has no useful
2400: value after this insn since it may also be an output of the insn. In
2401: such a case, however, a @code{REG_DEAD} note would be redundant and is
2402: usually not present until after the reload pass, but no code relies on
2403: this fact.
2404:
2405: @findex REG_INC
2406: @item REG_INC
2407: The register @var{op} is incremented (or decremented; at this level
2408: there is no distinction) by an embedded side effect inside this insn.
2409: This means it appears in a @code{post_inc}, @code{pre_inc},
2410: @code{post_dec} or @code{pre_dec} expression.
2411:
2412: @findex REG_NONNEG
2413: @item REG_NONNEG
2414: The register @var{op} is known to have a nonnegative value when this
2415: insn is reached. This is used so that decrement and branch until zero
2416: instructions, such as the m68k dbra, can be matched.
2417:
2418: The @code{REG_NONNEG} note is added to insns only if the machine
2419: description contains a pattern named
2420: @samp{decrement_and_branch_until_zero}.
2421:
2422: @findex REG_NO_CONFLICT
2423: @item REG_NO_CONFLICT
2424: This insn does not cause a conflict between @var{op} and the item
2425: being set by this insn even though it might appear that it does.
2426: In other words, if the destination register and @var{op} could
2427: otherwise be assigned the same register, this insn does not
2428: prevent that assignment.
2429:
2430: Insns with this note are usually part of a block that begins with a
2431: @code{clobber} insn specifying a multi-word pseudo register (which will
2432: be the output of the block), a group of insns that each set one word of
2433: the value and have the @code{REG_NO_CONFLICT} note attached, and a final
2434: insn that copies the output to itself with an attached @code{REG_EQUAL}
2435: note giving the expression being computed. This block is encapsulated
2436: with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and
2437: last insns, respectively.
2438:
2439: @findex REG_LABEL
2440: @item REG_LABEL
2441: This insn uses @var{op}, a @code{code_label}, but is not a
2442: @code{jump_insn}. The presence of this note allows jump optimization to
2443: be aware that @var{op} is, in fact, being used.
2444: @end table
2445:
2446: The following notes describe attributes of outputs of an insn:
2447:
2448: @table @code
2449: @findex REG_EQUIV
2450: @findex REG_EQUAL
2451: @item REG_EQUIV
2452: @itemx REG_EQUAL
2453: This note is only valid on an insn that sets only one register and
2454: indicates that that register will be equal to @var{op} at run time; the
2455: scope of this equivalence differs between the two types of notes. The
2456: value which the insn explicitly copies into the register may look
2457: different from @var{op}, but they will be equal at run time. If the
2458: output of the single @code{set} is a @code{strict_low_part} expression,
2459: the note refers to the register that is contained in @code{SUBREG_REG}
2460: of the @code{subreg} expression.
2461:
2462: For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
2463: the entire function, and could validly be replaced in all its
2464: occurrences by @var{op}. (``Validly'' here refers to the data flow of
2465: the program; simple replacement may make some insns invalid.) For
2466: example, when a constant is loaded into a register that is never
2467: assigned any other value, this kind of note is used.
2468:
2469: When a parameter is copied into a pseudo-register at entry to a function,
2470: a note of this kind records that the register is equivalent to the stack
2471: slot where the parameter was passed. Although in this case the register
2472: may be set by other insns, it is still valid to replace the register
2473: by the stack slot throughout the function.
2474:
2475: In the case of @code{REG_EQUAL}, the register that is set by this insn
2476: will be equal to @var{op} at run time at the end of this insn but not
2477: necessarily elsewhere in the function. In this case, @var{op}
2478: is typically an arithmetic expression. For example, when a sequence of
2479: insns such as a library call is used to perform an arithmetic operation,
2480: this kind of note is attached to the insn that produces or copies the
2481: final value.
2482:
2483: These two notes are used in different ways by the compiler passes.
2484: @code{REG_EQUAL} is used by passes prior to register allocation (such as
2485: common subexpression elimination and loop optimization) to tell them how
2486: to think of that value. @code{REG_EQUIV} notes are used by register
2487: allocation to indicate that there is an available substitute expression
2488: (either a constant or a @code{mem} expression for the location of a
2489: parameter on the stack) that may be used in place of a register if
2490: insufficient registers are available.
2491:
2492: Except for stack homes for parameters, which are indicated by a
2493: @code{REG_EQUIV} note and are not useful to the early optimization
2494: passes and pseudo registers that are equivalent to a memory location
2495: throughout there entire life, which is not detected until later in
2496: the compilation, all equivalences are initially indicated by an attached
2497: @code{REG_EQUAL} note. In the early stages of register allocation, a
2498: @code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
2499: @var{op} is a constant and the insn represents the only set of its
2500: destination register.
2501:
2502: Thus, compiler passes prior to register allocation need only check for
2503: @code{REG_EQUAL} notes and passes subsequent to register allocation
2504: need only check for @code{REG_EQUIV} notes.
2505:
2506: @findex REG_UNUSED
2507: @item REG_UNUSED
2508: The register @var{op} being set by this insn will not be used in a
2509: subsequent insn. This differs from a @code{REG_DEAD} note, which
2510: indicates that the value in an input will not be used subsequently.
2511: These two notes are independent; both may be present for the same
2512: register.
2513:
2514: @findex REG_WAS_0
2515: @item REG_WAS_0
2516: The single output of this insn contained zero before this insn.
2517: @var{op} is the insn that set it to zero. You can rely on this note if
2518: it is present and @var{op} has not been deleted or turned into a @code{note};
2519: its absence implies nothing.
2520: @end table
2521:
2522: These notes describe linkages between insns. They occur in pairs: one
2523: insn has one of a pair of notes that points to a second insn, which has
2524: the inverse note pointing back to the first insn.
2525:
2526: @table @code
2527: @findex REG_RETVAL
2528: @item REG_RETVAL
2529: This insn copies the value of a multi-insn sequence (for example, a
2530: library call), and @var{op} is the first insn of the sequence (for a
2531: library call, the first insn that was generated to set up the arguments
2532: for the library call).
2533:
2534: Loop optimization uses this note to treat such a sequence as a single
2535: operation for code motion purposes and flow analysis uses this note to
2536: delete such sequences whose results are dead.
2537:
2538: A @code{REG_EQUAL} note will also usually be attached to this insn to
2539: provide the expression being computed by the sequence.
2540:
2541: @findex REG_LIBCALL
2542: @item REG_LIBCALL
2543: This is the inverse of @code{REG_RETVAL}: it is placed on the first
2544: insn of a multi-insn sequence, and it points to the last one.
2545:
2546: @findex REG_CC_SETTER
2547: @findex REG_CC_USER
2548: @item REG_CC_SETTER
2549: @itemx REG_CC_USER
2550: On machines that use @code{cc0}, the insns which set and use @code{cc0}
2551: set and use @code{cc0} are adjacent. However, when branch delay slot
2552: filling is done, this may no longer be true. In this case a
2553: @code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
2554: point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
2555: be placed on the insn using @code{cc0} to point to the insn setting
2556: @code{cc0}.@refill
2557: @end table
2558:
2559: These values are only used in the @code{LOG_LINKS} field, and indicate
2560: the type of dependency that each link represents. Links which indicate
2561: a data dependence (a read after write dependence) do not use any code,
2562: they simply have mode @code{VOIDmode}, and are printed without any
2563: descriptive text.
2564:
2565: @table @code
2566: @findex REG_DEP_ANTI
2567: @item REG_DEP_ANTI
2568: This indicates an anti dependence (a write after read dependence).
2569:
2570: @findex REG_DEP_OUTPUT
2571: @item REG_DEP_OUTPUT
2572: This indicates an output dependence (a write after write dependence).
2573: @end table
2574:
2575: For convenience, the machine mode in an @code{insn_list} or
2576: @code{expr_list} is printed using these symbolic codes in debugging dumps.
2577:
2578: @findex insn_list
2579: @findex expr_list
2580: The only difference between the expression codes @code{insn_list} and
2581: @code{expr_list} is that the first operand of an @code{insn_list} is
2582: assumed to be an insn and is printed in debugging dumps as the insn's
2583: unique id; the first operand of an @code{expr_list} is printed in the
2584: ordinary way as an expression.
2585:
2586: @node Calls, Sharing, Insns, RTL
2587: @section RTL Representation of Function-Call Insns
2588: @cindex calling functions in RTL
2589: @cindex RTL function-call insns
2590: @cindex function-call insns
2591:
2592: Insns that call subroutines have the RTL expression code @code{call_insn}.
2593: These insns must satisfy special rules, and their bodies must use a special
2594: RTL expression code, @code{call}.
2595:
2596: @cindex @code{call} usage
2597: A @code{call} expression has two operands, as follows:
2598:
2599: @example
2600: (call (mem:@var{fm} @var{addr}) @var{nbytes})
2601: @end example
2602:
2603: @noindent
2604: Here @var{nbytes} is an operand that represents the number of bytes of
2605: argument data being passed to the subroutine, @var{fm} is a machine mode
2606: (which must equal as the definition of the @code{FUNCTION_MODE} macro in
2607: the machine description) and @var{addr} represents the address of the
2608: subroutine.
2609:
2610: For a subroutine that returns no value, the @code{call} expression as
2611: shown above is the entire body of the insn, except that the insn might
2612: also contain @code{use} or @code{clobber} expressions.
2613:
2614: @cindex @code{BLKmode}, and function return values
2615: For a subroutine that returns a value whose mode is not @code{BLKmode},
2616: the value is returned in a hard register. If this register's number is
2617: @var{r}, then the body of the call insn looks like this:
2618:
2619: @example
2620: (set (reg:@var{m} @var{r})
2621: (call (mem:@var{fm} @var{addr}) @var{nbytes}))
2622: @end example
2623:
2624: @noindent
2625: This RTL expression makes it clear (to the optimizer passes) that the
2626: appropriate register receives a useful value in this insn.
2627:
2628: When a subroutine returns a @code{BLKmode} value, it is handled by
2629: passing to the subroutine the address of a place to store the value.
2630: So the call insn itself does not ``return'' any value, and it has the
2631: same RTL form as a call that returns nothing.
2632:
2633: On some machines, the call instruction itself clobbers some register,
2634: for example to contain the return address. @code{call_insn} insns
2635: on these machines should have a body which is a @code{parallel}
2636: that contains both the @code{call} expression and @code{clobber}
2637: expressions that indicate which registers are destroyed. Similarly,
2638: if the call instruction requires some register other than the stack
2639: pointer that is not explicitly mentioned it its RTL, a @code{use}
2640: subexpression should mention that register.
2641:
2642: Functions that are called are assumed to modify all registers listed in
2643: the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
2644: Basics}) and, with the exception of @code{const} functions and library
2645: calls, to modify all of memory.
2646:
2647: Insns containing just @code{use} expressions directly precede the
2648: @code{call_insn} insn to indicate which registers contain inputs to the
2649: function. Similarly, if registers other than those in
2650: @code{CALL_USED_REGISTERS} are clobbered by the called function, insns
2651: containing a single @code{clobber} follow immediately after the call to
2652: indicate which registers.
2653:
2654: @node Sharing,, Calls, RTL
2655: @section Structure Sharing Assumptions
2656: @cindex sharing of RTL components
2657: @cindex RTL structure sharing assumptions
2658:
2659: The compiler assumes that certain kinds of RTL expressions are unique;
2660: there do not exist two distinct objects representing the same value.
2661: In other cases, it makes an opposite assumption: that no RTL expression
2662: object of a certain kind appears in more than one place in the
2663: containing structure.
2664:
2665: These assumptions refer to a single function; except for the RTL
2666: objects that describe global variables and external functions,
2667: and a few standard objects such as small integer constants,
2668: no RTL objects are common to two functions.
2669:
2670: @itemize @bullet
2671: @cindex @code{reg}, RTL sharing
2672: @item
2673: Each pseudo-register has only a single @code{reg} object to represent it,
2674: and therefore only a single machine mode.
2675:
2676: @cindex symbolic label
2677: @cindex @code{symbol_ref}, RTL sharing
2678: @item
2679: For any symbolic label, there is only one @code{symbol_ref} object
2680: referring to it.
2681:
2682: @cindex @code{const_int}, RTL sharing
2683: @item
2684: There is only one @code{const_int} expression with value 0, only
2685: one with value 1, and only one with value @minus{}1.
2686: Some other integer values are also stored uniquely.
2687:
2688: @cindex @code{pc}, RTL sharing
2689: @item
2690: There is only one @code{pc} expression.
2691:
2692: @cindex @code{cc0}, RTL sharing
2693: @item
2694: There is only one @code{cc0} expression.
2695:
2696: @cindex @code{const_double}, RTL sharing
2697: @item
2698: There is only one @code{const_double} expression with value 0 for
2699: each floating point mode. Likewise for values 1 and 2.
2700:
2701: @cindex @code{label_ref}, RTL sharing
2702: @cindex @code{scratch}, RTL sharing
2703: @item
2704: No @code{label_ref} or @code{scratch} appears in more than one place in
2705: the RTL structure; in other words, it is safe to do a tree-walk of all
2706: the insns in the function and assume that each time a @code{label_ref}
2707: or @code{scratch} is seen it is distinct from all others that are seen.
2708:
2709: @cindex @code{mem}, RTL sharing
2710: @item
2711: Only one @code{mem} object is normally created for each static
2712: variable or stack slot, so these objects are frequently shared in all
2713: the places they appear. However, separate but equal objects for these
2714: variables are occasionally made.
2715:
2716: @cindex @code{asm_operands}, RTL sharing
2717: @item
2718: When a single @code{asm} statement has multiple output operands, a
2719: distinct @code{asm_operands} expression is made for each output operand.
2720: However, these all share the vector which contains the sequence of input
2721: operands. This sharing is used later on to test whether two
2722: @code{asm_operands} expressions come from the same statement, so all
2723: optimizations must carefully preserve the sharing if they copy the
2724: vector at all.
2725:
2726: @item
2727: No RTL object appears in more than one place in the RTL structure
2728: except as described above. Many passes of the compiler rely on this
2729: by assuming that they can modify RTL objects in place without unwanted
2730: side-effects on other insns.
2731:
2732: @findex unshare_all_rtl
2733: @item
2734: During initial RTL generation, shared structure is freely introduced.
2735: After all the RTL for a function has been generated, all shared
2736: structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
2737: after which the above rules are guaranteed to be followed.
2738:
2739: @findex copy_rtx_if_shared
2740: @item
2741: During the combiner pass, shared structure within an insn can exist
2742: temporarily. However, the shared structure is copied before the
2743: combiner is finished with the insn. This is done by calling
2744: @code{copy_rtx_if_shared}, which is a subroutine of
2745: @code{unshare_all_rtl}.
2746: @end itemize
2747: @end ifset
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.