OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-old/] [gcc-4.2.2/] [gcc/] [doc/] [rtl.texi] - Blame information for rev 823

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 38 julius
@c Copyright (C) 1988, 1989, 1992, 1994, 1997, 1998, 1999, 2000, 2001, 2002,
2
@c 2003, 2004, 2005
3
@c Free Software Foundation, Inc.
4
@c This is part of the GCC manual.
5
@c For copying conditions, see the file gcc.texi.
6
 
7
@node RTL
8
@chapter RTL Representation
9
@cindex RTL representation
10
@cindex representation of RTL
11
@cindex Register Transfer Language (RTL)
12
 
13
Most of the work of the compiler is done on an intermediate representation
14
called register transfer language.  In this language, the instructions to be
15
output are described, pretty much one by one, in an algebraic form that
16
describes what the instruction does.
17
 
18
RTL is inspired by Lisp lists.  It has both an internal form, made up of
19
structures that point at other structures, and a textual form that is used
20
in the machine description and in printed debugging dumps.  The textual
21
form uses nested parentheses to indicate the pointers in the internal form.
22
 
23
@menu
24
* RTL Objects::       Expressions vs vectors vs strings vs integers.
25
* RTL Classes::       Categories of RTL expression objects, and their structure.
26
* Accessors::         Macros to access expression operands or vector elts.
27
* Special Accessors:: Macros to access specific annotations on RTL.
28
* Flags::             Other flags in an RTL expression.
29
* Machine Modes::     Describing the size and format of a datum.
30
* Constants::         Expressions with constant values.
31
* Regs and Memory::   Expressions representing register contents or memory.
32
* Arithmetic::        Expressions representing arithmetic on other expressions.
33
* Comparisons::       Expressions representing comparison of expressions.
34
* Bit-Fields::        Expressions representing bit-fields in memory or reg.
35
* Vector Operations:: Expressions involving vector datatypes.
36
* Conversions::       Extending, truncating, floating or fixing.
37
* RTL Declarations::  Declaring volatility, constancy, etc.
38
* Side Effects::      Expressions for storing in registers, etc.
39
* Incdec::            Embedded side-effects for autoincrement addressing.
40
* Assembler::         Representing @code{asm} with operands.
41
* Insns::             Expression types for entire insns.
42
* Calls::             RTL representation of function call insns.
43
* Sharing::           Some expressions are unique; others *must* be copied.
44
* Reading RTL::       Reading textual RTL from a file.
45
@end menu
46
 
47
@node RTL Objects
48
@section RTL Object Types
49
@cindex RTL object types
50
 
51
@cindex RTL integers
52
@cindex RTL strings
53
@cindex RTL vectors
54
@cindex RTL expression
55
@cindex RTX (See RTL)
56
RTL uses five kinds of objects: expressions, integers, wide integers,
57
strings and vectors.  Expressions are the most important ones.  An RTL
58
expression (``RTX'', for short) is a C structure, but it is usually
59
referred to with a pointer; a type that is given the typedef name
60
@code{rtx}.
61
 
62
An integer is simply an @code{int}; their written form uses decimal
63
digits.  A wide integer is an integral object whose type is
64
@code{HOST_WIDE_INT}; their written form uses decimal digits.
65
 
66
A string is a sequence of characters.  In core it is represented as a
67
@code{char *} in usual C fashion, and it is written in C syntax as well.
68
However, strings in RTL may never be null.  If you write an empty string in
69
a machine description, it is represented in core as a null pointer rather
70
than as a pointer to a null character.  In certain contexts, these null
71
pointers instead of strings are valid.  Within RTL code, strings are most
72
commonly found inside @code{symbol_ref} expressions, but they appear in
73
other contexts in the RTL expressions that make up machine descriptions.
74
 
75
In a machine description, strings are normally written with double
76
quotes, as you would in C@.  However, strings in machine descriptions may
77
extend over many lines, which is invalid C, and adjacent string
78
constants are not concatenated as they are in C@.  Any string constant
79
may be surrounded with a single set of parentheses.  Sometimes this
80
makes the machine description easier to read.
81
 
82
There is also a special syntax for strings, which can be useful when C
83
code is embedded in a machine description.  Wherever a string can
84
appear, it is also valid to write a C-style brace block.  The entire
85
brace block, including the outermost pair of braces, is considered to be
86
the string constant.  Double quote characters inside the braces are not
87
special.  Therefore, if you write string constants in the C code, you
88
need not escape each quote character with a backslash.
89
 
90
A vector contains an arbitrary number of pointers to expressions.  The
91
number of elements in the vector is explicitly present in the vector.
92
The written form of a vector consists of square brackets
93
(@samp{[@dots{}]}) surrounding the elements, in sequence and with
94
whitespace separating them.  Vectors of length zero are not created;
95
null pointers are used instead.
96
 
97
@cindex expression codes
98
@cindex codes, RTL expression
99
@findex GET_CODE
100
@findex PUT_CODE
101
Expressions are classified by @dfn{expression codes} (also called RTX
102
codes).  The expression code is a name defined in @file{rtl.def}, which is
103
also (in uppercase) a C enumeration constant.  The possible expression
104
codes and their meanings are machine-independent.  The code of an RTX can
105
be extracted with the macro @code{GET_CODE (@var{x})} and altered with
106
@code{PUT_CODE (@var{x}, @var{newcode})}.
107
 
108
The expression code determines how many operands the expression contains,
109
and what kinds of objects they are.  In RTL, unlike Lisp, you cannot tell
110
by looking at an operand what kind of object it is.  Instead, you must know
111
from its context---from the expression code of the containing expression.
112
For example, in an expression of code @code{subreg}, the first operand is
113
to be regarded as an expression and the second operand as an integer.  In
114
an expression of code @code{plus}, there are two operands, both of which
115
are to be regarded as expressions.  In a @code{symbol_ref} expression,
116
there is one operand, which is to be regarded as a string.
117
 
118
Expressions are written as parentheses containing the name of the
119
expression type, its flags and machine mode if any, and then the operands
120
of the expression (separated by spaces).
121
 
122
Expression code names in the @samp{md} file are written in lowercase,
123
but when they appear in C code they are written in uppercase.  In this
124
manual, they are shown as follows: @code{const_int}.
125
 
126
@cindex (nil)
127
@cindex nil
128
In a few contexts a null pointer is valid where an expression is normally
129
wanted.  The written form of this is @code{(nil)}.
130
 
131
@node RTL Classes
132
@section RTL Classes and Formats
133
@cindex RTL classes
134
@cindex classes of RTX codes
135
@cindex RTX codes, classes of
136
@findex GET_RTX_CLASS
137
 
138
The various expression codes are divided into several @dfn{classes},
139
which are represented by single characters.  You can determine the class
140
of an RTX code with the macro @code{GET_RTX_CLASS (@var{code})}.
141
Currently, @file{rtl.def} defines these classes:
142
 
143
@table @code
144
@item RTX_OBJ
145
An RTX code that represents an actual object, such as a register
146
(@code{REG}) or a memory location (@code{MEM}, @code{SYMBOL_REF}).
147
@code{LO_SUM}) is also included; instead, @code{SUBREG} and
148
@code{STRICT_LOW_PART} are not in this class, but in class @code{x}.
149
 
150
@item RTX_CONST_OBJ
151
An RTX code that represents a constant object.  @code{HIGH} is also
152
included in this class.
153
 
154
@item RTX_COMPARE
155
An RTX code for a non-symmetric comparison, such as @code{GEU} or
156
@code{LT}.
157
 
158
@item RTX_COMM_COMPARE
159
An RTX code for a symmetric (commutative) comparison, such as @code{EQ}
160
or @code{ORDERED}.
161
 
162
@item RTX_UNARY
163
An RTX code for a unary arithmetic operation, such as @code{NEG},
164
@code{NOT}, or @code{ABS}.  This category also includes value extension
165
(sign or zero) and conversions between integer and floating point.
166
 
167
@item RTX_COMM_ARITH
168
An RTX code for a commutative binary operation, such as @code{PLUS} or
169
@code{AND}.  @code{NE} and @code{EQ} are comparisons, so they have class
170
@code{<}.
171
 
172
@item RTX_BIN_ARITH
173
An RTX code for a non-commutative binary operation, such as @code{MINUS},
174
@code{DIV}, or @code{ASHIFTRT}.
175
 
176
@item RTX_BITFIELD_OPS
177
An RTX code for a bit-field operation.  Currently only
178
@code{ZERO_EXTRACT} and @code{SIGN_EXTRACT}.  These have three inputs
179
and are lvalues (so they can be used for insertion as well).
180
@xref{Bit-Fields}.
181
 
182
@item RTX_TERNARY
183
An RTX code for other three input operations.  Currently only
184
@code{IF_THEN_ELSE} and @code{VEC_MERGE}.
185
 
186
@item RTX_INSN
187
An RTX code for an entire instruction:  @code{INSN}, @code{JUMP_INSN}, and
188
@code{CALL_INSN}.  @xref{Insns}.
189
 
190
@item RTX_MATCH
191
An RTX code for something that matches in insns, such as
192
@code{MATCH_DUP}.  These only occur in machine descriptions.
193
 
194
@item RTX_AUTOINC
195
An RTX code for an auto-increment addressing mode, such as
196
@code{POST_INC}.
197
 
198
@item RTX_EXTRA
199
All other RTX codes.  This category includes the remaining codes used
200
only in machine descriptions (@code{DEFINE_*}, etc.).  It also includes
201
all the codes describing side effects (@code{SET}, @code{USE},
202
@code{CLOBBER}, etc.) and the non-insns that may appear on an insn
203
chain, such as @code{NOTE}, @code{BARRIER}, and @code{CODE_LABEL}.
204
@code{SUBREG} is also part of this class.
205
@end table
206
 
207
@cindex RTL format
208
For each expression code, @file{rtl.def} specifies the number of
209
contained objects and their kinds using a sequence of characters
210
called the @dfn{format} of the expression code.  For example,
211
the format of @code{subreg} is @samp{ei}.
212
 
213
@cindex RTL format characters
214
These are the most commonly used format characters:
215
 
216
@table @code
217
@item e
218
An expression (actually a pointer to an expression).
219
 
220
@item i
221
An integer.
222
 
223
@item w
224
A wide integer.
225
 
226
@item s
227
A string.
228
 
229
@item E
230
A vector of expressions.
231
@end table
232
 
233
A few other format characters are used occasionally:
234
 
235
@table @code
236
@item u
237
@samp{u} is equivalent to @samp{e} except that it is printed differently
238
in debugging dumps.  It is used for pointers to insns.
239
 
240
@item n
241
@samp{n} is equivalent to @samp{i} except that it is printed differently
242
in debugging dumps.  It is used for the line number or code number of a
243
@code{note} insn.
244
 
245
@item S
246
@samp{S} indicates a string which is optional.  In the RTL objects in
247
core, @samp{S} is equivalent to @samp{s}, but when the object is read,
248
from an @samp{md} file, the string value of this operand may be omitted.
249
An omitted string is taken to be the null string.
250
 
251
@item V
252
@samp{V} indicates a vector which is optional.  In the RTL objects in
253
core, @samp{V} is equivalent to @samp{E}, but when the object is read
254
from an @samp{md} file, the vector value of this operand may be omitted.
255
An omitted vector is effectively the same as a vector of no elements.
256
 
257
@item B
258
@samp{B} indicates a pointer to basic block structure.
259
 
260
@item 0
261
@samp{0} means a slot whose contents do not fit any normal category.
262
@samp{0} slots are not printed at all in dumps, and are often used in
263
special ways by small parts of the compiler.
264
@end table
265
 
266
There are macros to get the number of operands and the format
267
of an expression code:
268
 
269
@table @code
270
@findex GET_RTX_LENGTH
271
@item GET_RTX_LENGTH (@var{code})
272
Number of operands of an RTX of code @var{code}.
273
 
274
@findex GET_RTX_FORMAT
275
@item GET_RTX_FORMAT (@var{code})
276
The format of an RTX of code @var{code}, as a C string.
277
@end table
278
 
279
Some classes of RTX codes always have the same format.  For example, it
280
is safe to assume that all comparison operations have format @code{ee}.
281
 
282
@table @code
283
@item 1
284
All codes of this class have format @code{e}.
285
 
286
@item <
287
@itemx c
288
@itemx 2
289
All codes of these classes have format @code{ee}.
290
 
291
@item b
292
@itemx 3
293
All codes of these classes have format @code{eee}.
294
 
295
@item i
296
All codes of this class have formats that begin with @code{iuueiee}.
297
@xref{Insns}.  Note that not all RTL objects linked onto an insn chain
298
are of class @code{i}.
299
 
300
@item o
301
@itemx m
302
@itemx x
303
You can make no assumptions about the format of these codes.
304
@end table
305
 
306
@node Accessors
307
@section Access to Operands
308
@cindex accessors
309
@cindex access to operands
310
@cindex operand access
311
 
312
@findex XEXP
313
@findex XINT
314
@findex XWINT
315
@findex XSTR
316
Operands of expressions are accessed using the macros @code{XEXP},
317
@code{XINT}, @code{XWINT} and @code{XSTR}.  Each of these macros takes
318
two arguments: an expression-pointer (RTX) and an operand number
319
(counting from zero).  Thus,
320
 
321
@smallexample
322
XEXP (@var{x}, 2)
323
@end smallexample
324
 
325
@noindent
326
accesses operand 2 of expression @var{x}, as an expression.
327
 
328
@smallexample
329
XINT (@var{x}, 2)
330
@end smallexample
331
 
332
@noindent
333
accesses the same operand as an integer.  @code{XSTR}, used in the same
334
fashion, would access it as a string.
335
 
336
Any operand can be accessed as an integer, as an expression or as a string.
337
You must choose the correct method of access for the kind of value actually
338
stored in the operand.  You would do this based on the expression code of
339
the containing expression.  That is also how you would know how many
340
operands there are.
341
 
342
For example, if @var{x} is a @code{subreg} expression, you know that it has
343
two operands which can be correctly accessed as @code{XEXP (@var{x}, 0)}
344
and @code{XINT (@var{x}, 1)}.  If you did @code{XINT (@var{x}, 0)}, you
345
would get the address of the expression operand but cast as an integer;
346
that might occasionally be useful, but it would be cleaner to write
347
@code{(int) XEXP (@var{x}, 0)}.  @code{XEXP (@var{x}, 1)} would also
348
compile without error, and would return the second, integer operand cast as
349
an expression pointer, which would probably result in a crash when
350
accessed.  Nothing stops you from writing @code{XEXP (@var{x}, 28)} either,
351
but this will access memory past the end of the expression with
352
unpredictable results.
353
 
354
Access to operands which are vectors is more complicated.  You can use the
355
macro @code{XVEC} to get the vector-pointer itself, or the macros
356
@code{XVECEXP} and @code{XVECLEN} to access the elements and length of a
357
vector.
358
 
359
@table @code
360
@findex XVEC
361
@item XVEC (@var{exp}, @var{idx})
362
Access the vector-pointer which is operand number @var{idx} in @var{exp}.
363
 
364
@findex XVECLEN
365
@item XVECLEN (@var{exp}, @var{idx})
366
Access the length (number of elements) in the vector which is
367
in operand number @var{idx} in @var{exp}.  This value is an @code{int}.
368
 
369
@findex XVECEXP
370
@item XVECEXP (@var{exp}, @var{idx}, @var{eltnum})
371
Access element number @var{eltnum} in the vector which is
372
in operand number @var{idx} in @var{exp}.  This value is an RTX@.
373
 
374
It is up to you to make sure that @var{eltnum} is not negative
375
and is less than @code{XVECLEN (@var{exp}, @var{idx})}.
376
@end table
377
 
378
All the macros defined in this section expand into lvalues and therefore
379
can be used to assign the operands, lengths and vector elements as well as
380
to access them.
381
 
382
@node Special Accessors
383
@section Access to Special Operands
384
@cindex access to special operands
385
 
386
Some RTL nodes have special annotations associated with them.
387
 
388
@table @code
389
@item MEM
390
@table @code
391
@findex MEM_ALIAS_SET
392
@item MEM_ALIAS_SET (@var{x})
393
If 0, @var{x} is not in any alias set, and may alias anything.  Otherwise,
394
@var{x} can only alias @code{MEM}s in a conflicting alias set.  This value
395
is set in a language-dependent manner in the front-end, and should not be
396
altered in the back-end.  In some front-ends, these numbers may correspond
397
in some way to types, or other language-level entities, but they need not,
398
and the back-end makes no such assumptions.
399
These set numbers are tested with @code{alias_sets_conflict_p}.
400
 
401
@findex MEM_EXPR
402
@item MEM_EXPR (@var{x})
403
If this register is known to hold the value of some user-level
404
declaration, this is that tree node.  It may also be a
405
@code{COMPONENT_REF}, in which case this is some field reference,
406
and @code{TREE_OPERAND (@var{x}, 0)} contains the declaration,
407
or another @code{COMPONENT_REF}, or null if there is no compile-time
408
object associated with the reference.
409
 
410
@findex MEM_OFFSET
411
@item MEM_OFFSET (@var{x})
412
The offset from the start of @code{MEM_EXPR} as a @code{CONST_INT} rtx.
413
 
414
@findex MEM_SIZE
415
@item MEM_SIZE (@var{x})
416
The size in bytes of the memory reference as a @code{CONST_INT} rtx.
417
This is mostly relevant for @code{BLKmode} references as otherwise
418
the size is implied by the mode.
419
 
420
@findex MEM_ALIGN
421
@item MEM_ALIGN (@var{x})
422
The known alignment in bits of the memory reference.
423
@end table
424
 
425
@item REG
426
@table @code
427
@findex ORIGINAL_REGNO
428
@item ORIGINAL_REGNO (@var{x})
429
This field holds the number the register ``originally'' had; for a
430
pseudo register turned into a hard reg this will hold the old pseudo
431
register number.
432
 
433
@findex REG_EXPR
434
@item REG_EXPR (@var{x})
435
If this register is known to hold the value of some user-level
436
declaration, this is that tree node.
437
 
438
@findex REG_OFFSET
439
@item REG_OFFSET (@var{x})
440
If this register is known to hold the value of some user-level
441
declaration, this is the offset into that logical storage.
442
@end table
443
 
444
@item SYMBOL_REF
445
@table @code
446
@findex SYMBOL_REF_DECL
447
@item SYMBOL_REF_DECL (@var{x})
448
If the @code{symbol_ref} @var{x} was created for a @code{VAR_DECL} or
449
a @code{FUNCTION_DECL}, that tree is recorded here.  If this value is
450
null, then @var{x} was created by back end code generation routines,
451
and there is no associated front end symbol table entry.
452
 
453
@code{SYMBOL_REF_DECL} may also point to a tree of class @code{'c'},
454
that is, some sort of constant.  In this case, the @code{symbol_ref}
455
is an entry in the per-file constant pool; again, there is no associated
456
front end symbol table entry.
457
 
458
@findex SYMBOL_REF_CONSTANT
459
@item SYMBOL_REF_CONSTANT (@var{x})
460
If @samp{CONSTANT_POOL_ADDRESS_P (@var{x})} is true, this is the constant
461
pool entry for @var{x}.  It is null otherwise.
462
 
463
@findex SYMBOL_REF_DATA
464
@item SYMBOL_REF_DATA (@var{x})
465
A field of opaque type used to store @code{SYMBOL_REF_DECL} or
466
@code{SYMBOL_REF_CONSTANT}.
467
 
468
@findex SYMBOL_REF_FLAGS
469
@item SYMBOL_REF_FLAGS (@var{x})
470
In a @code{symbol_ref}, this is used to communicate various predicates
471
about the symbol.  Some of these are common enough to be computed by
472
common code, some are specific to the target.  The common bits are:
473
 
474
@table @code
475
@findex SYMBOL_REF_FUNCTION_P
476
@findex SYMBOL_FLAG_FUNCTION
477
@item SYMBOL_FLAG_FUNCTION
478
Set if the symbol refers to a function.
479
 
480
@findex SYMBOL_REF_LOCAL_P
481
@findex SYMBOL_FLAG_LOCAL
482
@item SYMBOL_FLAG_LOCAL
483
Set if the symbol is local to this ``module''.
484
See @code{TARGET_BINDS_LOCAL_P}.
485
 
486
@findex SYMBOL_REF_EXTERNAL_P
487
@findex SYMBOL_FLAG_EXTERNAL
488
@item SYMBOL_FLAG_EXTERNAL
489
Set if this symbol is not defined in this translation unit.
490
Note that this is not the inverse of @code{SYMBOL_FLAG_LOCAL}.
491
 
492
@findex SYMBOL_REF_SMALL_P
493
@findex SYMBOL_FLAG_SMALL
494
@item SYMBOL_FLAG_SMALL
495
Set if the symbol is located in the small data section.
496
See @code{TARGET_IN_SMALL_DATA_P}.
497
 
498
@findex SYMBOL_FLAG_TLS_SHIFT
499
@findex SYMBOL_REF_TLS_MODEL
500
@item SYMBOL_REF_TLS_MODEL (@var{x})
501
This is a multi-bit field accessor that returns the @code{tls_model}
502
to be used for a thread-local storage symbol.  It returns zero for
503
non-thread-local symbols.
504
 
505
@findex SYMBOL_REF_HAS_BLOCK_INFO_P
506
@findex SYMBOL_FLAG_HAS_BLOCK_INFO
507
@item SYMBOL_FLAG_HAS_BLOCK_INFO
508
Set if the symbol has @code{SYMBOL_REF_BLOCK} and
509
@code{SYMBOL_REF_BLOCK_OFFSET} fields.
510
 
511
@findex SYMBOL_REF_ANCHOR_P
512
@findex SYMBOL_FLAG_ANCHOR
513
@cindex @option{-fsection-anchors}
514
@item SYMBOL_FLAG_ANCHOR
515
Set if the symbol is used as a section anchor.  ``Section anchors''
516
are symbols that have a known position within an @code{object_block}
517
and that can be used to access nearby members of that block.
518
They are used to implement @option{-fsection-anchors}.
519
 
520
If this flag is set, then @code{SYMBOL_FLAG_HAS_BLOCK_INFO} will be too.
521
@end table
522
 
523
Bits beginning with @code{SYMBOL_FLAG_MACH_DEP} are available for
524
the target's use.
525
@end table
526
 
527
@findex SYMBOL_REF_BLOCK
528
@item SYMBOL_REF_BLOCK (@var{x})
529
If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the
530
@samp{object_block} structure to which the symbol belongs,
531
or @code{NULL} if it has not been assigned a block.
532
 
533
@findex SYMBOL_REF_BLOCK_OFFSET
534
@item SYMBOL_REF_BLOCK_OFFSET (@var{x})
535
If @samp{SYMBOL_REF_HAS_BLOCK_INFO_P (@var{x})}, this is the offset of @var{x}
536
from the first object in @samp{SYMBOL_REF_BLOCK (@var{x})}.  The value is
537
negative if @var{x} has not yet been assigned to a block, or it has not
538
been given an offset within that block.
539
@end table
540
 
541
@node Flags
542
@section Flags in an RTL Expression
543
@cindex flags in RTL expression
544
 
545
RTL expressions contain several flags (one-bit bit-fields)
546
that are used in certain types of expression.  Most often they
547
are accessed with the following macros, which expand into lvalues.
548
 
549
@table @code
550
@findex CONSTANT_POOL_ADDRESS_P
551
@cindex @code{symbol_ref} and @samp{/u}
552
@cindex @code{unchanging}, in @code{symbol_ref}
553
@item CONSTANT_POOL_ADDRESS_P (@var{x})
554
Nonzero in a @code{symbol_ref} if it refers to part of the current
555
function's constant pool.  For most targets these addresses are in a
556
@code{.rodata} section entirely separate from the function, but for
557
some targets the addresses are close to the beginning of the function.
558
In either case GCC assumes these addresses can be addressed directly,
559
perhaps with the help of base registers.
560
Stored in the @code{unchanging} field and printed as @samp{/u}.
561
 
562
@findex CONST_OR_PURE_CALL_P
563
@cindex @code{call_insn} and @samp{/u}
564
@cindex @code{unchanging}, in @code{call_insn}
565
@item CONST_OR_PURE_CALL_P (@var{x})
566
In a @code{call_insn}, @code{note}, or an @code{expr_list} for notes,
567
indicates that the insn represents a call to a const or pure function.
568
Stored in the @code{unchanging} field and printed as @samp{/u}.
569
 
570
@findex INSN_ANNULLED_BRANCH_P
571
@cindex @code{jump_insn} and @samp{/u}
572
@cindex @code{call_insn} and @samp{/u}
573
@cindex @code{insn} and @samp{/u}
574
@cindex @code{unchanging}, in @code{jump_insn}, @code{call_insn} and @code{insn}
575
@item INSN_ANNULLED_BRANCH_P (@var{x})
576
In a @code{jump_insn}, @code{call_insn}, or @code{insn} indicates
577
that the branch is an annulling one.  See the discussion under
578
@code{sequence} below.  Stored in the @code{unchanging} field and
579
printed as @samp{/u}.
580
 
581
@findex INSN_DELETED_P
582
@cindex @code{insn} and @samp{/v}
583
@cindex @code{call_insn} and @samp{/v}
584
@cindex @code{jump_insn} and @samp{/v}
585
@cindex @code{code_label} and @samp{/v}
586
@cindex @code{barrier} and @samp{/v}
587
@cindex @code{note} and @samp{/v}
588
@cindex @code{volatil}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label}, @code{barrier}, and @code{note}
589
@item INSN_DELETED_P (@var{x})
590
In an @code{insn}, @code{call_insn}, @code{jump_insn}, @code{code_label},
591
@code{barrier}, or @code{note},
592
nonzero if the insn has been deleted.  Stored in the
593
@code{volatil} field and printed as @samp{/v}.
594
 
595
@findex INSN_FROM_TARGET_P
596
@cindex @code{insn} and @samp{/s}
597
@cindex @code{jump_insn} and @samp{/s}
598
@cindex @code{call_insn} and @samp{/s}
599
@cindex @code{in_struct}, in @code{insn} and @code{jump_insn} and @code{call_insn}
600
@item INSN_FROM_TARGET_P (@var{x})
601
In an @code{insn} or @code{jump_insn} or @code{call_insn} in a delay
602
slot of a branch, indicates that the insn
603
is from the target of the branch.  If the branch insn has
604
@code{INSN_ANNULLED_BRANCH_P} set, this insn will only be executed if
605
the branch is taken.  For annulled branches with
606
@code{INSN_FROM_TARGET_P} clear, the insn will be executed only if the
607
branch is not taken.  When @code{INSN_ANNULLED_BRANCH_P} is not set,
608
this insn will always be executed.  Stored in the @code{in_struct}
609
field and printed as @samp{/s}.
610
 
611
@findex LABEL_PRESERVE_P
612
@cindex @code{code_label} and @samp{/i}
613
@cindex @code{note} and @samp{/i}
614
@cindex @code{in_struct}, in @code{code_label} and @code{note}
615
@item LABEL_PRESERVE_P (@var{x})
616
In a @code{code_label} or @code{note}, indicates that the label is referenced by
617
code or data not visible to the RTL of a given function.
618
Labels referenced by a non-local goto will have this bit set.  Stored
619
in the @code{in_struct} field and printed as @samp{/s}.
620
 
621
@findex LABEL_REF_NONLOCAL_P
622
@cindex @code{label_ref} and @samp{/v}
623
@cindex @code{reg_label} and @samp{/v}
624
@cindex @code{volatil}, in @code{label_ref} and @code{reg_label}
625
@item LABEL_REF_NONLOCAL_P (@var{x})
626
In @code{label_ref} and @code{reg_label} expressions, nonzero if this is
627
a reference to a non-local label.
628
Stored in the @code{volatil} field and printed as @samp{/v}.
629
 
630
@findex MEM_IN_STRUCT_P
631
@cindex @code{mem} and @samp{/s}
632
@cindex @code{in_struct}, in @code{mem}
633
@item MEM_IN_STRUCT_P (@var{x})
634
In @code{mem} expressions, nonzero for reference to an entire structure,
635
union or array, or to a component of one.  Zero for references to a
636
scalar variable or through a pointer to a scalar.  If both this flag and
637
@code{MEM_SCALAR_P} are clear, then we don't know whether this @code{mem}
638
is in a structure or not.  Both flags should never be simultaneously set.
639
Stored in the @code{in_struct} field and printed as @samp{/s}.
640
 
641
@findex MEM_KEEP_ALIAS_SET_P
642
@cindex @code{mem} and @samp{/j}
643
@cindex @code{jump}, in @code{mem}
644
@item MEM_KEEP_ALIAS_SET_P (@var{x})
645
In @code{mem} expressions, 1 if we should keep the alias set for this
646
mem unchanged when we access a component.  Set to 1, for example, when we
647
are already in a non-addressable component of an aggregate.
648
Stored in the @code{jump} field and printed as @samp{/j}.
649
 
650
@findex MEM_SCALAR_P
651
@cindex @code{mem} and @samp{/f}
652
@cindex @code{frame_related}, in @code{mem}
653
@item MEM_SCALAR_P (@var{x})
654
In @code{mem} expressions, nonzero for reference to a scalar known not
655
to be a member of a structure, union, or array.  Zero for such
656
references and for indirections through pointers, even pointers pointing
657
to scalar types.  If both this flag and @code{MEM_IN_STRUCT_P} are clear,
658
then we don't know whether this @code{mem} is in a structure or not.
659
Both flags should never be simultaneously set.
660
Stored in the @code{frame_related} field and printed as @samp{/f}.
661
 
662
@findex MEM_VOLATILE_P
663
@cindex @code{mem} and @samp{/v}
664
@cindex @code{asm_input} and @samp{/v}
665
@cindex @code{asm_operands} and @samp{/v}
666
@cindex @code{volatil}, in @code{mem}, @code{asm_operands}, and @code{asm_input}
667
@item MEM_VOLATILE_P (@var{x})
668
In @code{mem}, @code{asm_operands}, and @code{asm_input} expressions,
669
nonzero for volatile memory references.
670
Stored in the @code{volatil} field and printed as @samp{/v}.
671
 
672
@findex MEM_NOTRAP_P
673
@cindex @code{mem} and @samp{/c}
674
@cindex @code{call}, in @code{mem}
675
@item MEM_NOTRAP_P (@var{x})
676
In @code{mem}, nonzero for memory references that will not trap.
677
Stored in the @code{call} field and printed as @samp{/c}.
678
 
679
@findex REG_FUNCTION_VALUE_P
680
@cindex @code{reg} and @samp{/i}
681
@cindex @code{integrated}, in @code{reg}
682
@item REG_FUNCTION_VALUE_P (@var{x})
683
Nonzero in a @code{reg} if it is the place in which this function's
684
value is going to be returned.  (This happens only in a hard
685
register.)  Stored in the @code{integrated} field and printed as
686
@samp{/i}.
687
 
688
@findex REG_POINTER
689
@cindex @code{reg} and @samp{/f}
690
@cindex @code{frame_related}, in @code{reg}
691
@item REG_POINTER (@var{x})
692
Nonzero in a @code{reg} if the register holds a pointer.  Stored in the
693
@code{frame_related} field and printed as @samp{/f}.
694
 
695
@findex REG_USERVAR_P
696
@cindex @code{reg} and @samp{/v}
697
@cindex @code{volatil}, in @code{reg}
698
@item REG_USERVAR_P (@var{x})
699
In a @code{reg}, nonzero if it corresponds to a variable present in
700
the user's source code.  Zero for temporaries generated internally by
701
the compiler.  Stored in the @code{volatil} field and printed as
702
@samp{/v}.
703
 
704
The same hard register may be used also for collecting the values of
705
functions called by this one, but @code{REG_FUNCTION_VALUE_P} is zero
706
in this kind of use.
707
 
708
@findex RTX_FRAME_RELATED_P
709
@cindex @code{insn} and @samp{/f}
710
@cindex @code{call_insn} and @samp{/f}
711
@cindex @code{jump_insn} and @samp{/f}
712
@cindex @code{barrier} and @samp{/f}
713
@cindex @code{set} and @samp{/f}
714
@cindex @code{frame_related}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, and @code{set}
715
@item RTX_FRAME_RELATED_P (@var{x})
716
Nonzero in an @code{insn}, @code{call_insn}, @code{jump_insn},
717
@code{barrier}, or @code{set} which is part of a function prologue
718
and sets the stack pointer, sets the frame pointer, or saves a register.
719
This flag should also be set on an instruction that sets up a temporary
720
register to use in place of the frame pointer.
721
Stored in the @code{frame_related} field and printed as @samp{/f}.
722
 
723
In particular, on RISC targets where there are limits on the sizes of
724
immediate constants, it is sometimes impossible to reach the register
725
save area directly from the stack pointer.  In that case, a temporary
726
register is used that is near enough to the register save area, and the
727
Canonical Frame Address, i.e., DWARF2's logical frame pointer, register
728
must (temporarily) be changed to be this temporary register.  So, the
729
instruction that sets this temporary register must be marked as
730
@code{RTX_FRAME_RELATED_P}.
731
 
732
If the marked instruction is overly complex (defined in terms of what
733
@code{dwarf2out_frame_debug_expr} can handle), you will also have to
734
create a @code{REG_FRAME_RELATED_EXPR} note and attach it to the
735
instruction.  This note should contain a simple expression of the
736
computation performed by this instruction, i.e., one that
737
@code{dwarf2out_frame_debug_expr} can handle.
738
 
739
This flag is required for exception handling support on targets with RTL
740
prologues.
741
 
742
@cindex @code{insn} and @samp{/i}
743
@cindex @code{call_insn} and @samp{/i}
744
@cindex @code{jump_insn} and @samp{/i}
745
@cindex @code{barrier} and @samp{/i}
746
@cindex @code{code_label} and @samp{/i}
747
@cindex @code{insn_list} and @samp{/i}
748
@cindex @code{const} and @samp{/i}
749
@cindex @code{note} and @samp{/i}
750
@cindex @code{integrated}, in @code{insn}, @code{call_insn}, @code{jump_insn}, @code{barrier}, @code{code_label}, @code{insn_list}, @code{const}, and @code{note}
751
@code{code_label}, @code{insn_list}, @code{const}, or @code{note} if it
752
resulted from an in-line function call.
753
Stored in the @code{integrated} field and printed as @samp{/i}.
754
 
755
@findex MEM_READONLY_P
756
@cindex @code{mem} and @samp{/u}
757
@cindex @code{unchanging}, in @code{mem}
758
@item MEM_READONLY_P (@var{x})
759
Nonzero in a @code{mem}, if the memory is statically allocated and read-only.
760
 
761
Read-only in this context means never modified during the lifetime of the
762
program, not necessarily in ROM or in write-disabled pages.  A common
763
example of the later is a shared library's global offset table.  This
764
table is initialized by the runtime loader, so the memory is technically
765
writable, but after control is transfered from the runtime loader to the
766
application, this memory will never be subsequently modified.
767
 
768
Stored in the @code{unchanging} field and printed as @samp{/u}.
769
 
770
@findex SCHED_GROUP_P
771
@cindex @code{insn} and @samp{/s}
772
@cindex @code{call_insn} and @samp{/s}
773
@cindex @code{jump_insn} and @samp{/s}
774
@cindex @code{in_struct}, in @code{insn}, @code{jump_insn} and @code{call_insn}
775
@item SCHED_GROUP_P (@var{x})
776
During instruction scheduling, in an @code{insn}, @code{call_insn} or
777
@code{jump_insn}, indicates that the
778
previous insn must be scheduled together with this insn.  This is used to
779
ensure that certain groups of instructions will not be split up by the
780
instruction scheduling pass, for example, @code{use} insns before
781
a @code{call_insn} may not be separated from the @code{call_insn}.
782
Stored in the @code{in_struct} field and printed as @samp{/s}.
783
 
784
@findex SET_IS_RETURN_P
785
@cindex @code{insn} and @samp{/j}
786
@cindex @code{jump}, in @code{insn}
787
@item SET_IS_RETURN_P (@var{x})
788
For a @code{set}, nonzero if it is for a return.
789
Stored in the @code{jump} field and printed as @samp{/j}.
790
 
791
@findex SIBLING_CALL_P
792
@cindex @code{call_insn} and @samp{/j}
793
@cindex @code{jump}, in @code{call_insn}
794
@item SIBLING_CALL_P (@var{x})
795
For a @code{call_insn}, nonzero if the insn is a sibling call.
796
Stored in the @code{jump} field and printed as @samp{/j}.
797
 
798
@findex STRING_POOL_ADDRESS_P
799
@cindex @code{symbol_ref} and @samp{/f}
800
@cindex @code{frame_related}, in @code{symbol_ref}
801
@item STRING_POOL_ADDRESS_P (@var{x})
802
For a @code{symbol_ref} expression, nonzero if it addresses this function's
803
string constant pool.
804
Stored in the @code{frame_related} field and printed as @samp{/f}.
805
 
806
@findex SUBREG_PROMOTED_UNSIGNED_P
807
@cindex @code{subreg} and @samp{/u} and @samp{/v}
808
@cindex @code{unchanging}, in @code{subreg}
809
@cindex @code{volatil}, in @code{subreg}
810
@item SUBREG_PROMOTED_UNSIGNED_P (@var{x})
811
Returns a value greater then zero for a @code{subreg} that has
812
@code{SUBREG_PROMOTED_VAR_P} nonzero if the object being referenced is kept
813
zero-extended, zero if it is kept sign-extended, and less then zero if it is
814
extended some other way via the @code{ptr_extend} instruction.
815
Stored in the @code{unchanging}
816
field and @code{volatil} field, printed as @samp{/u} and @samp{/v}.
817
This macro may only be used to get the value it may not be used to change
818
the value.  Use @code{SUBREG_PROMOTED_UNSIGNED_SET} to change the value.
819
 
820
@findex SUBREG_PROMOTED_UNSIGNED_SET
821
@cindex @code{subreg} and @samp{/u}
822
@cindex @code{unchanging}, in @code{subreg}
823
@cindex @code{volatil}, in @code{subreg}
824
@item SUBREG_PROMOTED_UNSIGNED_SET (@var{x})
825
Set the @code{unchanging} and @code{volatil} fields in a @code{subreg}
826
to reflect zero, sign, or other extension.  If @code{volatil} is
827
zero, then @code{unchanging} as nonzero means zero extension and as
828
zero means sign extension.  If @code{volatil} is nonzero then some
829
other type of extension was done via the @code{ptr_extend} instruction.
830
 
831
@findex SUBREG_PROMOTED_VAR_P
832
@cindex @code{subreg} and @samp{/s}
833
@cindex @code{in_struct}, in @code{subreg}
834
@item SUBREG_PROMOTED_VAR_P (@var{x})
835
Nonzero in a @code{subreg} if it was made when accessing an object that
836
was promoted to a wider mode in accord with the @code{PROMOTED_MODE} machine
837
description macro (@pxref{Storage Layout}).  In this case, the mode of
838
the @code{subreg} is the declared mode of the object and the mode of
839
@code{SUBREG_REG} is the mode of the register that holds the object.
840
Promoted variables are always either sign- or zero-extended to the wider
841
mode on every assignment.  Stored in the @code{in_struct} field and
842
printed as @samp{/s}.
843
 
844
@findex SYMBOL_REF_USED
845
@cindex @code{used}, in @code{symbol_ref}
846
@item SYMBOL_REF_USED (@var{x})
847
In a @code{symbol_ref}, indicates that @var{x} has been used.  This is
848
normally only used to ensure that @var{x} is only declared external
849
once.  Stored in the @code{used} field.
850
 
851
@findex SYMBOL_REF_WEAK
852
@cindex @code{symbol_ref} and @samp{/i}
853
@cindex @code{integrated}, in @code{symbol_ref}
854
@item SYMBOL_REF_WEAK (@var{x})
855
In a @code{symbol_ref}, indicates that @var{x} has been declared weak.
856
Stored in the @code{integrated} field and printed as @samp{/i}.
857
 
858
@findex SYMBOL_REF_FLAG
859
@cindex @code{symbol_ref} and @samp{/v}
860
@cindex @code{volatil}, in @code{symbol_ref}
861
@item SYMBOL_REF_FLAG (@var{x})
862
In a @code{symbol_ref}, this is used as a flag for machine-specific purposes.
863
Stored in the @code{volatil} field and printed as @samp{/v}.
864
 
865
Most uses of @code{SYMBOL_REF_FLAG} are historic and may be subsumed
866
by @code{SYMBOL_REF_FLAGS}.  Certainly use of @code{SYMBOL_REF_FLAGS}
867
is mandatory if the target requires more than one bit of storage.
868
@end table
869
 
870
These are the fields to which the above macros refer:
871
 
872
@table @code
873
@findex call
874
@cindex @samp{/c} in RTL dump
875
@item call
876
In a @code{mem}, 1 means that the memory reference will not trap.
877
 
878
In an RTL dump, this flag is represented as @samp{/c}.
879
 
880
@findex frame_related
881
@cindex @samp{/f} in RTL dump
882
@item frame_related
883
In an @code{insn} or @code{set} expression, 1 means that it is part of
884
a function prologue and sets the stack pointer, sets the frame pointer,
885
saves a register, or sets up a temporary register to use in place of the
886
frame pointer.
887
 
888
In @code{reg} expressions, 1 means that the register holds a pointer.
889
 
890
In @code{symbol_ref} expressions, 1 means that the reference addresses
891
this function's string constant pool.
892
 
893
In @code{mem} expressions, 1 means that the reference is to a scalar.
894
 
895
In an RTL dump, this flag is represented as @samp{/f}.
896
 
897
@findex in_struct
898
@cindex @samp{/s} in RTL dump
899
@item in_struct
900
In @code{mem} expressions, it is 1 if the memory datum referred to is
901
all or part of a structure or array; 0 if it is (or might be) a scalar
902
variable.  A reference through a C pointer has 0 because the pointer
903
might point to a scalar variable.  This information allows the compiler
904
to determine something about possible cases of aliasing.
905
 
906
In @code{reg} expressions, it is 1 if the register has its entire life
907
contained within the test expression of some loop.
908
 
909
In @code{subreg} expressions, 1 means that the @code{subreg} is accessing
910
an object that has had its mode promoted from a wider mode.
911
 
912
In @code{label_ref} expressions, 1 means that the referenced label is
913
outside the innermost loop containing the insn in which the @code{label_ref}
914
was found.
915
 
916
In @code{code_label} expressions, it is 1 if the label may never be deleted.
917
This is used for labels which are the target of non-local gotos.  Such a
918
label that would have been deleted is replaced with a @code{note} of type
919
@code{NOTE_INSN_DELETED_LABEL}.
920
 
921
In an @code{insn} during dead-code elimination, 1 means that the insn is
922
dead code.
923
 
924
In an @code{insn} or @code{jump_insn} during reorg for an insn in the
925
delay slot of a branch,
926
1 means that this insn is from the target of the branch.
927
 
928
In an @code{insn} during instruction scheduling, 1 means that this insn
929
must be scheduled as part of a group together with the previous insn.
930
 
931
In an RTL dump, this flag is represented as @samp{/s}.
932
 
933
@findex integrated
934
@cindex @samp{/i} in RTL dump
935
@item integrated
936
In an @code{insn}, @code{insn_list}, or @code{const}, 1 means the RTL was
937
produced by procedure integration.
938
 
939
In @code{reg} expressions, 1 means the register contains
940
the value to be returned by the current function.  On
941
machines that pass parameters in registers, the same register number
942
may be used for parameters as well, but this flag is not set on such
943
uses.
944
 
945
In @code{symbol_ref} expressions, 1 means the referenced symbol is weak.
946
 
947
In an RTL dump, this flag is represented as @samp{/i}.
948
 
949
@findex jump
950
@cindex @samp{/j} in RTL dump
951
@item jump
952
In a @code{mem} expression, 1 means we should keep the alias set for this
953
mem unchanged when we access a component.
954
 
955
In a @code{set}, 1 means it is for a return.
956
 
957
In a @code{call_insn}, 1 means it is a sibling call.
958
 
959
In an RTL dump, this flag is represented as @samp{/j}.
960
 
961
@findex unchanging
962
@cindex @samp{/u} in RTL dump
963
@item unchanging
964
In @code{reg} and @code{mem} expressions, 1 means
965
that the value of the expression never changes.
966
 
967
In @code{subreg} expressions, it is 1 if the @code{subreg} references an
968
unsigned object whose mode has been promoted to a wider mode.
969
 
970
In an @code{insn} or @code{jump_insn} in the delay slot of a branch
971
instruction, 1 means an annulling branch should be used.
972
 
973
In a @code{symbol_ref} expression, 1 means that this symbol addresses
974
something in the per-function constant pool.
975
 
976
In a @code{call_insn}, @code{note}, or an @code{expr_list} of notes,
977
1 means that this instruction is a call to a const or pure function.
978
 
979
In an RTL dump, this flag is represented as @samp{/u}.
980
 
981
@findex used
982
@item used
983
This flag is used directly (without an access macro) at the end of RTL
984
generation for a function, to count the number of times an expression
985
appears in insns.  Expressions that appear more than once are copied,
986
according to the rules for shared structure (@pxref{Sharing}).
987
 
988
For a @code{reg}, it is used directly (without an access macro) by the
989
leaf register renumbering code to ensure that each register is only
990
renumbered once.
991
 
992
In a @code{symbol_ref}, it indicates that an external declaration for
993
the symbol has already been written.
994
 
995
@findex volatil
996
@cindex @samp{/v} in RTL dump
997
@item volatil
998
@cindex volatile memory references
999
In a @code{mem}, @code{asm_operands}, or @code{asm_input}
1000
expression, it is 1 if the memory
1001
reference is volatile.  Volatile memory references may not be deleted,
1002
reordered or combined.
1003
 
1004
In a @code{symbol_ref} expression, it is used for machine-specific
1005
purposes.
1006
 
1007
In a @code{reg} expression, it is 1 if the value is a user-level variable.
1008
 
1009
 
1010
In an @code{insn}, 1 means the insn has been deleted.
1011
 
1012
In @code{label_ref} and @code{reg_label} expressions, 1 means a reference
1013
to a non-local label.
1014
 
1015
In an RTL dump, this flag is represented as @samp{/v}.
1016
@end table
1017
 
1018
@node Machine Modes
1019
@section Machine Modes
1020
@cindex machine modes
1021
 
1022
@findex enum machine_mode
1023
A machine mode describes a size of data object and the representation used
1024
for it.  In the C code, machine modes are represented by an enumeration
1025
type, @code{enum machine_mode}, defined in @file{machmode.def}.  Each RTL
1026
expression has room for a machine mode and so do certain kinds of tree
1027
expressions (declarations and types, to be precise).
1028
 
1029
In debugging dumps and machine descriptions, the machine mode of an RTL
1030
expression is written after the expression code with a colon to separate
1031
them.  The letters @samp{mode} which appear at the end of each machine mode
1032
name are omitted.  For example, @code{(reg:SI 38)} is a @code{reg}
1033
expression with machine mode @code{SImode}.  If the mode is
1034
@code{VOIDmode}, it is not written at all.
1035
 
1036
Here is a table of machine modes.  The term ``byte'' below refers to an
1037
object of @code{BITS_PER_UNIT} bits (@pxref{Storage Layout}).
1038
 
1039
@table @code
1040
@findex BImode
1041
@item BImode
1042
``Bit'' mode represents a single bit, for predicate registers.
1043
 
1044
@findex QImode
1045
@item QImode
1046
``Quarter-Integer'' mode represents a single byte treated as an integer.
1047
 
1048
@findex HImode
1049
@item HImode
1050
``Half-Integer'' mode represents a two-byte integer.
1051
 
1052
@findex PSImode
1053
@item PSImode
1054
``Partial Single Integer'' mode represents an integer which occupies
1055
four bytes but which doesn't really use all four.  On some machines,
1056
this is the right mode to use for pointers.
1057
 
1058
@findex SImode
1059
@item SImode
1060
``Single Integer'' mode represents a four-byte integer.
1061
 
1062
@findex PDImode
1063
@item PDImode
1064
``Partial Double Integer'' mode represents an integer which occupies
1065
eight bytes but which doesn't really use all eight.  On some machines,
1066
this is the right mode to use for certain pointers.
1067
 
1068
@findex DImode
1069
@item DImode
1070
``Double Integer'' mode represents an eight-byte integer.
1071
 
1072
@findex TImode
1073
@item TImode
1074
``Tetra Integer'' (?) mode represents a sixteen-byte integer.
1075
 
1076
@findex OImode
1077
@item OImode
1078
``Octa Integer'' (?) mode represents a thirty-two-byte integer.
1079
 
1080
@findex QFmode
1081
@item QFmode
1082
``Quarter-Floating'' mode represents a quarter-precision (single byte)
1083
floating point number.
1084
 
1085
@findex HFmode
1086
@item HFmode
1087
``Half-Floating'' mode represents a half-precision (two byte) floating
1088
point number.
1089
 
1090
@findex TQFmode
1091
@item TQFmode
1092
``Three-Quarter-Floating'' (?) mode represents a three-quarter-precision
1093
(three byte) floating point number.
1094
 
1095
@findex SFmode
1096
@item SFmode
1097
``Single Floating'' mode represents a four byte floating point number.
1098
In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1099
this is a single-precision IEEE floating point number; it can also be
1100
used for double-precision (on processors with 16-bit bytes) and
1101
single-precision VAX and IBM types.
1102
 
1103
@findex DFmode
1104
@item DFmode
1105
``Double Floating'' mode represents an eight byte floating point number.
1106
In the common case, of a processor with IEEE arithmetic and 8-bit bytes,
1107
this is a double-precision IEEE floating point number.
1108
 
1109
@findex XFmode
1110
@item XFmode
1111
``Extended Floating'' mode represents an IEEE extended floating point
1112
number.  This mode only has 80 meaningful bits (ten bytes).  Some
1113
processors require such numbers to be padded to twelve bytes, others
1114
to sixteen; this mode is used for either.
1115
 
1116
@findex SDmode
1117
@item SDmode
1118
``Single Decimal Floating'' mode represents a four byte decimal
1119
floating point number (as distinct from conventional binary floating
1120
point).
1121
 
1122
@findex DDmode
1123
@item DDmode
1124
``Double Decimal Floating'' mode represents an eight byte decimal
1125
floating point number.
1126
 
1127
@findex TDmode
1128
@item TDmode
1129
``Tetra Decimal Floating'' mode represents a sixteen byte decimal
1130
floating point number all 128 of whose bits are meaningful.
1131
 
1132
@findex TFmode
1133
@item TFmode
1134
``Tetra Floating'' mode represents a sixteen byte floating point number
1135
all 128 of whose bits are meaningful.  One common use is the
1136
IEEE quad-precision format.
1137
 
1138
@findex CCmode
1139
@item CCmode
1140
``Condition Code'' mode represents the value of a condition code, which
1141
is a machine-specific set of bits used to represent the result of a
1142
comparison operation.  Other machine-specific modes may also be used for
1143
the condition code.  These modes are not used on machines that use
1144
@code{cc0} (see @pxref{Condition Code}).
1145
 
1146
@findex BLKmode
1147
@item BLKmode
1148
``Block'' mode represents values that are aggregates to which none of
1149
the other modes apply.  In RTL, only memory references can have this mode,
1150
and only if they appear in string-move or vector instructions.  On machines
1151
which have no such instructions, @code{BLKmode} will not appear in RTL@.
1152
 
1153
@findex VOIDmode
1154
@item VOIDmode
1155
Void mode means the absence of a mode or an unspecified mode.
1156
For example, RTL expressions of code @code{const_int} have mode
1157
@code{VOIDmode} because they can be taken to have whatever mode the context
1158
requires.  In debugging dumps of RTL, @code{VOIDmode} is expressed by
1159
the absence of any mode.
1160
 
1161
@findex QCmode
1162
@findex HCmode
1163
@findex SCmode
1164
@findex DCmode
1165
@findex XCmode
1166
@findex TCmode
1167
@item QCmode, HCmode, SCmode, DCmode, XCmode, TCmode
1168
These modes stand for a complex number represented as a pair of floating
1169
point values.  The floating point values are in @code{QFmode},
1170
@code{HFmode}, @code{SFmode}, @code{DFmode}, @code{XFmode}, and
1171
@code{TFmode}, respectively.
1172
 
1173
@findex CQImode
1174
@findex CHImode
1175
@findex CSImode
1176
@findex CDImode
1177
@findex CTImode
1178
@findex COImode
1179
@item CQImode, CHImode, CSImode, CDImode, CTImode, COImode
1180
These modes stand for a complex number represented as a pair of integer
1181
values.  The integer values are in @code{QImode}, @code{HImode},
1182
@code{SImode}, @code{DImode}, @code{TImode}, and @code{OImode},
1183
respectively.
1184
@end table
1185
 
1186
The machine description defines @code{Pmode} as a C macro which expands
1187
into the machine mode used for addresses.  Normally this is the mode
1188
whose size is @code{BITS_PER_WORD}, @code{SImode} on 32-bit machines.
1189
 
1190
The only modes which a machine description @i{must} support are
1191
@code{QImode}, and the modes corresponding to @code{BITS_PER_WORD},
1192
@code{FLOAT_TYPE_SIZE} and @code{DOUBLE_TYPE_SIZE}.
1193
The compiler will attempt to use @code{DImode} for 8-byte structures and
1194
unions, but this can be prevented by overriding the definition of
1195
@code{MAX_FIXED_MODE_SIZE}.  Alternatively, you can have the compiler
1196
use @code{TImode} for 16-byte structures and unions.  Likewise, you can
1197
arrange for the C type @code{short int} to avoid using @code{HImode}.
1198
 
1199
@cindex mode classes
1200
Very few explicit references to machine modes remain in the compiler and
1201
these few references will soon be removed.  Instead, the machine modes
1202
are divided into mode classes.  These are represented by the enumeration
1203
type @code{enum mode_class} defined in @file{machmode.h}.  The possible
1204
mode classes are:
1205
 
1206
@table @code
1207
@findex MODE_INT
1208
@item MODE_INT
1209
Integer modes.  By default these are @code{BImode}, @code{QImode},
1210
@code{HImode}, @code{SImode}, @code{DImode}, @code{TImode}, and
1211
@code{OImode}.
1212
 
1213
@findex MODE_PARTIAL_INT
1214
@item MODE_PARTIAL_INT
1215
The ``partial integer'' modes, @code{PQImode}, @code{PHImode},
1216
@code{PSImode} and @code{PDImode}.
1217
 
1218
@findex MODE_FLOAT
1219
@item MODE_FLOAT
1220
Floating point modes.  By default these are @code{QFmode},
1221
@code{HFmode}, @code{TQFmode}, @code{SFmode}, @code{DFmode},
1222
@code{XFmode} and @code{TFmode}.
1223
 
1224
@findex MODE_DECIMAL_FLOAT
1225
@item MODE_DECIMAL_FLOAT
1226
Decimal floating point modes.  By default these are @code{SDmode},
1227
@code{DDmode} and @code{TDmode}.
1228
 
1229
@findex MODE_COMPLEX_INT
1230
@item MODE_COMPLEX_INT
1231
Complex integer modes.  (These are not currently implemented).
1232
 
1233
@findex MODE_COMPLEX_FLOAT
1234
@item MODE_COMPLEX_FLOAT
1235
Complex floating point modes.  By default these are @code{QCmode},
1236
@code{HCmode}, @code{SCmode}, @code{DCmode}, @code{XCmode}, and
1237
@code{TCmode}.
1238
 
1239
@findex MODE_FUNCTION
1240
@item MODE_FUNCTION
1241
Algol or Pascal function variables including a static chain.
1242
(These are not currently implemented).
1243
 
1244
@findex MODE_CC
1245
@item MODE_CC
1246
Modes representing condition code values.  These are @code{CCmode} plus
1247
any @code{CC_MODE} modes listed in the @file{@var{machine}-modes.def}.
1248
@xref{Jump Patterns},
1249
also see @ref{Condition Code}.
1250
 
1251
@findex MODE_RANDOM
1252
@item MODE_RANDOM
1253
This is a catchall mode class for modes which don't fit into the above
1254
classes.  Currently @code{VOIDmode} and @code{BLKmode} are in
1255
@code{MODE_RANDOM}.
1256
@end table
1257
 
1258
Here are some C macros that relate to machine modes:
1259
 
1260
@table @code
1261
@findex GET_MODE
1262
@item GET_MODE (@var{x})
1263
Returns the machine mode of the RTX @var{x}.
1264
 
1265
@findex PUT_MODE
1266
@item PUT_MODE (@var{x}, @var{newmode})
1267
Alters the machine mode of the RTX @var{x} to be @var{newmode}.
1268
 
1269
@findex NUM_MACHINE_MODES
1270
@item NUM_MACHINE_MODES
1271
Stands for the number of machine modes available on the target
1272
machine.  This is one greater than the largest numeric value of any
1273
machine mode.
1274
 
1275
@findex GET_MODE_NAME
1276
@item GET_MODE_NAME (@var{m})
1277
Returns the name of mode @var{m} as a string.
1278
 
1279
@findex GET_MODE_CLASS
1280
@item GET_MODE_CLASS (@var{m})
1281
Returns the mode class of mode @var{m}.
1282
 
1283
@findex GET_MODE_WIDER_MODE
1284
@item GET_MODE_WIDER_MODE (@var{m})
1285
Returns the next wider natural mode.  For example, the expression
1286
@code{GET_MODE_WIDER_MODE (QImode)} returns @code{HImode}.
1287
 
1288
@findex GET_MODE_SIZE
1289
@item GET_MODE_SIZE (@var{m})
1290
Returns the size in bytes of a datum of mode @var{m}.
1291
 
1292
@findex GET_MODE_BITSIZE
1293
@item GET_MODE_BITSIZE (@var{m})
1294
Returns the size in bits of a datum of mode @var{m}.
1295
 
1296
@findex GET_MODE_MASK
1297
@item GET_MODE_MASK (@var{m})
1298
Returns a bitmask containing 1 for all bits in a word that fit within
1299
mode @var{m}.  This macro can only be used for modes whose bitsize is
1300
less than or equal to @code{HOST_BITS_PER_INT}.
1301
 
1302
@findex GET_MODE_ALIGNMENT
1303
@item GET_MODE_ALIGNMENT (@var{m})
1304
Return the required alignment, in bits, for an object of mode @var{m}.
1305
 
1306
@findex GET_MODE_UNIT_SIZE
1307
@item GET_MODE_UNIT_SIZE (@var{m})
1308
Returns the size in bytes of the subunits of a datum of mode @var{m}.
1309
This is the same as @code{GET_MODE_SIZE} except in the case of complex
1310
modes.  For them, the unit size is the size of the real or imaginary
1311
part.
1312
 
1313
@findex GET_MODE_NUNITS
1314
@item GET_MODE_NUNITS (@var{m})
1315
Returns the number of units contained in a mode, i.e.,
1316
@code{GET_MODE_SIZE} divided by @code{GET_MODE_UNIT_SIZE}.
1317
 
1318
@findex GET_CLASS_NARROWEST_MODE
1319
@item GET_CLASS_NARROWEST_MODE (@var{c})
1320
Returns the narrowest mode in mode class @var{c}.
1321
@end table
1322
 
1323
@findex byte_mode
1324
@findex word_mode
1325
The global variables @code{byte_mode} and @code{word_mode} contain modes
1326
whose classes are @code{MODE_INT} and whose bitsizes are either
1327
@code{BITS_PER_UNIT} or @code{BITS_PER_WORD}, respectively.  On 32-bit
1328
machines, these are @code{QImode} and @code{SImode}, respectively.
1329
 
1330
@node Constants
1331
@section Constant Expression Types
1332
@cindex RTL constants
1333
@cindex RTL constant expression types
1334
 
1335
The simplest RTL expressions are those that represent constant values.
1336
 
1337
@table @code
1338
@findex const_int
1339
@item (const_int @var{i})
1340
This type of expression represents the integer value @var{i}.  @var{i}
1341
is customarily accessed with the macro @code{INTVAL} as in
1342
@code{INTVAL (@var{exp})}, which is equivalent to @code{XWINT (@var{exp}, 0)}.
1343
 
1344
Constants generated for modes with fewer bits than @code{HOST_WIDE_INT}
1345
must be sign extended to full width (e.g., with @code{gen_int_mode}).
1346
 
1347
@findex const0_rtx
1348
@findex const1_rtx
1349
@findex const2_rtx
1350
@findex constm1_rtx
1351
There is only one expression object for the integer value zero; it is
1352
the value of the variable @code{const0_rtx}.  Likewise, the only
1353
expression for integer value one is found in @code{const1_rtx}, the only
1354
expression for integer value two is found in @code{const2_rtx}, and the
1355
only expression for integer value negative one is found in
1356
@code{constm1_rtx}.  Any attempt to create an expression of code
1357
@code{const_int} and value zero, one, two or negative one will return
1358
@code{const0_rtx}, @code{const1_rtx}, @code{const2_rtx} or
1359
@code{constm1_rtx} as appropriate.
1360
 
1361
@findex const_true_rtx
1362
Similarly, there is only one object for the integer whose value is
1363
@code{STORE_FLAG_VALUE}.  It is found in @code{const_true_rtx}.  If
1364
@code{STORE_FLAG_VALUE} is one, @code{const_true_rtx} and
1365
@code{const1_rtx} will point to the same object.  If
1366
@code{STORE_FLAG_VALUE} is @minus{}1, @code{const_true_rtx} and
1367
@code{constm1_rtx} will point to the same object.
1368
 
1369
@findex const_double
1370
@item (const_double:@var{m} @var{addr} @var{i0} @var{i1} @dots{})
1371
Represents either a floating-point constant of mode @var{m} or an
1372
integer constant too large to fit into @code{HOST_BITS_PER_WIDE_INT}
1373
bits but small enough to fit within twice that number of bits (GCC
1374
does not provide a mechanism to represent even larger constants).  In
1375
the latter case, @var{m} will be @code{VOIDmode}.
1376
 
1377
@findex const_vector
1378
@item (const_vector:@var{m} [@var{x0} @var{x1} @dots{}])
1379
Represents a vector constant.  The square brackets stand for the vector
1380
containing the constant elements.  @var{x0}, @var{x1} and so on are
1381
the @code{const_int} or @code{const_double} elements.
1382
 
1383
The number of units in a @code{const_vector} is obtained with the macro
1384
@code{CONST_VECTOR_NUNITS} as in @code{CONST_VECTOR_NUNITS (@var{v})}.
1385
 
1386
Individual elements in a vector constant are accessed with the macro
1387
@code{CONST_VECTOR_ELT} as in @code{CONST_VECTOR_ELT (@var{v}, @var{n})}
1388
where @var{v} is the vector constant and @var{n} is the element
1389
desired.
1390
 
1391
@findex CONST_DOUBLE_MEM
1392
@findex CONST_DOUBLE_CHAIN
1393
@var{addr} is used to contain the @code{mem} expression that corresponds
1394
to the location in memory that at which the constant can be found.  If
1395
it has not been allocated a memory location, but is on the chain of all
1396
@code{const_double} expressions in this compilation (maintained using an
1397
undisplayed field), @var{addr} contains @code{const0_rtx}.  If it is not
1398
on the chain, @var{addr} contains @code{cc0_rtx}.  @var{addr} is
1399
customarily accessed with the macro @code{CONST_DOUBLE_MEM} and the
1400
chain field via @code{CONST_DOUBLE_CHAIN}.
1401
 
1402
@findex CONST_DOUBLE_LOW
1403
If @var{m} is @code{VOIDmode}, the bits of the value are stored in
1404
@var{i0} and @var{i1}.  @var{i0} is customarily accessed with the macro
1405
@code{CONST_DOUBLE_LOW} and @var{i1} with @code{CONST_DOUBLE_HIGH}.
1406
 
1407
If the constant is floating point (regardless of its precision), then
1408
the number of integers used to store the value depends on the size of
1409
@code{REAL_VALUE_TYPE} (@pxref{Floating Point}).  The integers
1410
represent a floating point number, but not precisely in the target
1411
machine's or host machine's floating point format.  To convert them to
1412
the precise bit pattern used by the target machine, use the macro
1413
@code{REAL_VALUE_TO_TARGET_DOUBLE} and friends (@pxref{Data Output}).
1414
 
1415
@findex CONST0_RTX
1416
@findex CONST1_RTX
1417
@findex CONST2_RTX
1418
The macro @code{CONST0_RTX (@var{mode})} refers to an expression with
1419
value 0 in mode @var{mode}.  If mode @var{mode} is of mode class
1420
@code{MODE_INT}, it returns @code{const0_rtx}.  If mode @var{mode} is of
1421
mode class @code{MODE_FLOAT}, it returns a @code{CONST_DOUBLE}
1422
expression in mode @var{mode}.  Otherwise, it returns a
1423
@code{CONST_VECTOR} expression in mode @var{mode}.  Similarly, the macro
1424
@code{CONST1_RTX (@var{mode})} refers to an expression with value 1 in
1425
mode @var{mode} and similarly for @code{CONST2_RTX}.  The
1426
@code{CONST1_RTX} and @code{CONST2_RTX} macros are undefined
1427
for vector modes.
1428
 
1429
@findex const_string
1430
@item (const_string @var{str})
1431
Represents a constant string with value @var{str}.  Currently this is
1432
used only for insn attributes (@pxref{Insn Attributes}) since constant
1433
strings in C are placed in memory.
1434
 
1435
@findex symbol_ref
1436
@item (symbol_ref:@var{mode} @var{symbol})
1437
Represents the value of an assembler label for data.  @var{symbol} is
1438
a string that describes the name of the assembler label.  If it starts
1439
with a @samp{*}, the label is the rest of @var{symbol} not including
1440
the @samp{*}.  Otherwise, the label is @var{symbol}, usually prefixed
1441
with @samp{_}.
1442
 
1443
The @code{symbol_ref} contains a mode, which is usually @code{Pmode}.
1444
Usually that is the only mode for which a symbol is directly valid.
1445
 
1446
@findex label_ref
1447
@item (label_ref:@var{mode} @var{label})
1448
Represents the value of an assembler label for code.  It contains one
1449
operand, an expression, which must be a @code{code_label} or a @code{note}
1450
of type @code{NOTE_INSN_DELETED_LABEL} that appears in the instruction
1451
sequence to identify the place where the label should go.
1452
 
1453
The reason for using a distinct expression type for code label
1454
references is so that jump optimization can distinguish them.
1455
 
1456
The @code{label_ref} contains a mode, which is usually @code{Pmode}.
1457
Usually that is the only mode for which a label is directly valid.
1458
 
1459
@item (const:@var{m} @var{exp})
1460
Represents a constant that is the result of an assembly-time
1461
arithmetic computation.  The operand, @var{exp}, is an expression that
1462
contains only constants (@code{const_int}, @code{symbol_ref} and
1463
@code{label_ref} expressions) combined with @code{plus} and
1464
@code{minus}.  However, not all combinations are valid, since the
1465
assembler cannot do arbitrary arithmetic on relocatable symbols.
1466
 
1467
@var{m} should be @code{Pmode}.
1468
 
1469
@findex high
1470
@item (high:@var{m} @var{exp})
1471
Represents the high-order bits of @var{exp}, usually a
1472
@code{symbol_ref}.  The number of bits is machine-dependent and is
1473
normally the number of bits specified in an instruction that initializes
1474
the high order bits of a register.  It is used with @code{lo_sum} to
1475
represent the typical two-instruction sequence used in RISC machines to
1476
reference a global memory location.
1477
 
1478
@var{m} should be @code{Pmode}.
1479
@end table
1480
 
1481
@node Regs and Memory
1482
@section Registers and Memory
1483
@cindex RTL register expressions
1484
@cindex RTL memory expressions
1485
 
1486
Here are the RTL expression types for describing access to machine
1487
registers and to main memory.
1488
 
1489
@table @code
1490
@findex reg
1491
@cindex hard registers
1492
@cindex pseudo registers
1493
@item (reg:@var{m} @var{n})
1494
For small values of the integer @var{n} (those that are less than
1495
@code{FIRST_PSEUDO_REGISTER}), this stands for a reference to machine
1496
register number @var{n}: a @dfn{hard register}.  For larger values of
1497
@var{n}, it stands for a temporary value or @dfn{pseudo register}.
1498
The compiler's strategy is to generate code assuming an unlimited
1499
number of such pseudo registers, and later convert them into hard
1500
registers or into memory references.
1501
 
1502
@var{m} is the machine mode of the reference.  It is necessary because
1503
machines can generally refer to each register in more than one mode.
1504
For example, a register may contain a full word but there may be
1505
instructions to refer to it as a half word or as a single byte, as
1506
well as instructions to refer to it as a floating point number of
1507
various precisions.
1508
 
1509
Even for a register that the machine can access in only one mode,
1510
the mode must always be specified.
1511
 
1512
The symbol @code{FIRST_PSEUDO_REGISTER} is defined by the machine
1513
description, since the number of hard registers on the machine is an
1514
invariant characteristic of the machine.  Note, however, that not
1515
all of the machine registers must be general registers.  All the
1516
machine registers that can be used for storage of data are given
1517
hard register numbers, even those that can be used only in certain
1518
instructions or can hold only certain types of data.
1519
 
1520
A hard register may be accessed in various modes throughout one
1521
function, but each pseudo register is given a natural mode
1522
and is accessed only in that mode.  When it is necessary to describe
1523
an access to a pseudo register using a nonnatural mode, a @code{subreg}
1524
expression is used.
1525
 
1526
A @code{reg} expression with a machine mode that specifies more than
1527
one word of data may actually stand for several consecutive registers.
1528
If in addition the register number specifies a hardware register, then
1529
it actually represents several consecutive hardware registers starting
1530
with the specified one.
1531
 
1532
Each pseudo register number used in a function's RTL code is
1533
represented by a unique @code{reg} expression.
1534
 
1535
@findex FIRST_VIRTUAL_REGISTER
1536
@findex LAST_VIRTUAL_REGISTER
1537
Some pseudo register numbers, those within the range of
1538
@code{FIRST_VIRTUAL_REGISTER} to @code{LAST_VIRTUAL_REGISTER} only
1539
appear during the RTL generation phase and are eliminated before the
1540
optimization phases.  These represent locations in the stack frame that
1541
cannot be determined until RTL generation for the function has been
1542
completed.  The following virtual register numbers are defined:
1543
 
1544
@table @code
1545
@findex VIRTUAL_INCOMING_ARGS_REGNUM
1546
@item VIRTUAL_INCOMING_ARGS_REGNUM
1547
This points to the first word of the incoming arguments passed on the
1548
stack.  Normally these arguments are placed there by the caller, but the
1549
callee may have pushed some arguments that were previously passed in
1550
registers.
1551
 
1552
@cindex @code{FIRST_PARM_OFFSET} and virtual registers
1553
@cindex @code{ARG_POINTER_REGNUM} and virtual registers
1554
When RTL generation is complete, this virtual register is replaced
1555
by the sum of the register given by @code{ARG_POINTER_REGNUM} and the
1556
value of @code{FIRST_PARM_OFFSET}.
1557
 
1558
@findex VIRTUAL_STACK_VARS_REGNUM
1559
@cindex @code{FRAME_GROWS_DOWNWARD} and virtual registers
1560
@item VIRTUAL_STACK_VARS_REGNUM
1561
If @code{FRAME_GROWS_DOWNWARD} is defined to a nonzero value, this points
1562
to immediately above the first variable on the stack.  Otherwise, it points
1563
to the first variable on the stack.
1564
 
1565
@cindex @code{STARTING_FRAME_OFFSET} and virtual registers
1566
@cindex @code{FRAME_POINTER_REGNUM} and virtual registers
1567
@code{VIRTUAL_STACK_VARS_REGNUM} is replaced with the sum of the
1568
register given by @code{FRAME_POINTER_REGNUM} and the value
1569
@code{STARTING_FRAME_OFFSET}.
1570
 
1571
@findex VIRTUAL_STACK_DYNAMIC_REGNUM
1572
@item VIRTUAL_STACK_DYNAMIC_REGNUM
1573
This points to the location of dynamically allocated memory on the stack
1574
immediately after the stack pointer has been adjusted by the amount of
1575
memory desired.
1576
 
1577
@cindex @code{STACK_DYNAMIC_OFFSET} and virtual registers
1578
@cindex @code{STACK_POINTER_REGNUM} and virtual registers
1579
This virtual register is replaced by the sum of the register given by
1580
@code{STACK_POINTER_REGNUM} and the value @code{STACK_DYNAMIC_OFFSET}.
1581
 
1582
@findex VIRTUAL_OUTGOING_ARGS_REGNUM
1583
@item VIRTUAL_OUTGOING_ARGS_REGNUM
1584
This points to the location in the stack at which outgoing arguments
1585
should be written when the stack is pre-pushed (arguments pushed using
1586
push insns should always use @code{STACK_POINTER_REGNUM}).
1587
 
1588
@cindex @code{STACK_POINTER_OFFSET} and virtual registers
1589
This virtual register is replaced by the sum of the register given by
1590
@code{STACK_POINTER_REGNUM} and the value @code{STACK_POINTER_OFFSET}.
1591
@end table
1592
 
1593
@findex subreg
1594
@item (subreg:@var{m} @var{reg} @var{bytenum})
1595
@code{subreg} expressions are used to refer to a register in a machine
1596
mode other than its natural one, or to refer to one register of
1597
a multi-part @code{reg} that actually refers to several registers.
1598
 
1599
Each pseudo-register has a natural mode.  If it is necessary to
1600
operate on it in a different mode---for example, to perform a fullword
1601
move instruction on a pseudo-register that contains a single
1602
byte---the pseudo-register must be enclosed in a @code{subreg}.  In
1603
such a case, @var{bytenum} is zero.
1604
 
1605
Usually @var{m} is at least as narrow as the mode of @var{reg}, in which
1606
case it is restricting consideration to only the bits of @var{reg} that
1607
are in @var{m}.
1608
 
1609
Sometimes @var{m} is wider than the mode of @var{reg}.  These
1610
@code{subreg} expressions are often called @dfn{paradoxical}.  They are
1611
used in cases where we want to refer to an object in a wider mode but do
1612
not care what value the additional bits have.  The reload pass ensures
1613
that paradoxical references are only made to hard registers.
1614
 
1615
The other use of @code{subreg} is to extract the individual registers of
1616
a multi-register value.  Machine modes such as @code{DImode} and
1617
@code{TImode} can indicate values longer than a word, values which
1618
usually require two or more consecutive registers.  To access one of the
1619
registers, use a @code{subreg} with mode @code{SImode} and a
1620
@var{bytenum} offset that says which register.
1621
 
1622
Storing in a non-paradoxical @code{subreg} has undefined results for
1623
bits belonging to the same word as the @code{subreg}.  This laxity makes
1624
it easier to generate efficient code for such instructions.  To
1625
represent an instruction that preserves all the bits outside of those in
1626
the @code{subreg}, use @code{strict_low_part} around the @code{subreg}.
1627
 
1628
@cindex @code{WORDS_BIG_ENDIAN}, effect on @code{subreg}
1629
The compilation parameter @code{WORDS_BIG_ENDIAN}, if set to 1, says
1630
that byte number zero is part of the most significant word; otherwise,
1631
it is part of the least significant word.
1632
 
1633
@cindex @code{BYTES_BIG_ENDIAN}, effect on @code{subreg}
1634
The compilation parameter @code{BYTES_BIG_ENDIAN}, if set to 1, says
1635
that byte number zero is the most significant byte within a word;
1636
otherwise, it is the least significant byte within a word.
1637
 
1638
@cindex @code{FLOAT_WORDS_BIG_ENDIAN}, (lack of) effect on @code{subreg}
1639
On a few targets, @code{FLOAT_WORDS_BIG_ENDIAN} disagrees with
1640
@code{WORDS_BIG_ENDIAN}.
1641
However, most parts of the compiler treat floating point values as if
1642
they had the same endianness as integer values.  This works because
1643
they handle them solely as a collection of integer values, with no
1644
particular numerical value.  Only real.c and the runtime libraries
1645
care about @code{FLOAT_WORDS_BIG_ENDIAN}.
1646
 
1647
@cindex combiner pass
1648
@cindex reload pass
1649
@cindex @code{subreg}, special reload handling
1650
Between the combiner pass and the reload pass, it is possible to have a
1651
paradoxical @code{subreg} which contains a @code{mem} instead of a
1652
@code{reg} as its first operand.  After the reload pass, it is also
1653
possible to have a non-paradoxical @code{subreg} which contains a
1654
@code{mem}; this usually occurs when the @code{mem} is a stack slot
1655
which replaced a pseudo register.
1656
 
1657
Note that it is not valid to access a @code{DFmode} value in @code{SFmode}
1658
using a @code{subreg}.  On some machines the most significant part of a
1659
@code{DFmode} value does not have the same format as a single-precision
1660
floating value.
1661
 
1662
It is also not valid to access a single word of a multi-word value in a
1663
hard register when less registers can hold the value than would be
1664
expected from its size.  For example, some 32-bit machines have
1665
floating-point registers that can hold an entire @code{DFmode} value.
1666
If register 10 were such a register @code{(subreg:SI (reg:DF 10) 4)}
1667
would be invalid because there is no way to convert that reference to
1668
a single machine register.  The reload pass prevents @code{subreg}
1669
expressions such as these from being formed.
1670
 
1671
@findex SUBREG_REG
1672
@findex SUBREG_BYTE
1673
The first operand of a @code{subreg} expression is customarily accessed
1674
with the @code{SUBREG_REG} macro and the second operand is customarily
1675
accessed with the @code{SUBREG_BYTE} macro.
1676
 
1677
@findex scratch
1678
@cindex scratch operands
1679
@item (scratch:@var{m})
1680
This represents a scratch register that will be required for the
1681
execution of a single instruction and not used subsequently.  It is
1682
converted into a @code{reg} by either the local register allocator or
1683
the reload pass.
1684
 
1685
@code{scratch} is usually present inside a @code{clobber} operation
1686
(@pxref{Side Effects}).
1687
 
1688
@findex cc0
1689
@cindex condition code register
1690
@item (cc0)
1691
This refers to the machine's condition code register.  It has no
1692
operands and may not have a machine mode.  There are two ways to use it:
1693
 
1694
@itemize @bullet
1695
@item
1696
To stand for a complete set of condition code flags.  This is best on
1697
most machines, where each comparison sets the entire series of flags.
1698
 
1699
With this technique, @code{(cc0)} may be validly used in only two
1700
contexts: as the destination of an assignment (in test and compare
1701
instructions) and in comparison operators comparing against zero
1702
(@code{const_int} with value zero; that is to say, @code{const0_rtx}).
1703
 
1704
@item
1705
To stand for a single flag that is the result of a single condition.
1706
This is useful on machines that have only a single flag bit, and in
1707
which comparison instructions must specify the condition to test.
1708
 
1709
With this technique, @code{(cc0)} may be validly used in only two
1710
contexts: as the destination of an assignment (in test and compare
1711
instructions) where the source is a comparison operator, and as the
1712
first operand of @code{if_then_else} (in a conditional branch).
1713
@end itemize
1714
 
1715
@findex cc0_rtx
1716
There is only one expression object of code @code{cc0}; it is the
1717
value of the variable @code{cc0_rtx}.  Any attempt to create an
1718
expression of code @code{cc0} will return @code{cc0_rtx}.
1719
 
1720
Instructions can set the condition code implicitly.  On many machines,
1721
nearly all instructions set the condition code based on the value that
1722
they compute or store.  It is not necessary to record these actions
1723
explicitly in the RTL because the machine description includes a
1724
prescription for recognizing the instructions that do so (by means of
1725
the macro @code{NOTICE_UPDATE_CC}).  @xref{Condition Code}.  Only
1726
instructions whose sole purpose is to set the condition code, and
1727
instructions that use the condition code, need mention @code{(cc0)}.
1728
 
1729
On some machines, the condition code register is given a register number
1730
and a @code{reg} is used instead of @code{(cc0)}.  This is usually the
1731
preferable approach if only a small subset of instructions modify the
1732
condition code.  Other machines store condition codes in general
1733
registers; in such cases a pseudo register should be used.
1734
 
1735
Some machines, such as the SPARC and RS/6000, have two sets of
1736
arithmetic instructions, one that sets and one that does not set the
1737
condition code.  This is best handled by normally generating the
1738
instruction that does not set the condition code, and making a pattern
1739
that both performs the arithmetic and sets the condition code register
1740
(which would not be @code{(cc0)} in this case).  For examples, search
1741
for @samp{addcc} and @samp{andcc} in @file{sparc.md}.
1742
 
1743
@findex pc
1744
@item (pc)
1745
@cindex program counter
1746
This represents the machine's program counter.  It has no operands and
1747
may not have a machine mode.  @code{(pc)} may be validly used only in
1748
certain specific contexts in jump instructions.
1749
 
1750
@findex pc_rtx
1751
There is only one expression object of code @code{pc}; it is the value
1752
of the variable @code{pc_rtx}.  Any attempt to create an expression of
1753
code @code{pc} will return @code{pc_rtx}.
1754
 
1755
All instructions that do not jump alter the program counter implicitly
1756
by incrementing it, but there is no need to mention this in the RTL@.
1757
 
1758
@findex mem
1759
@item (mem:@var{m} @var{addr} @var{alias})
1760
This RTX represents a reference to main memory at an address
1761
represented by the expression @var{addr}.  @var{m} specifies how large
1762
a unit of memory is accessed.  @var{alias} specifies an alias set for the
1763
reference.  In general two items are in different alias sets if they cannot
1764
reference the same memory address.
1765
 
1766
The construct @code{(mem:BLK (scratch))} is considered to alias all
1767
other memories.  Thus it may be used as a memory barrier in epilogue
1768
stack deallocation patterns.
1769
 
1770
@findex addressof
1771
@item (addressof:@var{m} @var{reg})
1772
This RTX represents a request for the address of register @var{reg}.  Its mode
1773
is always @code{Pmode}.  If there are any @code{addressof}
1774
expressions left in the function after CSE, @var{reg} is forced into the
1775
stack and the @code{addressof} expression is replaced with a @code{plus}
1776
expression for the address of its stack slot.
1777
@end table
1778
 
1779
@node Arithmetic
1780
@section RTL Expressions for Arithmetic
1781
@cindex arithmetic, in RTL
1782
@cindex math, in RTL
1783
@cindex RTL expressions for arithmetic
1784
 
1785
Unless otherwise specified, all the operands of arithmetic expressions
1786
must be valid for mode @var{m}.  An operand is valid for mode @var{m}
1787
if it has mode @var{m}, or if it is a @code{const_int} or
1788
@code{const_double} and @var{m} is a mode of class @code{MODE_INT}.
1789
 
1790
For commutative binary operations, constants should be placed in the
1791
second operand.
1792
 
1793
@table @code
1794
@findex plus
1795
@findex ss_plus
1796
@findex us_plus
1797
@cindex RTL sum
1798
@cindex RTL addition
1799
@cindex RTL addition with signed saturation
1800
@cindex RTL addition with unsigned saturation
1801
@item (plus:@var{m} @var{x} @var{y})
1802
@itemx (ss_plus:@var{m} @var{x} @var{y})
1803
@itemx (us_plus:@var{m} @var{x} @var{y})
1804
 
1805
These three expressions all represent the sum of the values
1806
represented by @var{x} and @var{y} carried out in machine mode
1807
@var{m}.  They differ in their behavior on overflow of integer modes.
1808
@code{plus} wraps round modulo the width of @var{m}; @code{ss_plus}
1809
saturates at the maximum signed value representable in @var{m};
1810
@code{us_plus} saturates at the maximum unsigned value.
1811
 
1812
@c ??? What happens on overflow of floating point modes?
1813
 
1814
@findex lo_sum
1815
@item (lo_sum:@var{m} @var{x} @var{y})
1816
 
1817
This expression represents the sum of @var{x} and the low-order bits
1818
of @var{y}.  It is used with @code{high} (@pxref{Constants}) to
1819
represent the typical two-instruction sequence used in RISC machines
1820
to reference a global memory location.
1821
 
1822
The number of low order bits is machine-dependent but is
1823
normally the number of bits in a @code{Pmode} item minus the number of
1824
bits set by @code{high}.
1825
 
1826
@var{m} should be @code{Pmode}.
1827
 
1828
@findex minus
1829
@findex ss_minus
1830
@findex us_minus
1831
@cindex RTL difference
1832
@cindex RTL subtraction
1833
@cindex RTL subtraction with signed saturation
1834
@cindex RTL subtraction with unsigned saturation
1835
@item (minus:@var{m} @var{x} @var{y})
1836
@itemx (ss_minus:@var{m} @var{x} @var{y})
1837
@itemx (us_minus:@var{m} @var{x} @var{y})
1838
 
1839
These three expressions represent the result of subtracting @var{y}
1840
from @var{x}, carried out in mode @var{M}.  Behavior on overflow is
1841
the same as for the three variants of @code{plus} (see above).
1842
 
1843
@findex compare
1844
@cindex RTL comparison
1845
@item (compare:@var{m} @var{x} @var{y})
1846
Represents the result of subtracting @var{y} from @var{x} for purposes
1847
of comparison.  The result is computed without overflow, as if with
1848
infinite precision.
1849
 
1850
Of course, machines can't really subtract with infinite precision.
1851
However, they can pretend to do so when only the sign of the result will
1852
be used, which is the case when the result is stored in the condition
1853
code.  And that is the @emph{only} way this kind of expression may
1854
validly be used: as a value to be stored in the condition codes, either
1855
@code{(cc0)} or a register.  @xref{Comparisons}.
1856
 
1857
The mode @var{m} is not related to the modes of @var{x} and @var{y}, but
1858
instead is the mode of the condition code value.  If @code{(cc0)} is
1859
used, it is @code{VOIDmode}.  Otherwise it is some mode in class
1860
@code{MODE_CC}, often @code{CCmode}.  @xref{Condition Code}.  If @var{m}
1861
is @code{VOIDmode} or @code{CCmode}, the operation returns sufficient
1862
information (in an unspecified format) so that any comparison operator
1863
can be applied to the result of the @code{COMPARE} operation.  For other
1864
modes in class @code{MODE_CC}, the operation only returns a subset of
1865
this information.
1866
 
1867
Normally, @var{x} and @var{y} must have the same mode.  Otherwise,
1868
@code{compare} is valid only if the mode of @var{x} is in class
1869
@code{MODE_INT} and @var{y} is a @code{const_int} or
1870
@code{const_double} with mode @code{VOIDmode}.  The mode of @var{x}
1871
determines what mode the comparison is to be done in; thus it must not
1872
be @code{VOIDmode}.
1873
 
1874
If one of the operands is a constant, it should be placed in the
1875
second operand and the comparison code adjusted as appropriate.
1876
 
1877
A @code{compare} specifying two @code{VOIDmode} constants is not valid
1878
since there is no way to know in what mode the comparison is to be
1879
performed; the comparison must either be folded during the compilation
1880
or the first operand must be loaded into a register while its mode is
1881
still known.
1882
 
1883
@findex neg
1884
@findex ss_neg
1885
@cindex negation
1886
@cindex negation with signed saturation
1887
@item (neg:@var{m} @var{x})
1888
@itemx (ss_neg:@var{m} @var{x})
1889
These two expressions represent the negation (subtraction from zero) of
1890
the value represented by @var{x}, carried out in mode @var{m}.  They
1891
differ in the behavior on overflow of integer modes.  In the case of
1892
@code{neg}, the negation of the operand may be a number not representable
1893
in mode @var{m}, in which case it is truncated to @var{m}.  @code{ss_neg}
1894
ensures that an out-of-bounds result saturates to the maximum or minimum
1895
representable value.
1896
 
1897
@findex mult
1898
@cindex multiplication
1899
@cindex product
1900
@item (mult:@var{m} @var{x} @var{y})
1901
Represents the signed product of the values represented by @var{x} and
1902
@var{y} carried out in machine mode @var{m}.
1903
 
1904
Some machines support a multiplication that generates a product wider
1905
than the operands.  Write the pattern for this as
1906
 
1907
@smallexample
1908
(mult:@var{m} (sign_extend:@var{m} @var{x}) (sign_extend:@var{m} @var{y}))
1909
@end smallexample
1910
 
1911
where @var{m} is wider than the modes of @var{x} and @var{y}, which need
1912
not be the same.
1913
 
1914
For unsigned widening multiplication, use the same idiom, but with
1915
@code{zero_extend} instead of @code{sign_extend}.
1916
 
1917
@findex div
1918
@cindex division
1919
@cindex signed division
1920
@cindex quotient
1921
@item (div:@var{m} @var{x} @var{y})
1922
Represents the quotient in signed division of @var{x} by @var{y},
1923
carried out in machine mode @var{m}.  If @var{m} is a floating point
1924
mode, it represents the exact quotient; otherwise, the integerized
1925
quotient.
1926
 
1927
Some machines have division instructions in which the operands and
1928
quotient widths are not all the same; you should represent
1929
such instructions using @code{truncate} and @code{sign_extend} as in,
1930
 
1931
@smallexample
1932
(truncate:@var{m1} (div:@var{m2} @var{x} (sign_extend:@var{m2} @var{y})))
1933
@end smallexample
1934
 
1935
@findex udiv
1936
@cindex unsigned division
1937
@cindex division
1938
@item (udiv:@var{m} @var{x} @var{y})
1939
Like @code{div} but represents unsigned division.
1940
 
1941
@findex mod
1942
@findex umod
1943
@cindex remainder
1944
@cindex division
1945
@item (mod:@var{m} @var{x} @var{y})
1946
@itemx (umod:@var{m} @var{x} @var{y})
1947
Like @code{div} and @code{udiv} but represent the remainder instead of
1948
the quotient.
1949
 
1950
@findex smin
1951
@findex smax
1952
@cindex signed minimum
1953
@cindex signed maximum
1954
@item (smin:@var{m} @var{x} @var{y})
1955
@itemx (smax:@var{m} @var{x} @var{y})
1956
Represents the smaller (for @code{smin}) or larger (for @code{smax}) of
1957
@var{x} and @var{y}, interpreted as signed values in mode @var{m}.
1958
When used with floating point, if both operands are zeros, or if either
1959
operand is @code{NaN}, then it is unspecified which of the two operands
1960
is returned as the result.
1961
 
1962
@findex umin
1963
@findex umax
1964
@cindex unsigned minimum and maximum
1965
@item (umin:@var{m} @var{x} @var{y})
1966
@itemx (umax:@var{m} @var{x} @var{y})
1967
Like @code{smin} and @code{smax}, but the values are interpreted as unsigned
1968
integers.
1969
 
1970
@findex not
1971
@cindex complement, bitwise
1972
@cindex bitwise complement
1973
@item (not:@var{m} @var{x})
1974
Represents the bitwise complement of the value represented by @var{x},
1975
carried out in mode @var{m}, which must be a fixed-point machine mode.
1976
 
1977
@findex and
1978
@cindex logical-and, bitwise
1979
@cindex bitwise logical-and
1980
@item (and:@var{m} @var{x} @var{y})
1981
Represents the bitwise logical-and of the values represented by
1982
@var{x} and @var{y}, carried out in machine mode @var{m}, which must be
1983
a fixed-point machine mode.
1984
 
1985
@findex ior
1986
@cindex inclusive-or, bitwise
1987
@cindex bitwise inclusive-or
1988
@item (ior:@var{m} @var{x} @var{y})
1989
Represents the bitwise inclusive-or of the values represented by @var{x}
1990
and @var{y}, carried out in machine mode @var{m}, which must be a
1991
fixed-point mode.
1992
 
1993
@findex xor
1994
@cindex exclusive-or, bitwise
1995
@cindex bitwise exclusive-or
1996
@item (xor:@var{m} @var{x} @var{y})
1997
Represents the bitwise exclusive-or of the values represented by @var{x}
1998
and @var{y}, carried out in machine mode @var{m}, which must be a
1999
fixed-point mode.
2000
 
2001
@findex ashift
2002
@findex ss_ashift
2003
@cindex left shift
2004
@cindex shift
2005
@cindex arithmetic shift
2006
@cindex arithmetic shift with signed saturation
2007
@item (ashift:@var{m} @var{x} @var{c})
2008
@itemx (ss_ashift:@var{m} @var{x} @var{c})
2009
These two expressions represent the result of arithmetically shifting @var{x}
2010
left by @var{c} places.  They differ in their behavior on overflow of integer
2011
modes.  An @code{ashift} operation is a plain shift with no special behavior
2012
in case of a change in the sign bit; @code{ss_ashift} saturates to the minimum
2013
or maximum representable value if any of the bits shifted out differs from the
2014
final sign bit.
2015
 
2016
@var{x} have mode @var{m}, a fixed-point machine mode.  @var{c}
2017
be a fixed-point mode or be a constant with mode @code{VOIDmode}; which
2018
mode is determined by the mode called for in the machine description
2019
entry for the left-shift instruction.  For example, on the VAX, the mode
2020
of @var{c} is @code{QImode} regardless of @var{m}.
2021
 
2022
@findex lshiftrt
2023
@cindex right shift
2024
@findex ashiftrt
2025
@item (lshiftrt:@var{m} @var{x} @var{c})
2026
@itemx (ashiftrt:@var{m} @var{x} @var{c})
2027
Like @code{ashift} but for right shift.  Unlike the case for left shift,
2028
these two operations are distinct.
2029
 
2030
@findex rotate
2031
@cindex rotate
2032
@cindex left rotate
2033
@findex rotatert
2034
@cindex right rotate
2035
@item (rotate:@var{m} @var{x} @var{c})
2036
@itemx (rotatert:@var{m} @var{x} @var{c})
2037
Similar but represent left and right rotate.  If @var{c} is a constant,
2038
use @code{rotate}.
2039
 
2040
@findex abs
2041
@cindex absolute value
2042
@item (abs:@var{m} @var{x})
2043
Represents the absolute value of @var{x}, computed in mode @var{m}.
2044
 
2045
@findex sqrt
2046
@cindex square root
2047
@item (sqrt:@var{m} @var{x})
2048
Represents the square root of @var{x}, computed in mode @var{m}.
2049
Most often @var{m} will be a floating point mode.
2050
 
2051
@findex ffs
2052
@item (ffs:@var{m} @var{x})
2053
Represents one plus the index of the least significant 1-bit in
2054
@var{x}, represented as an integer of mode @var{m}.  (The value is
2055
zero if @var{x} is zero.)  The mode of @var{x} need not be @var{m};
2056
depending on the target machine, various mode combinations may be
2057
valid.
2058
 
2059
@findex clz
2060
@item (clz:@var{m} @var{x})
2061
Represents the number of leading 0-bits in @var{x}, represented as an
2062
integer of mode @var{m}, starting at the most significant bit position.
2063
If @var{x} is zero, the value is determined by
2064
@code{CLZ_DEFINED_VALUE_AT_ZERO}.  Note that this is one of
2065
the few expressions that is not invariant under widening.  The mode of
2066
@var{x} will usually be an integer mode.
2067
 
2068
@findex ctz
2069
@item (ctz:@var{m} @var{x})
2070
Represents the number of trailing 0-bits in @var{x}, represented as an
2071
integer of mode @var{m}, starting at the least significant bit position.
2072
If @var{x} is zero, the value is determined by
2073
@code{CTZ_DEFINED_VALUE_AT_ZERO}.  Except for this case,
2074
@code{ctz(x)} is equivalent to @code{ffs(@var{x}) - 1}.  The mode of
2075
@var{x} will usually be an integer mode.
2076
 
2077
@findex popcount
2078
@item (popcount:@var{m} @var{x})
2079
Represents the number of 1-bits in @var{x}, represented as an integer of
2080
mode @var{m}.  The mode of @var{x} will usually be an integer mode.
2081
 
2082
@findex parity
2083
@item (parity:@var{m} @var{x})
2084
Represents the number of 1-bits modulo 2 in @var{x}, represented as an
2085
integer of mode @var{m}.  The mode of @var{x} will usually be an integer
2086
mode.
2087
@end table
2088
 
2089
@node Comparisons
2090
@section Comparison Operations
2091
@cindex RTL comparison operations
2092
 
2093
Comparison operators test a relation on two operands and are considered
2094
to represent a machine-dependent nonzero value described by, but not
2095
necessarily equal to, @code{STORE_FLAG_VALUE} (@pxref{Misc})
2096
if the relation holds, or zero if it does not, for comparison operators
2097
whose results have a `MODE_INT' mode,
2098
@code{FLOAT_STORE_FLAG_VALUE} (@pxref{Misc}) if the relation holds, or
2099
zero if it does not, for comparison operators that return floating-point
2100
values, and a vector of either @code{VECTOR_STORE_FLAG_VALUE} (@pxref{Misc})
2101
if the relation holds, or of zeros if it does not, for comparison operators
2102
that return vector results.
2103
The mode of the comparison operation is independent of the mode
2104
of the data being compared.  If the comparison operation is being tested
2105
(e.g., the first operand of an @code{if_then_else}), the mode must be
2106
@code{VOIDmode}.
2107
 
2108
@cindex condition codes
2109
There are two ways that comparison operations may be used.  The
2110
comparison operators may be used to compare the condition codes
2111
@code{(cc0)} against zero, as in @code{(eq (cc0) (const_int 0))}.  Such
2112
a construct actually refers to the result of the preceding instruction
2113
in which the condition codes were set.  The instruction setting the
2114
condition code must be adjacent to the instruction using the condition
2115
code; only @code{note} insns may separate them.
2116
 
2117
Alternatively, a comparison operation may directly compare two data
2118
objects.  The mode of the comparison is determined by the operands; they
2119
must both be valid for a common machine mode.  A comparison with both
2120
operands constant would be invalid as the machine mode could not be
2121
deduced from it, but such a comparison should never exist in RTL due to
2122
constant folding.
2123
 
2124
In the example above, if @code{(cc0)} were last set to
2125
@code{(compare @var{x} @var{y})}, the comparison operation is
2126
identical to @code{(eq @var{x} @var{y})}.  Usually only one style
2127
of comparisons is supported on a particular machine, but the combine
2128
pass will try to merge the operations to produce the @code{eq} shown
2129
in case it exists in the context of the particular insn involved.
2130
 
2131
Inequality comparisons come in two flavors, signed and unsigned.  Thus,
2132
there are distinct expression codes @code{gt} and @code{gtu} for signed and
2133
unsigned greater-than.  These can produce different results for the same
2134
pair of integer values: for example, 1 is signed greater-than @minus{}1 but not
2135
unsigned greater-than, because @minus{}1 when regarded as unsigned is actually
2136
@code{0xffffffff} which is greater than 1.
2137
 
2138
The signed comparisons are also used for floating point values.  Floating
2139
point comparisons are distinguished by the machine modes of the operands.
2140
 
2141
@table @code
2142
@findex eq
2143
@cindex equal
2144
@item (eq:@var{m} @var{x} @var{y})
2145
@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2146
are equal, otherwise 0.
2147
 
2148
@findex ne
2149
@cindex not equal
2150
@item (ne:@var{m} @var{x} @var{y})
2151
@code{STORE_FLAG_VALUE} if the values represented by @var{x} and @var{y}
2152
are not equal, otherwise 0.
2153
 
2154
@findex gt
2155
@cindex greater than
2156
@item (gt:@var{m} @var{x} @var{y})
2157
@code{STORE_FLAG_VALUE} if the @var{x} is greater than @var{y}.  If they
2158
are fixed-point, the comparison is done in a signed sense.
2159
 
2160
@findex gtu
2161
@cindex greater than
2162
@cindex unsigned greater than
2163
@item (gtu:@var{m} @var{x} @var{y})
2164
Like @code{gt} but does unsigned comparison, on fixed-point numbers only.
2165
 
2166
@findex lt
2167
@cindex less than
2168
@findex ltu
2169
@cindex unsigned less than
2170
@item (lt:@var{m} @var{x} @var{y})
2171
@itemx (ltu:@var{m} @var{x} @var{y})
2172
Like @code{gt} and @code{gtu} but test for ``less than''.
2173
 
2174
@findex ge
2175
@cindex greater than
2176
@findex geu
2177
@cindex unsigned greater than
2178
@item (ge:@var{m} @var{x} @var{y})
2179
@itemx (geu:@var{m} @var{x} @var{y})
2180
Like @code{gt} and @code{gtu} but test for ``greater than or equal''.
2181
 
2182
@findex le
2183
@cindex less than or equal
2184
@findex leu
2185
@cindex unsigned less than
2186
@item (le:@var{m} @var{x} @var{y})
2187
@itemx (leu:@var{m} @var{x} @var{y})
2188
Like @code{gt} and @code{gtu} but test for ``less than or equal''.
2189
 
2190
@findex if_then_else
2191
@item (if_then_else @var{cond} @var{then} @var{else})
2192
This is not a comparison operation but is listed here because it is
2193
always used in conjunction with a comparison operation.  To be
2194
precise, @var{cond} is a comparison expression.  This expression
2195
represents a choice, according to @var{cond}, between the value
2196
represented by @var{then} and the one represented by @var{else}.
2197
 
2198
On most machines, @code{if_then_else} expressions are valid only
2199
to express conditional jumps.
2200
 
2201
@findex cond
2202
@item (cond [@var{test1} @var{value1} @var{test2} @var{value2} @dots{}] @var{default})
2203
Similar to @code{if_then_else}, but more general.  Each of @var{test1},
2204
@var{test2}, @dots{} is performed in turn.  The result of this expression is
2205
the @var{value} corresponding to the first nonzero test, or @var{default} if
2206
none of the tests are nonzero expressions.
2207
 
2208
This is currently not valid for instruction patterns and is supported only
2209
for insn attributes.  @xref{Insn Attributes}.
2210
@end table
2211
 
2212
@node Bit-Fields
2213
@section Bit-Fields
2214
@cindex bit-fields
2215
 
2216
Special expression codes exist to represent bit-field instructions.
2217
 
2218
@table @code
2219
@findex sign_extract
2220
@cindex @code{BITS_BIG_ENDIAN}, effect on @code{sign_extract}
2221
@item (sign_extract:@var{m} @var{loc} @var{size} @var{pos})
2222
This represents a reference to a sign-extended bit-field contained or
2223
starting in @var{loc} (a memory or register reference).  The bit-field
2224
is @var{size} bits wide and starts at bit @var{pos}.  The compilation
2225
option @code{BITS_BIG_ENDIAN} says which end of the memory unit
2226
@var{pos} counts from.
2227
 
2228
If @var{loc} is in memory, its mode must be a single-byte integer mode.
2229
If @var{loc} is in a register, the mode to use is specified by the
2230
operand of the @code{insv} or @code{extv} pattern
2231
(@pxref{Standard Names}) and is usually a full-word integer mode,
2232
which is the default if none is specified.
2233
 
2234
The mode of @var{pos} is machine-specific and is also specified
2235
in the @code{insv} or @code{extv} pattern.
2236
 
2237
The mode @var{m} is the same as the mode that would be used for
2238
@var{loc} if it were a register.
2239
 
2240
A @code{sign_extract} can not appear as an lvalue, or part thereof,
2241
in RTL.
2242
 
2243
@findex zero_extract
2244
@item (zero_extract:@var{m} @var{loc} @var{size} @var{pos})
2245
Like @code{sign_extract} but refers to an unsigned or zero-extended
2246
bit-field.  The same sequence of bits are extracted, but they
2247
are filled to an entire word with zeros instead of by sign-extension.
2248
 
2249
Unlike @code{sign_extract}, this type of expressions can be lvalues
2250
in RTL; they may appear on the left side of an assignment, indicating
2251
insertion of a value into the specified bit-field.
2252
@end table
2253
 
2254
@node Vector Operations
2255
@section Vector Operations
2256
@cindex vector operations
2257
 
2258
All normal RTL expressions can be used with vector modes; they are
2259
interpreted as operating on each part of the vector independently.
2260
Additionally, there are a few new expressions to describe specific vector
2261
operations.
2262
 
2263
@table @code
2264
@findex vec_merge
2265
@item (vec_merge:@var{m} @var{vec1} @var{vec2} @var{items})
2266
This describes a merge operation between two vectors.  The result is a vector
2267
of mode @var{m}; its elements are selected from either @var{vec1} or
2268
@var{vec2}.  Which elements are selected is described by @var{items}, which
2269
is a bit mask represented by a @code{const_int}; a zero bit indicates the
2270
corresponding element in the result vector is taken from @var{vec2} while
2271
a set bit indicates it is taken from @var{vec1}.
2272
 
2273
@findex vec_select
2274
@item (vec_select:@var{m} @var{vec1} @var{selection})
2275
This describes an operation that selects parts of a vector.  @var{vec1} is
2276
the source vector, @var{selection} is a @code{parallel} that contains a
2277
@code{const_int} for each of the subparts of the result vector, giving the
2278
number of the source subpart that should be stored into it.
2279
 
2280
@findex vec_concat
2281
@item (vec_concat:@var{m} @var{vec1} @var{vec2})
2282
Describes a vector concat operation.  The result is a concatenation of the
2283
vectors @var{vec1} and @var{vec2}; its length is the sum of the lengths of
2284
the two inputs.
2285
 
2286
@findex vec_duplicate
2287
@item (vec_duplicate:@var{m} @var{vec})
2288
This operation converts a small vector into a larger one by duplicating the
2289
input values.  The output vector mode must have the same submodes as the
2290
input vector mode, and the number of output parts must be an integer multiple
2291
of the number of input parts.
2292
 
2293
@end table
2294
 
2295
@node Conversions
2296
@section Conversions
2297
@cindex conversions
2298
@cindex machine mode conversions
2299
 
2300
All conversions between machine modes must be represented by
2301
explicit conversion operations.  For example, an expression
2302
which is the sum of a byte and a full word cannot be written as
2303
@code{(plus:SI (reg:QI 34) (reg:SI 80))} because the @code{plus}
2304
operation requires two operands of the same machine mode.
2305
Therefore, the byte-sized operand is enclosed in a conversion
2306
operation, as in
2307
 
2308
@smallexample
2309
(plus:SI (sign_extend:SI (reg:QI 34)) (reg:SI 80))
2310
@end smallexample
2311
 
2312
The conversion operation is not a mere placeholder, because there
2313
may be more than one way of converting from a given starting mode
2314
to the desired final mode.  The conversion operation code says how
2315
to do it.
2316
 
2317
For all conversion operations, @var{x} must not be @code{VOIDmode}
2318
because the mode in which to do the conversion would not be known.
2319
The conversion must either be done at compile-time or @var{x}
2320
must be placed into a register.
2321
 
2322
@table @code
2323
@findex sign_extend
2324
@item (sign_extend:@var{m} @var{x})
2325
Represents the result of sign-extending the value @var{x}
2326
to machine mode @var{m}.  @var{m} must be a fixed-point mode
2327
and @var{x} a fixed-point value of a mode narrower than @var{m}.
2328
 
2329
@findex zero_extend
2330
@item (zero_extend:@var{m} @var{x})
2331
Represents the result of zero-extending the value @var{x}
2332
to machine mode @var{m}.  @var{m} must be a fixed-point mode
2333
and @var{x} a fixed-point value of a mode narrower than @var{m}.
2334
 
2335
@findex float_extend
2336
@item (float_extend:@var{m} @var{x})
2337
Represents the result of extending the value @var{x}
2338
to machine mode @var{m}.  @var{m} must be a floating point mode
2339
and @var{x} a floating point value of a mode narrower than @var{m}.
2340
 
2341
@findex truncate
2342
@item (truncate:@var{m} @var{x})
2343
Represents the result of truncating the value @var{x}
2344
to machine mode @var{m}.  @var{m} must be a fixed-point mode
2345
and @var{x} a fixed-point value of a mode wider than @var{m}.
2346
 
2347
@findex ss_truncate
2348
@item (ss_truncate:@var{m} @var{x})
2349
Represents the result of truncating the value @var{x}
2350
to machine mode @var{m}, using signed saturation in the case of
2351
overflow.  Both @var{m} and the mode of @var{x} must be fixed-point
2352
modes.
2353
 
2354
@findex us_truncate
2355
@item (us_truncate:@var{m} @var{x})
2356
Represents the result of truncating the value @var{x}
2357
to machine mode @var{m}, using unsigned saturation in the case of
2358
overflow.  Both @var{m} and the mode of @var{x} must be fixed-point
2359
modes.
2360
 
2361
@findex float_truncate
2362
@item (float_truncate:@var{m} @var{x})
2363
Represents the result of truncating the value @var{x}
2364
to machine mode @var{m}.  @var{m} must be a floating point mode
2365
and @var{x} a floating point value of a mode wider than @var{m}.
2366
 
2367
@findex float
2368
@item (float:@var{m} @var{x})
2369
Represents the result of converting fixed point value @var{x},
2370
regarded as signed, to floating point mode @var{m}.
2371
 
2372
@findex unsigned_float
2373
@item (unsigned_float:@var{m} @var{x})
2374
Represents the result of converting fixed point value @var{x},
2375
regarded as unsigned, to floating point mode @var{m}.
2376
 
2377
@findex fix
2378
@item (fix:@var{m} @var{x})
2379
When @var{m} is a fixed point mode, represents the result of
2380
converting floating point value @var{x} to mode @var{m}, regarded as
2381
signed.  How rounding is done is not specified, so this operation may
2382
be used validly in compiling C code only for integer-valued operands.
2383
 
2384
@findex unsigned_fix
2385
@item (unsigned_fix:@var{m} @var{x})
2386
Represents the result of converting floating point value @var{x} to
2387
fixed point mode @var{m}, regarded as unsigned.  How rounding is done
2388
is not specified.
2389
 
2390
@findex fix
2391
@item (fix:@var{m} @var{x})
2392
When @var{m} is a floating point mode, represents the result of
2393
converting floating point value @var{x} (valid for mode @var{m}) to an
2394
integer, still represented in floating point mode @var{m}, by rounding
2395
towards zero.
2396
@end table
2397
 
2398
@node RTL Declarations
2399
@section Declarations
2400
@cindex RTL declarations
2401
@cindex declarations, RTL
2402
 
2403
Declaration expression codes do not represent arithmetic operations
2404
but rather state assertions about their operands.
2405
 
2406
@table @code
2407
@findex strict_low_part
2408
@cindex @code{subreg}, in @code{strict_low_part}
2409
@item (strict_low_part (subreg:@var{m} (reg:@var{n} @var{r}) 0))
2410
This expression code is used in only one context: as the destination operand of a
2411
@code{set} expression.  In addition, the operand of this expression
2412
must be a non-paradoxical @code{subreg} expression.
2413
 
2414
The presence of @code{strict_low_part} says that the part of the
2415
register which is meaningful in mode @var{n}, but is not part of
2416
mode @var{m}, is not to be altered.  Normally, an assignment to such
2417
a subreg is allowed to have undefined effects on the rest of the
2418
register when @var{m} is less than a word.
2419
@end table
2420
 
2421
@node Side Effects
2422
@section Side Effect Expressions
2423
@cindex RTL side effect expressions
2424
 
2425
The expression codes described so far represent values, not actions.
2426
But machine instructions never produce values; they are meaningful
2427
only for their side effects on the state of the machine.  Special
2428
expression codes are used to represent side effects.
2429
 
2430
The body of an instruction is always one of these side effect codes;
2431
the codes described above, which represent values, appear only as
2432
the operands of these.
2433
 
2434
@table @code
2435
@findex set
2436
@item (set @var{lval} @var{x})
2437
Represents the action of storing the value of @var{x} into the place
2438
represented by @var{lval}.  @var{lval} must be an expression
2439
representing a place that can be stored in: @code{reg} (or @code{subreg},
2440
@code{strict_low_part} or @code{zero_extract}), @code{mem}, @code{pc},
2441
@code{parallel}, or @code{cc0}.
2442
 
2443
If @var{lval} is a @code{reg}, @code{subreg} or @code{mem}, it has a
2444
machine mode; then @var{x} must be valid for that mode.
2445
 
2446
If @var{lval} is a @code{reg} whose machine mode is less than the full
2447
width of the register, then it means that the part of the register
2448
specified by the machine mode is given the specified value and the
2449
rest of the register receives an undefined value.  Likewise, if
2450
@var{lval} is a @code{subreg} whose machine mode is narrower than
2451
the mode of the register, the rest of the register can be changed in
2452
an undefined way.
2453
 
2454
If @var{lval} is a @code{strict_low_part} of a subreg, then the part
2455
of the register specified by the machine mode of the @code{subreg} is
2456
given the value @var{x} and the rest of the register is not changed.
2457
 
2458
If @var{lval} is a @code{zero_extract}, then the referenced part of
2459
the bit-field (a memory or register reference) specified by the
2460
@code{zero_extract} is given the value @var{x} and the rest of the
2461
bit-field is not changed.  Note that @code{sign_extract} can not
2462
appear in @var{lval}.
2463
 
2464
If @var{lval} is @code{(cc0)}, it has no machine mode, and @var{x} may
2465
be either a @code{compare} expression or a value that may have any mode.
2466
The latter case represents a ``test'' instruction.  The expression
2467
@code{(set (cc0) (reg:@var{m} @var{n}))} is equivalent to
2468
@code{(set (cc0) (compare (reg:@var{m} @var{n}) (const_int 0)))}.
2469
Use the former expression to save space during the compilation.
2470
 
2471
If @var{lval} is a @code{parallel}, it is used to represent the case of
2472
a function returning a structure in multiple registers.  Each element
2473
of the @code{parallel} is an @code{expr_list} whose first operand is a
2474
@code{reg} and whose second operand is a @code{const_int} representing the
2475
offset (in bytes) into the structure at which the data in that register
2476
corresponds.  The first element may be null to indicate that the structure
2477
is also passed partly in memory.
2478
 
2479
@cindex jump instructions and @code{set}
2480
@cindex @code{if_then_else} usage
2481
If @var{lval} is @code{(pc)}, we have a jump instruction, and the
2482
possibilities for @var{x} are very limited.  It may be a
2483
@code{label_ref} expression (unconditional jump).  It may be an
2484
@code{if_then_else} (conditional jump), in which case either the
2485
second or the third operand must be @code{(pc)} (for the case which
2486
does not jump) and the other of the two must be a @code{label_ref}
2487
(for the case which does jump).  @var{x} may also be a @code{mem} or
2488
@code{(plus:SI (pc) @var{y})}, where @var{y} may be a @code{reg} or a
2489
@code{mem}; these unusual patterns are used to represent jumps through
2490
branch tables.
2491
 
2492
If @var{lval} is neither @code{(cc0)} nor @code{(pc)}, the mode of
2493
@var{lval} must not be @code{VOIDmode} and the mode of @var{x} must be
2494
valid for the mode of @var{lval}.
2495
 
2496
@findex SET_DEST
2497
@findex SET_SRC
2498
@var{lval} is customarily accessed with the @code{SET_DEST} macro and
2499
@var{x} with the @code{SET_SRC} macro.
2500
 
2501
@findex return
2502
@item (return)
2503
As the sole expression in a pattern, represents a return from the
2504
current function, on machines where this can be done with one
2505
instruction, such as VAXen.  On machines where a multi-instruction
2506
``epilogue'' must be executed in order to return from the function,
2507
returning is done by jumping to a label which precedes the epilogue, and
2508
the @code{return} expression code is never used.
2509
 
2510
Inside an @code{if_then_else} expression, represents the value to be
2511
placed in @code{pc} to return to the caller.
2512
 
2513
Note that an insn pattern of @code{(return)} is logically equivalent to
2514
@code{(set (pc) (return))}, but the latter form is never used.
2515
 
2516
@findex call
2517
@item (call @var{function} @var{nargs})
2518
Represents a function call.  @var{function} is a @code{mem} expression
2519
whose address is the address of the function to be called.
2520
@var{nargs} is an expression which can be used for two purposes: on
2521
some machines it represents the number of bytes of stack argument; on
2522
others, it represents the number of argument registers.
2523
 
2524
Each machine has a standard machine mode which @var{function} must
2525
have.  The machine description defines macro @code{FUNCTION_MODE} to
2526
expand into the requisite mode name.  The purpose of this mode is to
2527
specify what kind of addressing is allowed, on machines where the
2528
allowed kinds of addressing depend on the machine mode being
2529
addressed.
2530
 
2531
@findex clobber
2532
@item (clobber @var{x})
2533
Represents the storing or possible storing of an unpredictable,
2534
undescribed value into @var{x}, which must be a @code{reg},
2535
@code{scratch}, @code{parallel} or @code{mem} expression.
2536
 
2537
One place this is used is in string instructions that store standard
2538
values into particular hard registers.  It may not be worth the
2539
trouble to describe the values that are stored, but it is essential to
2540
inform the compiler that the registers will be altered, lest it
2541
attempt to keep data in them across the string instruction.
2542
 
2543
If @var{x} is @code{(mem:BLK (const_int 0))} or
2544
@code{(mem:BLK (scratch))}, it means that all memory
2545
locations must be presumed clobbered.  If @var{x} is a @code{parallel},
2546
it has the same meaning as a @code{parallel} in a @code{set} expression.
2547
 
2548
Note that the machine description classifies certain hard registers as
2549
``call-clobbered''.  All function call instructions are assumed by
2550
default to clobber these registers, so there is no need to use
2551
@code{clobber} expressions to indicate this fact.  Also, each function
2552
call is assumed to have the potential to alter any memory location,
2553
unless the function is declared @code{const}.
2554
 
2555
If the last group of expressions in a @code{parallel} are each a
2556
@code{clobber} expression whose arguments are @code{reg} or
2557
@code{match_scratch} (@pxref{RTL Template}) expressions, the combiner
2558
phase can add the appropriate @code{clobber} expressions to an insn it
2559
has constructed when doing so will cause a pattern to be matched.
2560
 
2561
This feature can be used, for example, on a machine that whose multiply
2562
and add instructions don't use an MQ register but which has an
2563
add-accumulate instruction that does clobber the MQ register.  Similarly,
2564
a combined instruction might require a temporary register while the
2565
constituent instructions might not.
2566
 
2567
When a @code{clobber} expression for a register appears inside a
2568
@code{parallel} with other side effects, the register allocator
2569
guarantees that the register is unoccupied both before and after that
2570
insn.  However, the reload phase may allocate a register used for one of
2571
the inputs unless the @samp{&} constraint is specified for the selected
2572
alternative (@pxref{Modifiers}).  You can clobber either a specific hard
2573
register, a pseudo register, or a @code{scratch} expression; in the
2574
latter two cases, GCC will allocate a hard register that is available
2575
there for use as a temporary.
2576
 
2577
For instructions that require a temporary register, you should use
2578
@code{scratch} instead of a pseudo-register because this will allow the
2579
combiner phase to add the @code{clobber} when required.  You do this by
2580
coding (@code{clobber} (@code{match_scratch} @dots{})).  If you do
2581
clobber a pseudo register, use one which appears nowhere else---generate
2582
a new one each time.  Otherwise, you may confuse CSE@.
2583
 
2584
There is one other known use for clobbering a pseudo register in a
2585
@code{parallel}: when one of the input operands of the insn is also
2586
clobbered by the insn.  In this case, using the same pseudo register in
2587
the clobber and elsewhere in the insn produces the expected results.
2588
 
2589
@findex use
2590
@item (use @var{x})
2591
Represents the use of the value of @var{x}.  It indicates that the
2592
value in @var{x} at this point in the program is needed, even though
2593
it may not be apparent why this is so.  Therefore, the compiler will
2594
not attempt to delete previous instructions whose only effect is to
2595
store a value in @var{x}.  @var{x} must be a @code{reg} expression.
2596
 
2597
In some situations, it may be tempting to add a @code{use} of a
2598
register in a @code{parallel} to describe a situation where the value
2599
of a special register will modify the behavior of the instruction.
2600
An hypothetical example might be a pattern for an addition that can
2601
either wrap around or use saturating addition depending on the value
2602
of a special control register:
2603
 
2604
@smallexample
2605
(parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
2606
                                       (reg:SI 4)] 0))
2607
           (use (reg:SI 1))])
2608
@end smallexample
2609
 
2610
@noindent
2611
 
2612
This will not work, several of the optimizers only look at expressions
2613
locally; it is very likely that if you have multiple insns with
2614
identical inputs to the @code{unspec}, they will be optimized away even
2615
if register 1 changes in between.
2616
 
2617
This means that @code{use} can @emph{only} be used to describe
2618
that the register is live.  You should think twice before adding
2619
@code{use} statements, more often you will want to use @code{unspec}
2620
instead.  The @code{use} RTX is most commonly useful to describe that
2621
a fixed register is implicitly used in an insn.  It is also safe to use
2622
in patterns where the compiler knows for other reasons that the result
2623
of the whole pattern is variable, such as @samp{movmem@var{m}} or
2624
@samp{call} patterns.
2625
 
2626
During the reload phase, an insn that has a @code{use} as pattern
2627
can carry a reg_equal note.  These @code{use} insns will be deleted
2628
before the reload phase exits.
2629
 
2630
During the delayed branch scheduling phase, @var{x} may be an insn.
2631
This indicates that @var{x} previously was located at this place in the
2632
code and its data dependencies need to be taken into account.  These
2633
@code{use} insns will be deleted before the delayed branch scheduling
2634
phase exits.
2635
 
2636
@findex parallel
2637
@item (parallel [@var{x0} @var{x1} @dots{}])
2638
Represents several side effects performed in parallel.  The square
2639
brackets stand for a vector; the operand of @code{parallel} is a
2640
vector of expressions.  @var{x0}, @var{x1} and so on are individual
2641
side effect expressions---expressions of code @code{set}, @code{call},
2642
@code{return}, @code{clobber} or @code{use}.
2643
 
2644
``In parallel'' means that first all the values used in the individual
2645
side-effects are computed, and second all the actual side-effects are
2646
performed.  For example,
2647
 
2648
@smallexample
2649
(parallel [(set (reg:SI 1) (mem:SI (reg:SI 1)))
2650
           (set (mem:SI (reg:SI 1)) (reg:SI 1))])
2651
@end smallexample
2652
 
2653
@noindent
2654
says unambiguously that the values of hard register 1 and the memory
2655
location addressed by it are interchanged.  In both places where
2656
@code{(reg:SI 1)} appears as a memory address it refers to the value
2657
in register 1 @emph{before} the execution of the insn.
2658
 
2659
It follows that it is @emph{incorrect} to use @code{parallel} and
2660
expect the result of one @code{set} to be available for the next one.
2661
For example, people sometimes attempt to represent a jump-if-zero
2662
instruction this way:
2663
 
2664
@smallexample
2665
(parallel [(set (cc0) (reg:SI 34))
2666
           (set (pc) (if_then_else
2667
                        (eq (cc0) (const_int 0))
2668
                        (label_ref @dots{})
2669
                        (pc)))])
2670
@end smallexample
2671
 
2672
@noindent
2673
But this is incorrect, because it says that the jump condition depends
2674
on the condition code value @emph{before} this instruction, not on the
2675
new value that is set by this instruction.
2676
 
2677
@cindex peephole optimization, RTL representation
2678
Peephole optimization, which takes place together with final assembly
2679
code output, can produce insns whose patterns consist of a @code{parallel}
2680
whose elements are the operands needed to output the resulting
2681
assembler code---often @code{reg}, @code{mem} or constant expressions.
2682
This would not be well-formed RTL at any other stage in compilation,
2683
but it is ok then because no further optimization remains to be done.
2684
However, the definition of the macro @code{NOTICE_UPDATE_CC}, if
2685
any, must deal with such insns if you define any peephole optimizations.
2686
 
2687
@findex cond_exec
2688
@item (cond_exec [@var{cond} @var{expr}])
2689
Represents a conditionally executed expression.  The @var{expr} is
2690
executed only if the @var{cond} is nonzero.  The @var{cond} expression
2691
must not have side-effects, but the @var{expr} may very well have
2692
side-effects.
2693
 
2694
@findex sequence
2695
@item (sequence [@var{insns} @dots{}])
2696
Represents a sequence of insns.  Each of the @var{insns} that appears
2697
in the vector is suitable for appearing in the chain of insns, so it
2698
must be an @code{insn}, @code{jump_insn}, @code{call_insn},
2699
@code{code_label}, @code{barrier} or @code{note}.
2700
 
2701
A @code{sequence} RTX is never placed in an actual insn during RTL
2702
generation.  It represents the sequence of insns that result from a
2703
@code{define_expand} @emph{before} those insns are passed to
2704
@code{emit_insn} to insert them in the chain of insns.  When actually
2705
inserted, the individual sub-insns are separated out and the
2706
@code{sequence} is forgotten.
2707
 
2708
After delay-slot scheduling is completed, an insn and all the insns that
2709
reside in its delay slots are grouped together into a @code{sequence}.
2710
The insn requiring the delay slot is the first insn in the vector;
2711
subsequent insns are to be placed in the delay slot.
2712
 
2713
@code{INSN_ANNULLED_BRANCH_P} is set on an insn in a delay slot to
2714
indicate that a branch insn should be used that will conditionally annul
2715
the effect of the insns in the delay slots.  In such a case,
2716
@code{INSN_FROM_TARGET_P} indicates that the insn is from the target of
2717
the branch and should be executed only if the branch is taken; otherwise
2718
the insn should be executed only if the branch is not taken.
2719
@xref{Delay Slots}.
2720
@end table
2721
 
2722
These expression codes appear in place of a side effect, as the body of
2723
an insn, though strictly speaking they do not always describe side
2724
effects as such:
2725
 
2726
@table @code
2727
@findex asm_input
2728
@item (asm_input @var{s})
2729
Represents literal assembler code as described by the string @var{s}.
2730
 
2731
@findex unspec
2732
@findex unspec_volatile
2733
@item (unspec [@var{operands} @dots{}] @var{index})
2734
@itemx (unspec_volatile [@var{operands} @dots{}] @var{index})
2735
Represents a machine-specific operation on @var{operands}.  @var{index}
2736
selects between multiple machine-specific operations.
2737
@code{unspec_volatile} is used for volatile operations and operations
2738
that may trap; @code{unspec} is used for other operations.
2739
 
2740
These codes may appear inside a @code{pattern} of an
2741
insn, inside a @code{parallel}, or inside an expression.
2742
 
2743
@findex addr_vec
2744
@item (addr_vec:@var{m} [@var{lr0} @var{lr1} @dots{}])
2745
Represents a table of jump addresses.  The vector elements @var{lr0},
2746
etc., are @code{label_ref} expressions.  The mode @var{m} specifies
2747
how much space is given to each address; normally @var{m} would be
2748
@code{Pmode}.
2749
 
2750
@findex addr_diff_vec
2751
@item (addr_diff_vec:@var{m} @var{base} [@var{lr0} @var{lr1} @dots{}] @var{min} @var{max} @var{flags})
2752
Represents a table of jump addresses expressed as offsets from
2753
@var{base}.  The vector elements @var{lr0}, etc., are @code{label_ref}
2754
expressions and so is @var{base}.  The mode @var{m} specifies how much
2755
space is given to each address-difference.  @var{min} and @var{max}
2756
are set up by branch shortening and hold a label with a minimum and a
2757
maximum address, respectively.  @var{flags} indicates the relative
2758
position of @var{base}, @var{min} and @var{max} to the containing insn
2759
and of @var{min} and @var{max} to @var{base}.  See rtl.def for details.
2760
 
2761
@findex prefetch
2762
@item (prefetch:@var{m} @var{addr} @var{rw} @var{locality})
2763
Represents prefetch of memory at address @var{addr}.
2764
Operand @var{rw} is 1 if the prefetch is for data to be written, 0 otherwise;
2765
targets that do not support write prefetches should treat this as a normal
2766
prefetch.
2767
Operand @var{locality} specifies the amount of temporal locality; 0 if there
2768
is none or 1, 2, or 3 for increasing levels of temporal locality;
2769
targets that do not support locality hints should ignore this.
2770
 
2771
This insn is used to minimize cache-miss latency by moving data into a
2772
cache before it is accessed.  It should use only non-faulting data prefetch
2773
instructions.
2774
@end table
2775
 
2776
@node Incdec
2777
@section Embedded Side-Effects on Addresses
2778
@cindex RTL preincrement
2779
@cindex RTL postincrement
2780
@cindex RTL predecrement
2781
@cindex RTL postdecrement
2782
 
2783
Six special side-effect expression codes appear as memory addresses.
2784
 
2785
@table @code
2786
@findex pre_dec
2787
@item (pre_dec:@var{m} @var{x})
2788
Represents the side effect of decrementing @var{x} by a standard
2789
amount and represents also the value that @var{x} has after being
2790
decremented.  @var{x} must be a @code{reg} or @code{mem}, but most
2791
machines allow only a @code{reg}.  @var{m} must be the machine mode
2792
for pointers on the machine in use.  The amount @var{x} is decremented
2793
by is the length in bytes of the machine mode of the containing memory
2794
reference of which this expression serves as the address.  Here is an
2795
example of its use:
2796
 
2797
@smallexample
2798
(mem:DF (pre_dec:SI (reg:SI 39)))
2799
@end smallexample
2800
 
2801
@noindent
2802
This says to decrement pseudo register 39 by the length of a @code{DFmode}
2803
value and use the result to address a @code{DFmode} value.
2804
 
2805
@findex pre_inc
2806
@item (pre_inc:@var{m} @var{x})
2807
Similar, but specifies incrementing @var{x} instead of decrementing it.
2808
 
2809
@findex post_dec
2810
@item (post_dec:@var{m} @var{x})
2811
Represents the same side effect as @code{pre_dec} but a different
2812
value.  The value represented here is the value @var{x} has @i{before}
2813
being decremented.
2814
 
2815
@findex post_inc
2816
@item (post_inc:@var{m} @var{x})
2817
Similar, but specifies incrementing @var{x} instead of decrementing it.
2818
 
2819
@findex post_modify
2820
@item (post_modify:@var{m} @var{x} @var{y})
2821
 
2822
Represents the side effect of setting @var{x} to @var{y} and
2823
represents @var{x} before @var{x} is modified.  @var{x} must be a
2824
@code{reg} or @code{mem}, but most machines allow only a @code{reg}.
2825
@var{m} must be the machine mode for pointers on the machine in use.
2826
 
2827
The expression @var{y} must be one of three forms:
2828
@table @code
2829
@code{(plus:@var{m} @var{x} @var{z})},
2830
@code{(minus:@var{m} @var{x} @var{z})}, or
2831
@code{(plus:@var{m} @var{x} @var{i})},
2832
@end table
2833
where @var{z} is an index register and @var{i} is a constant.
2834
 
2835
Here is an example of its use:
2836
 
2837
@smallexample
2838
(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
2839
                                          (reg:SI 48))))
2840
@end smallexample
2841
 
2842
This says to modify pseudo register 42 by adding the contents of pseudo
2843
register 48 to it, after the use of what ever 42 points to.
2844
 
2845
@findex pre_modify
2846
@item (pre_modify:@var{m} @var{x} @var{expr})
2847
Similar except side effects happen before the use.
2848
@end table
2849
 
2850
These embedded side effect expressions must be used with care.  Instruction
2851
patterns may not use them.  Until the @samp{flow} pass of the compiler,
2852
they may occur only to represent pushes onto the stack.  The @samp{flow}
2853
pass finds cases where registers are incremented or decremented in one
2854
instruction and used as an address shortly before or after; these cases are
2855
then transformed to use pre- or post-increment or -decrement.
2856
 
2857
If a register used as the operand of these expressions is used in
2858
another address in an insn, the original value of the register is used.
2859
Uses of the register outside of an address are not permitted within the
2860
same insn as a use in an embedded side effect expression because such
2861
insns behave differently on different machines and hence must be treated
2862
as ambiguous and disallowed.
2863
 
2864
An instruction that can be represented with an embedded side effect
2865
could also be represented using @code{parallel} containing an additional
2866
@code{set} to describe how the address register is altered.  This is not
2867
done because machines that allow these operations at all typically
2868
allow them wherever a memory address is called for.  Describing them as
2869
additional parallel stores would require doubling the number of entries
2870
in the machine description.
2871
 
2872
@node Assembler
2873
@section Assembler Instructions as Expressions
2874
@cindex assembler instructions in RTL
2875
 
2876
@cindex @code{asm_operands}, usage
2877
The RTX code @code{asm_operands} represents a value produced by a
2878
user-specified assembler instruction.  It is used to represent
2879
an @code{asm} statement with arguments.  An @code{asm} statement with
2880
a single output operand, like this:
2881
 
2882
@smallexample
2883
asm ("foo %1,%2,%0" : "=a" (outputvar) : "g" (x + y), "di" (*z));
2884
@end smallexample
2885
 
2886
@noindent
2887
is represented using a single @code{asm_operands} RTX which represents
2888
the value that is stored in @code{outputvar}:
2889
 
2890
@smallexample
2891
(set @var{rtx-for-outputvar}
2892
     (asm_operands "foo %1,%2,%0" "a" 0
2893
                   [@var{rtx-for-addition-result} @var{rtx-for-*z}]
2894
                   [(asm_input:@var{m1} "g")
2895
                    (asm_input:@var{m2} "di")]))
2896
@end smallexample
2897
 
2898
@noindent
2899
Here the operands of the @code{asm_operands} RTX are the assembler
2900
template string, the output-operand's constraint, the index-number of the
2901
output operand among the output operands specified, a vector of input
2902
operand RTX's, and a vector of input-operand modes and constraints.  The
2903
mode @var{m1} is the mode of the sum @code{x+y}; @var{m2} is that of
2904
@code{*z}.
2905
 
2906
When an @code{asm} statement has multiple output values, its insn has
2907
several such @code{set} RTX's inside of a @code{parallel}.  Each @code{set}
2908
contains a @code{asm_operands}; all of these share the same assembler
2909
template and vectors, but each contains the constraint for the respective
2910
output operand.  They are also distinguished by the output-operand index
2911
number, which is 0, 1, @dots{} for successive output operands.
2912
 
2913
@node Insns
2914
@section Insns
2915
@cindex insns
2916
 
2917
The RTL representation of the code for a function is a doubly-linked
2918
chain of objects called @dfn{insns}.  Insns are expressions with
2919
special codes that are used for no other purpose.  Some insns are
2920
actual instructions; others represent dispatch tables for @code{switch}
2921
statements; others represent labels to jump to or various sorts of
2922
declarative information.
2923
 
2924
In addition to its own specific data, each insn must have a unique
2925
id-number that distinguishes it from all other insns in the current
2926
function (after delayed branch scheduling, copies of an insn with the
2927
same id-number may be present in multiple places in a function, but
2928
these copies will always be identical and will only appear inside a
2929
@code{sequence}), and chain pointers to the preceding and following
2930
insns.  These three fields occupy the same position in every insn,
2931
independent of the expression code of the insn.  They could be accessed
2932
with @code{XEXP} and @code{XINT}, but instead three special macros are
2933
always used:
2934
 
2935
@table @code
2936
@findex INSN_UID
2937
@item INSN_UID (@var{i})
2938
Accesses the unique id of insn @var{i}.
2939
 
2940
@findex PREV_INSN
2941
@item PREV_INSN (@var{i})
2942
Accesses the chain pointer to the insn preceding @var{i}.
2943
If @var{i} is the first insn, this is a null pointer.
2944
 
2945
@findex NEXT_INSN
2946
@item NEXT_INSN (@var{i})
2947
Accesses the chain pointer to the insn following @var{i}.
2948
If @var{i} is the last insn, this is a null pointer.
2949
@end table
2950
 
2951
@findex get_insns
2952
@findex get_last_insn
2953
The first insn in the chain is obtained by calling @code{get_insns}; the
2954
last insn is the result of calling @code{get_last_insn}.  Within the
2955
chain delimited by these insns, the @code{NEXT_INSN} and
2956
@code{PREV_INSN} pointers must always correspond: if @var{insn} is not
2957
the first insn,
2958
 
2959
@smallexample
2960
NEXT_INSN (PREV_INSN (@var{insn})) == @var{insn}
2961
@end smallexample
2962
 
2963
@noindent
2964
is always true and if @var{insn} is not the last insn,
2965
 
2966
@smallexample
2967
PREV_INSN (NEXT_INSN (@var{insn})) == @var{insn}
2968
@end smallexample
2969
 
2970
@noindent
2971
is always true.
2972
 
2973
After delay slot scheduling, some of the insns in the chain might be
2974
@code{sequence} expressions, which contain a vector of insns.  The value
2975
of @code{NEXT_INSN} in all but the last of these insns is the next insn
2976
in the vector; the value of @code{NEXT_INSN} of the last insn in the vector
2977
is the same as the value of @code{NEXT_INSN} for the @code{sequence} in
2978
which it is contained.  Similar rules apply for @code{PREV_INSN}.
2979
 
2980
This means that the above invariants are not necessarily true for insns
2981
inside @code{sequence} expressions.  Specifically, if @var{insn} is the
2982
first insn in a @code{sequence}, @code{NEXT_INSN (PREV_INSN (@var{insn}))}
2983
is the insn containing the @code{sequence} expression, as is the value
2984
of @code{PREV_INSN (NEXT_INSN (@var{insn}))} if @var{insn} is the last
2985
insn in the @code{sequence} expression.  You can use these expressions
2986
to find the containing @code{sequence} expression.
2987
 
2988
Every insn has one of the following six expression codes:
2989
 
2990
@table @code
2991
@findex insn
2992
@item insn
2993
The expression code @code{insn} is used for instructions that do not jump
2994
and do not do function calls.  @code{sequence} expressions are always
2995
contained in insns with code @code{insn} even if one of those insns
2996
should jump or do function calls.
2997
 
2998
Insns with code @code{insn} have four additional fields beyond the three
2999
mandatory ones listed above.  These four are described in a table below.
3000
 
3001
@findex jump_insn
3002
@item jump_insn
3003
The expression code @code{jump_insn} is used for instructions that may
3004
jump (or, more generally, may contain @code{label_ref} expressions).  If
3005
there is an instruction to return from the current function, it is
3006
recorded as a @code{jump_insn}.
3007
 
3008
@findex JUMP_LABEL
3009
@code{jump_insn} insns have the same extra fields as @code{insn} insns,
3010
accessed in the same way and in addition contain a field
3011
@code{JUMP_LABEL} which is defined once jump optimization has completed.
3012
 
3013
For simple conditional and unconditional jumps, this field contains
3014
the @code{code_label} to which this insn will (possibly conditionally)
3015
branch.  In a more complex jump, @code{JUMP_LABEL} records one of the
3016
labels that the insn refers to; the only way to find the others is to
3017
scan the entire body of the insn.  In an @code{addr_vec},
3018
@code{JUMP_LABEL} is @code{NULL_RTX}.
3019
 
3020
Return insns count as jumps, but since they do not refer to any
3021
labels, their @code{JUMP_LABEL} is @code{NULL_RTX}.
3022
 
3023
@findex call_insn
3024
@item call_insn
3025
The expression code @code{call_insn} is used for instructions that may do
3026
function calls.  It is important to distinguish these instructions because
3027
they imply that certain registers and memory locations may be altered
3028
unpredictably.
3029
 
3030
@findex CALL_INSN_FUNCTION_USAGE
3031
@code{call_insn} insns have the same extra fields as @code{insn} insns,
3032
accessed in the same way and in addition contain a field
3033
@code{CALL_INSN_FUNCTION_USAGE}, which contains a list (chain of
3034
@code{expr_list} expressions) containing @code{use} and @code{clobber}
3035
expressions that denote hard registers and @code{MEM}s used or
3036
clobbered by the called function.
3037
 
3038
A @code{MEM} generally points to a stack slots in which arguments passed
3039
to the libcall by reference (@pxref{Register Arguments,
3040
TARGET_PASS_BY_REFERENCE}) are stored.  If the argument is
3041
caller-copied (@pxref{Register Arguments, TARGET_CALLEE_COPIES}),
3042
the stack slot will be mentioned in @code{CLOBBER} and @code{USE}
3043
entries; if it's callee-copied, only a @code{USE} will appear, and the
3044
@code{MEM} may point to addresses that are not stack slots.
3045
 
3046
@code{CLOBBER}ed registers in this list augment registers specified in
3047
@code{CALL_USED_REGISTERS} (@pxref{Register Basics}).
3048
 
3049
@findex code_label
3050
@findex CODE_LABEL_NUMBER
3051
@item code_label
3052
A @code{code_label} insn represents a label that a jump insn can jump
3053
to.  It contains two special fields of data in addition to the three
3054
standard ones.  @code{CODE_LABEL_NUMBER} is used to hold the @dfn{label
3055
number}, a number that identifies this label uniquely among all the
3056
labels in the compilation (not just in the current function).
3057
Ultimately, the label is represented in the assembler output as an
3058
assembler label, usually of the form @samp{L@var{n}} where @var{n} is
3059
the label number.
3060
 
3061
When a @code{code_label} appears in an RTL expression, it normally
3062
appears within a @code{label_ref} which represents the address of
3063
the label, as a number.
3064
 
3065
Besides as a @code{code_label}, a label can also be represented as a
3066
@code{note} of type @code{NOTE_INSN_DELETED_LABEL}.
3067
 
3068
@findex LABEL_NUSES
3069
The field @code{LABEL_NUSES} is only defined once the jump optimization
3070
phase is completed.  It contains the number of times this label is
3071
referenced in the current function.
3072
 
3073
@findex LABEL_KIND
3074
@findex SET_LABEL_KIND
3075
@findex LABEL_ALT_ENTRY_P
3076
@cindex alternate entry points
3077
The field @code{LABEL_KIND} differentiates four different types of
3078
labels: @code{LABEL_NORMAL}, @code{LABEL_STATIC_ENTRY},
3079
@code{LABEL_GLOBAL_ENTRY}, and @code{LABEL_WEAK_ENTRY}.  The only labels
3080
that do not have type @code{LABEL_NORMAL} are @dfn{alternate entry
3081
points} to the current function.  These may be static (visible only in
3082
the containing translation unit), global (exposed to all translation
3083
units), or weak (global, but can be overridden by another symbol with the
3084
same name).
3085
 
3086
Much of the compiler treats all four kinds of label identically.  Some
3087
of it needs to know whether or not a label is an alternate entry point;
3088
for this purpose, the macro @code{LABEL_ALT_ENTRY_P} is provided.  It is
3089
equivalent to testing whether @samp{LABEL_KIND (label) == LABEL_NORMAL}.
3090
The only place that cares about the distinction between static, global,
3091
and weak alternate entry points, besides the front-end code that creates
3092
them, is the function @code{output_alternate_entry_point}, in
3093
@file{final.c}.
3094
 
3095
To set the kind of a label, use the @code{SET_LABEL_KIND} macro.
3096
 
3097
@findex barrier
3098
@item barrier
3099
Barriers are placed in the instruction stream when control cannot flow
3100
past them.  They are placed after unconditional jump instructions to
3101
indicate that the jumps are unconditional and after calls to
3102
@code{volatile} functions, which do not return (e.g., @code{exit}).
3103
They contain no information beyond the three standard fields.
3104
 
3105
@findex note
3106
@findex NOTE_LINE_NUMBER
3107
@findex NOTE_SOURCE_FILE
3108
@item note
3109
@code{note} insns are used to represent additional debugging and
3110
declarative information.  They contain two nonstandard fields, an
3111
integer which is accessed with the macro @code{NOTE_LINE_NUMBER} and a
3112
string accessed with @code{NOTE_SOURCE_FILE}.
3113
 
3114
If @code{NOTE_LINE_NUMBER} is positive, the note represents the
3115
position of a source line and @code{NOTE_SOURCE_FILE} is the source file name
3116
that the line came from.  These notes control generation of line
3117
number data in the assembler output.
3118
 
3119
Otherwise, @code{NOTE_LINE_NUMBER} is not really a line number but a
3120
code with one of the following values (and @code{NOTE_SOURCE_FILE}
3121
must contain a null pointer):
3122
 
3123
@table @code
3124
@findex NOTE_INSN_DELETED
3125
@item NOTE_INSN_DELETED
3126
Such a note is completely ignorable.  Some passes of the compiler
3127
delete insns by altering them into notes of this kind.
3128
 
3129
@findex NOTE_INSN_DELETED_LABEL
3130
@item NOTE_INSN_DELETED_LABEL
3131
This marks what used to be a @code{code_label}, but was not used for other
3132
purposes than taking its address and was transformed to mark that no
3133
code jumps to it.
3134
 
3135
@findex NOTE_INSN_BLOCK_BEG
3136
@findex NOTE_INSN_BLOCK_END
3137
@item NOTE_INSN_BLOCK_BEG
3138
@itemx NOTE_INSN_BLOCK_END
3139
These types of notes indicate the position of the beginning and end
3140
of a level of scoping of variable names.  They control the output
3141
of debugging information.
3142
 
3143
@findex NOTE_INSN_EH_REGION_BEG
3144
@findex NOTE_INSN_EH_REGION_END
3145
@item NOTE_INSN_EH_REGION_BEG
3146
@itemx NOTE_INSN_EH_REGION_END
3147
These types of notes indicate the position of the beginning and end of a
3148
level of scoping for exception handling.  @code{NOTE_BLOCK_NUMBER}
3149
identifies which @code{CODE_LABEL} or @code{note} of type
3150
@code{NOTE_INSN_DELETED_LABEL} is associated with the given region.
3151
 
3152
@findex NOTE_INSN_LOOP_BEG
3153
@findex NOTE_INSN_LOOP_END
3154
@item NOTE_INSN_LOOP_BEG
3155
@itemx NOTE_INSN_LOOP_END
3156
These types of notes indicate the position of the beginning and end
3157
of a @code{while} or @code{for} loop.  They enable the loop optimizer
3158
to find loops quickly.
3159
 
3160
@findex NOTE_INSN_LOOP_CONT
3161
@item NOTE_INSN_LOOP_CONT
3162
Appears at the place in a loop that @code{continue} statements jump to.
3163
 
3164
@findex NOTE_INSN_LOOP_VTOP
3165
@item NOTE_INSN_LOOP_VTOP
3166
This note indicates the place in a loop where the exit test begins for
3167
those loops in which the exit test has been duplicated.  This position
3168
becomes another virtual start of the loop when considering loop
3169
invariants.
3170
 
3171
@findex NOTE_INSN_FUNCTION_BEG
3172
@item NOTE_INSN_FUNCTION_BEG
3173
Appears at the start of the function body, after the function
3174
prologue.
3175
 
3176
@findex NOTE_INSN_FUNCTION_END
3177
@item NOTE_INSN_FUNCTION_END
3178
Appears near the end of the function body, just before the label that
3179
@code{return} statements jump to (on machine where a single instruction
3180
does not suffice for returning).  This note may be deleted by jump
3181
optimization.
3182
 
3183
@end table
3184
 
3185
These codes are printed symbolically when they appear in debugging dumps.
3186
@end table
3187
 
3188
@cindex @code{TImode}, in @code{insn}
3189
@cindex @code{HImode}, in @code{insn}
3190
@cindex @code{QImode}, in @code{insn}
3191
The machine mode of an insn is normally @code{VOIDmode}, but some
3192
phases use the mode for various purposes.
3193
 
3194
The common subexpression elimination pass sets the mode of an insn to
3195
@code{QImode} when it is the first insn in a block that has already
3196
been processed.
3197
 
3198
The second Haifa scheduling pass, for targets that can multiple issue,
3199
sets the mode of an insn to @code{TImode} when it is believed that the
3200
instruction begins an issue group.  That is, when the instruction
3201
cannot issue simultaneously with the previous.  This may be relied on
3202
by later passes, in particular machine-dependent reorg.
3203
 
3204
Here is a table of the extra fields of @code{insn}, @code{jump_insn}
3205
and @code{call_insn} insns:
3206
 
3207
@table @code
3208
@findex PATTERN
3209
@item PATTERN (@var{i})
3210
An expression for the side effect performed by this insn.  This must be
3211
one of the following codes: @code{set}, @code{call}, @code{use},
3212
@code{clobber}, @code{return}, @code{asm_input}, @code{asm_output},
3213
@code{addr_vec}, @code{addr_diff_vec}, @code{trap_if}, @code{unspec},
3214
@code{unspec_volatile}, @code{parallel}, @code{cond_exec}, or @code{sequence}.  If it is a @code{parallel},
3215
each element of the @code{parallel} must be one these codes, except that
3216
@code{parallel} expressions cannot be nested and @code{addr_vec} and
3217
@code{addr_diff_vec} are not permitted inside a @code{parallel} expression.
3218
 
3219
@findex INSN_CODE
3220
@item INSN_CODE (@var{i})
3221
An integer that says which pattern in the machine description matches
3222
this insn, or @minus{}1 if the matching has not yet been attempted.
3223
 
3224
Such matching is never attempted and this field remains @minus{}1 on an insn
3225
whose pattern consists of a single @code{use}, @code{clobber},
3226
@code{asm_input}, @code{addr_vec} or @code{addr_diff_vec} expression.
3227
 
3228
@findex asm_noperands
3229
Matching is also never attempted on insns that result from an @code{asm}
3230
statement.  These contain at least one @code{asm_operands} expression.
3231
The function @code{asm_noperands} returns a non-negative value for
3232
such insns.
3233
 
3234
In the debugging output, this field is printed as a number followed by
3235
a symbolic representation that locates the pattern in the @file{md}
3236
file as some small positive or negative offset from a named pattern.
3237
 
3238
@findex LOG_LINKS
3239
@item LOG_LINKS (@var{i})
3240
A list (chain of @code{insn_list} expressions) giving information about
3241
dependencies between instructions within a basic block.  Neither a jump
3242
nor a label may come between the related insns.
3243
 
3244
@findex REG_NOTES
3245
@item REG_NOTES (@var{i})
3246
A list (chain of @code{expr_list} and @code{insn_list} expressions)
3247
giving miscellaneous information about the insn.  It is often
3248
information pertaining to the registers used in this insn.
3249
@end table
3250
 
3251
The @code{LOG_LINKS} field of an insn is a chain of @code{insn_list}
3252
expressions.  Each of these has two operands: the first is an insn,
3253
and the second is another @code{insn_list} expression (the next one in
3254
the chain).  The last @code{insn_list} in the chain has a null pointer
3255
as second operand.  The significant thing about the chain is which
3256
insns appear in it (as first operands of @code{insn_list}
3257
expressions).  Their order is not significant.
3258
 
3259
This list is originally set up by the flow analysis pass; it is a null
3260
pointer until then.  Flow only adds links for those data dependencies
3261
which can be used for instruction combination.  For each insn, the flow
3262
analysis pass adds a link to insns which store into registers values
3263
that are used for the first time in this insn.  The instruction
3264
scheduling pass adds extra links so that every dependence will be
3265
represented.  Links represent data dependencies, antidependencies and
3266
output dependencies; the machine mode of the link distinguishes these
3267
three types: antidependencies have mode @code{REG_DEP_ANTI}, output
3268
dependencies have mode @code{REG_DEP_OUTPUT}, and data dependencies have
3269
mode @code{VOIDmode}.
3270
 
3271
The @code{REG_NOTES} field of an insn is a chain similar to the
3272
@code{LOG_LINKS} field but it includes @code{expr_list} expressions in
3273
addition to @code{insn_list} expressions.  There are several kinds of
3274
register notes, which are distinguished by the machine mode, which in a
3275
register note is really understood as being an @code{enum reg_note}.
3276
The first operand @var{op} of the note is data whose meaning depends on
3277
the kind of note.
3278
 
3279
@findex REG_NOTE_KIND
3280
@findex PUT_REG_NOTE_KIND
3281
The macro @code{REG_NOTE_KIND (@var{x})} returns the kind of
3282
register note.  Its counterpart, the macro @code{PUT_REG_NOTE_KIND
3283
(@var{x}, @var{newkind})} sets the register note type of @var{x} to be
3284
@var{newkind}.
3285
 
3286
Register notes are of three classes: They may say something about an
3287
input to an insn, they may say something about an output of an insn, or
3288
they may create a linkage between two insns.  There are also a set
3289
of values that are only used in @code{LOG_LINKS}.
3290
 
3291
These register notes annotate inputs to an insn:
3292
 
3293
@table @code
3294
@findex REG_DEAD
3295
@item REG_DEAD
3296
The value in @var{op} dies in this insn; that is to say, altering the
3297
value immediately after this insn would not affect the future behavior
3298
of the program.
3299
 
3300
It does not follow that the register @var{op} has no useful value after
3301
this insn since @var{op} is not necessarily modified by this insn.
3302
Rather, no subsequent instruction uses the contents of @var{op}.
3303
 
3304
@findex REG_UNUSED
3305
@item REG_UNUSED
3306
The register @var{op} being set by this insn will not be used in a
3307
subsequent insn.  This differs from a @code{REG_DEAD} note, which
3308
indicates that the value in an input will not be used subsequently.
3309
These two notes are independent; both may be present for the same
3310
register.
3311
 
3312
@findex REG_INC
3313
@item REG_INC
3314
The register @var{op} is incremented (or decremented; at this level
3315
there is no distinction) by an embedded side effect inside this insn.
3316
This means it appears in a @code{post_inc}, @code{pre_inc},
3317
@code{post_dec} or @code{pre_dec} expression.
3318
 
3319
@findex REG_NONNEG
3320
@item REG_NONNEG
3321
The register @var{op} is known to have a nonnegative value when this
3322
insn is reached.  This is used so that decrement and branch until zero
3323
instructions, such as the m68k dbra, can be matched.
3324
 
3325
The @code{REG_NONNEG} note is added to insns only if the machine
3326
description has a @samp{decrement_and_branch_until_zero} pattern.
3327
 
3328
@findex REG_NO_CONFLICT
3329
@item REG_NO_CONFLICT
3330
This insn does not cause a conflict between @var{op} and the item
3331
being set by this insn even though it might appear that it does.
3332
In other words, if the destination register and @var{op} could
3333
otherwise be assigned the same register, this insn does not
3334
prevent that assignment.
3335
 
3336
Insns with this note are usually part of a block that begins with a
3337
@code{clobber} insn specifying a multi-word pseudo register (which will
3338
be the output of the block), a group of insns that each set one word of
3339
the value and have the @code{REG_NO_CONFLICT} note attached, and a final
3340
insn that copies the output to itself with an attached @code{REG_EQUAL}
3341
note giving the expression being computed.  This block is encapsulated
3342
with @code{REG_LIBCALL} and @code{REG_RETVAL} notes on the first and
3343
last insns, respectively.
3344
 
3345
@findex REG_LABEL
3346
@item REG_LABEL
3347
This insn uses @var{op}, a @code{code_label} or a @code{note} of type
3348
@code{NOTE_INSN_DELETED_LABEL}, but is not a
3349
@code{jump_insn}, or it is a @code{jump_insn} that required the label to
3350
be held in a register.  The presence of this note allows jump
3351
optimization to be aware that @var{op} is, in fact, being used, and flow
3352
optimization to build an accurate flow graph.
3353
 
3354
@findex REG_CROSSING_JUMP
3355
@item REG_CROSSING_JUMP
3356
This insn is an branching instruction (either an unconditional jump or
3357
an indirect jump) which crosses between hot and cold sections, which
3358
could potentially be very far apart in the executable.  The presence
3359
of this note indicates to other optimizations that this this branching
3360
instruction should not be ``collapsed'' into a simpler branching
3361
construct.  It is used when the optimization to partition basic blocks
3362
into hot and cold sections is turned on.
3363
 
3364
@findex REG_SETJMP
3365
@item REG_SETJMP
3366
Appears attached to each @code{CALL_INSN} to @code{setjmp} or a
3367
related function.
3368
@end table
3369
 
3370
The following notes describe attributes of outputs of an insn:
3371
 
3372
@table @code
3373
@findex REG_EQUIV
3374
@findex REG_EQUAL
3375
@item REG_EQUIV
3376
@itemx REG_EQUAL
3377
This note is only valid on an insn that sets only one register and
3378
indicates that that register will be equal to @var{op} at run time; the
3379
scope of this equivalence differs between the two types of notes.  The
3380
value which the insn explicitly copies into the register may look
3381
different from @var{op}, but they will be equal at run time.  If the
3382
output of the single @code{set} is a @code{strict_low_part} expression,
3383
the note refers to the register that is contained in @code{SUBREG_REG}
3384
of the @code{subreg} expression.
3385
 
3386
For @code{REG_EQUIV}, the register is equivalent to @var{op} throughout
3387
the entire function, and could validly be replaced in all its
3388
occurrences by @var{op}.  (``Validly'' here refers to the data flow of
3389
the program; simple replacement may make some insns invalid.)  For
3390
example, when a constant is loaded into a register that is never
3391
assigned any other value, this kind of note is used.
3392
 
3393
When a parameter is copied into a pseudo-register at entry to a function,
3394
a note of this kind records that the register is equivalent to the stack
3395
slot where the parameter was passed.  Although in this case the register
3396
may be set by other insns, it is still valid to replace the register
3397
by the stack slot throughout the function.
3398
 
3399
A @code{REG_EQUIV} note is also used on an instruction which copies a
3400
register parameter into a pseudo-register at entry to a function, if
3401
there is a stack slot where that parameter could be stored.  Although
3402
other insns may set the pseudo-register, it is valid for the compiler to
3403
replace the pseudo-register by stack slot throughout the function,
3404
provided the compiler ensures that the stack slot is properly
3405
initialized by making the replacement in the initial copy instruction as
3406
well.  This is used on machines for which the calling convention
3407
allocates stack space for register parameters.  See
3408
@code{REG_PARM_STACK_SPACE} in @ref{Stack Arguments}.
3409
 
3410
In the case of @code{REG_EQUAL}, the register that is set by this insn
3411
will be equal to @var{op} at run time at the end of this insn but not
3412
necessarily elsewhere in the function.  In this case, @var{op}
3413
is typically an arithmetic expression.  For example, when a sequence of
3414
insns such as a library call is used to perform an arithmetic operation,
3415
this kind of note is attached to the insn that produces or copies the
3416
final value.
3417
 
3418
These two notes are used in different ways by the compiler passes.
3419
@code{REG_EQUAL} is used by passes prior to register allocation (such as
3420
common subexpression elimination and loop optimization) to tell them how
3421
to think of that value.  @code{REG_EQUIV} notes are used by register
3422
allocation to indicate that there is an available substitute expression
3423
(either a constant or a @code{mem} expression for the location of a
3424
parameter on the stack) that may be used in place of a register if
3425
insufficient registers are available.
3426
 
3427
Except for stack homes for parameters, which are indicated by a
3428
@code{REG_EQUIV} note and are not useful to the early optimization
3429
passes and pseudo registers that are equivalent to a memory location
3430
throughout their entire life, which is not detected until later in
3431
the compilation, all equivalences are initially indicated by an attached
3432
@code{REG_EQUAL} note.  In the early stages of register allocation, a
3433
@code{REG_EQUAL} note is changed into a @code{REG_EQUIV} note if
3434
@var{op} is a constant and the insn represents the only set of its
3435
destination register.
3436
 
3437
Thus, compiler passes prior to register allocation need only check for
3438
@code{REG_EQUAL} notes and passes subsequent to register allocation
3439
need only check for @code{REG_EQUIV} notes.
3440
@end table
3441
 
3442
These notes describe linkages between insns.  They occur in pairs: one
3443
insn has one of a pair of notes that points to a second insn, which has
3444
the inverse note pointing back to the first insn.
3445
 
3446
@table @code
3447
@findex REG_RETVAL
3448
@item REG_RETVAL
3449
This insn copies the value of a multi-insn sequence (for example, a
3450
library call), and @var{op} is the first insn of the sequence (for a
3451
library call, the first insn that was generated to set up the arguments
3452
for the library call).
3453
 
3454
Loop optimization uses this note to treat such a sequence as a single
3455
operation for code motion purposes and flow analysis uses this note to
3456
delete such sequences whose results are dead.
3457
 
3458
A @code{REG_EQUAL} note will also usually be attached to this insn to
3459
provide the expression being computed by the sequence.
3460
 
3461
These notes will be deleted after reload, since they are no longer
3462
accurate or useful.
3463
 
3464
@findex REG_LIBCALL
3465
@item REG_LIBCALL
3466
This is the inverse of @code{REG_RETVAL}: it is placed on the first
3467
insn of a multi-insn sequence, and it points to the last one.
3468
 
3469
These notes are deleted after reload, since they are no longer useful or
3470
accurate.
3471
 
3472
@findex REG_CC_SETTER
3473
@findex REG_CC_USER
3474
@item REG_CC_SETTER
3475
@itemx REG_CC_USER
3476
On machines that use @code{cc0}, the insns which set and use @code{cc0}
3477
set and use @code{cc0} are adjacent.  However, when branch delay slot
3478
filling is done, this may no longer be true.  In this case a
3479
@code{REG_CC_USER} note will be placed on the insn setting @code{cc0} to
3480
point to the insn using @code{cc0} and a @code{REG_CC_SETTER} note will
3481
be placed on the insn using @code{cc0} to point to the insn setting
3482
@code{cc0}.
3483
@end table
3484
 
3485
These values are only used in the @code{LOG_LINKS} field, and indicate
3486
the type of dependency that each link represents.  Links which indicate
3487
a data dependence (a read after write dependence) do not use any code,
3488
they simply have mode @code{VOIDmode}, and are printed without any
3489
descriptive text.
3490
 
3491
@table @code
3492
@findex REG_DEP_ANTI
3493
@item REG_DEP_ANTI
3494
This indicates an anti dependence (a write after read dependence).
3495
 
3496
@findex REG_DEP_OUTPUT
3497
@item REG_DEP_OUTPUT
3498
This indicates an output dependence (a write after write dependence).
3499
@end table
3500
 
3501
These notes describe information gathered from gcov profile data.  They
3502
are stored in the @code{REG_NOTES} field of an insn as an
3503
@code{expr_list}.
3504
 
3505
@table @code
3506
@findex REG_BR_PROB
3507
@item REG_BR_PROB
3508
This is used to specify the ratio of branches to non-branches of a
3509
branch insn according to the profile data.  The value is stored as a
3510
value between 0 and REG_BR_PROB_BASE; larger values indicate a higher
3511
probability that the branch will be taken.
3512
 
3513
@findex REG_BR_PRED
3514
@item REG_BR_PRED
3515
These notes are found in JUMP insns after delayed branch scheduling
3516
has taken place.  They indicate both the direction and the likelihood
3517
of the JUMP@.  The format is a bitmask of ATTR_FLAG_* values.
3518
 
3519
@findex REG_FRAME_RELATED_EXPR
3520
@item REG_FRAME_RELATED_EXPR
3521
This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression
3522
is used in place of the actual insn pattern.  This is done in cases where
3523
the pattern is either complex or misleading.
3524
@end table
3525
 
3526
For convenience, the machine mode in an @code{insn_list} or
3527
@code{expr_list} is printed using these symbolic codes in debugging dumps.
3528
 
3529
@findex insn_list
3530
@findex expr_list
3531
The only difference between the expression codes @code{insn_list} and
3532
@code{expr_list} is that the first operand of an @code{insn_list} is
3533
assumed to be an insn and is printed in debugging dumps as the insn's
3534
unique id; the first operand of an @code{expr_list} is printed in the
3535
ordinary way as an expression.
3536
 
3537
@node Calls
3538
@section RTL Representation of Function-Call Insns
3539
@cindex calling functions in RTL
3540
@cindex RTL function-call insns
3541
@cindex function-call insns
3542
 
3543
Insns that call subroutines have the RTL expression code @code{call_insn}.
3544
These insns must satisfy special rules, and their bodies must use a special
3545
RTL expression code, @code{call}.
3546
 
3547
@cindex @code{call} usage
3548
A @code{call} expression has two operands, as follows:
3549
 
3550
@smallexample
3551
(call (mem:@var{fm} @var{addr}) @var{nbytes})
3552
@end smallexample
3553
 
3554
@noindent
3555
Here @var{nbytes} is an operand that represents the number of bytes of
3556
argument data being passed to the subroutine, @var{fm} is a machine mode
3557
(which must equal as the definition of the @code{FUNCTION_MODE} macro in
3558
the machine description) and @var{addr} represents the address of the
3559
subroutine.
3560
 
3561
For a subroutine that returns no value, the @code{call} expression as
3562
shown above is the entire body of the insn, except that the insn might
3563
also contain @code{use} or @code{clobber} expressions.
3564
 
3565
@cindex @code{BLKmode}, and function return values
3566
For a subroutine that returns a value whose mode is not @code{BLKmode},
3567
the value is returned in a hard register.  If this register's number is
3568
@var{r}, then the body of the call insn looks like this:
3569
 
3570
@smallexample
3571
(set (reg:@var{m} @var{r})
3572
     (call (mem:@var{fm} @var{addr}) @var{nbytes}))
3573
@end smallexample
3574
 
3575
@noindent
3576
This RTL expression makes it clear (to the optimizer passes) that the
3577
appropriate register receives a useful value in this insn.
3578
 
3579
When a subroutine returns a @code{BLKmode} value, it is handled by
3580
passing to the subroutine the address of a place to store the value.
3581
So the call insn itself does not ``return'' any value, and it has the
3582
same RTL form as a call that returns nothing.
3583
 
3584
On some machines, the call instruction itself clobbers some register,
3585
for example to contain the return address.  @code{call_insn} insns
3586
on these machines should have a body which is a @code{parallel}
3587
that contains both the @code{call} expression and @code{clobber}
3588
expressions that indicate which registers are destroyed.  Similarly,
3589
if the call instruction requires some register other than the stack
3590
pointer that is not explicitly mentioned in its RTL, a @code{use}
3591
subexpression should mention that register.
3592
 
3593
Functions that are called are assumed to modify all registers listed in
3594
the configuration macro @code{CALL_USED_REGISTERS} (@pxref{Register
3595
Basics}) and, with the exception of @code{const} functions and library
3596
calls, to modify all of memory.
3597
 
3598
Insns containing just @code{use} expressions directly precede the
3599
@code{call_insn} insn to indicate which registers contain inputs to the
3600
function.  Similarly, if registers other than those in
3601
@code{CALL_USED_REGISTERS} are clobbered by the called function, insns
3602
containing a single @code{clobber} follow immediately after the call to
3603
indicate which registers.
3604
 
3605
@node Sharing
3606
@section Structure Sharing Assumptions
3607
@cindex sharing of RTL components
3608
@cindex RTL structure sharing assumptions
3609
 
3610
The compiler assumes that certain kinds of RTL expressions are unique;
3611
there do not exist two distinct objects representing the same value.
3612
In other cases, it makes an opposite assumption: that no RTL expression
3613
object of a certain kind appears in more than one place in the
3614
containing structure.
3615
 
3616
These assumptions refer to a single function; except for the RTL
3617
objects that describe global variables and external functions,
3618
and a few standard objects such as small integer constants,
3619
no RTL objects are common to two functions.
3620
 
3621
@itemize @bullet
3622
@cindex @code{reg}, RTL sharing
3623
@item
3624
Each pseudo-register has only a single @code{reg} object to represent it,
3625
and therefore only a single machine mode.
3626
 
3627
@cindex symbolic label
3628
@cindex @code{symbol_ref}, RTL sharing
3629
@item
3630
For any symbolic label, there is only one @code{symbol_ref} object
3631
referring to it.
3632
 
3633
@cindex @code{const_int}, RTL sharing
3634
@item
3635
All @code{const_int} expressions with equal values are shared.
3636
 
3637
@cindex @code{pc}, RTL sharing
3638
@item
3639
There is only one @code{pc} expression.
3640
 
3641
@cindex @code{cc0}, RTL sharing
3642
@item
3643
There is only one @code{cc0} expression.
3644
 
3645
@cindex @code{const_double}, RTL sharing
3646
@item
3647
There is only one @code{const_double} expression with value 0 for
3648
each floating point mode.  Likewise for values 1 and 2.
3649
 
3650
@cindex @code{const_vector}, RTL sharing
3651
@item
3652
There is only one @code{const_vector} expression with value 0 for
3653
each vector mode, be it an integer or a double constant vector.
3654
 
3655
@cindex @code{label_ref}, RTL sharing
3656
@cindex @code{scratch}, RTL sharing
3657
@item
3658
No @code{label_ref} or @code{scratch} appears in more than one place in
3659
the RTL structure; in other words, it is safe to do a tree-walk of all
3660
the insns in the function and assume that each time a @code{label_ref}
3661
or @code{scratch} is seen it is distinct from all others that are seen.
3662
 
3663
@cindex @code{mem}, RTL sharing
3664
@item
3665
Only one @code{mem} object is normally created for each static
3666
variable or stack slot, so these objects are frequently shared in all
3667
the places they appear.  However, separate but equal objects for these
3668
variables are occasionally made.
3669
 
3670
@cindex @code{asm_operands}, RTL sharing
3671
@item
3672
When a single @code{asm} statement has multiple output operands, a
3673
distinct @code{asm_operands} expression is made for each output operand.
3674
However, these all share the vector which contains the sequence of input
3675
operands.  This sharing is used later on to test whether two
3676
@code{asm_operands} expressions come from the same statement, so all
3677
optimizations must carefully preserve the sharing if they copy the
3678
vector at all.
3679
 
3680
@item
3681
No RTL object appears in more than one place in the RTL structure
3682
except as described above.  Many passes of the compiler rely on this
3683
by assuming that they can modify RTL objects in place without unwanted
3684
side-effects on other insns.
3685
 
3686
@findex unshare_all_rtl
3687
@item
3688
During initial RTL generation, shared structure is freely introduced.
3689
After all the RTL for a function has been generated, all shared
3690
structure is copied by @code{unshare_all_rtl} in @file{emit-rtl.c},
3691
after which the above rules are guaranteed to be followed.
3692
 
3693
@findex copy_rtx_if_shared
3694
@item
3695
During the combiner pass, shared structure within an insn can exist
3696
temporarily.  However, the shared structure is copied before the
3697
combiner is finished with the insn.  This is done by calling
3698
@code{copy_rtx_if_shared}, which is a subroutine of
3699
@code{unshare_all_rtl}.
3700
@end itemize
3701
 
3702
@node Reading RTL
3703
@section Reading RTL
3704
 
3705
To read an RTL object from a file, call @code{read_rtx}.  It takes one
3706
argument, a stdio stream, and returns a single RTL object.  This routine
3707
is defined in @file{read-rtl.c}.  It is not available in the compiler
3708
itself, only the various programs that generate the compiler back end
3709
from the machine description.
3710
 
3711
People frequently have the idea of using RTL stored as text in a file as
3712
an interface between a language front end and the bulk of GCC@.  This
3713
idea is not feasible.
3714
 
3715
GCC was designed to use RTL internally only.  Correct RTL for a given
3716
program is very dependent on the particular target machine.  And the RTL
3717
does not contain all the information about the program.
3718
 
3719
The proper way to interface GCC to a new language front end is with
3720
the ``tree'' data structure, described in the files @file{tree.h} and
3721
@file{tree.def}.  The documentation for this structure (@pxref{Trees})
3722
is incomplete.

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.