]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
1 | .. |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | .. index:: insns | |
7 | ||
8 | .. _insns: | |
9 | ||
10 | Insns | |
11 | ***** | |
12 | ||
13 | The RTL representation of the code for a function is a doubly-linked | |
14 | chain of objects called :dfn:`insns`. Insns are expressions with | |
15 | special codes that are used for no other purpose. Some insns are | |
16 | actual instructions; others represent dispatch tables for ``switch`` | |
17 | statements; others represent labels to jump to or various sorts of | |
18 | declarative information. | |
19 | ||
20 | In addition to its own specific data, each insn must have a unique | |
21 | id-number that distinguishes it from all other insns in the current | |
22 | function (after delayed branch scheduling, copies of an insn with the | |
23 | same id-number may be present in multiple places in a function, but | |
24 | these copies will always be identical and will only appear inside a | |
25 | ``sequence``), and chain pointers to the preceding and following | |
26 | insns. These three fields occupy the same position in every insn, | |
27 | independent of the expression code of the insn. They could be accessed | |
28 | with ``XEXP`` and ``XINT``, but instead three special macros are | |
29 | always used: | |
30 | ||
31 | .. index:: INSN_UID | |
32 | ||
33 | :samp:`INSN_UID ({i})` | |
34 | Accesses the unique id of insn :samp:`{i}`. | |
35 | ||
36 | .. index:: PREV_INSN | |
37 | ||
38 | :samp:`PREV_INSN ({i})` | |
39 | Accesses the chain pointer to the insn preceding :samp:`{i}`. | |
40 | If :samp:`{i}` is the first insn, this is a null pointer. | |
41 | ||
42 | .. index:: NEXT_INSN | |
43 | ||
44 | :samp:`NEXT_INSN ({i})` | |
45 | Accesses the chain pointer to the insn following :samp:`{i}`. | |
46 | If :samp:`{i}` is the last insn, this is a null pointer. | |
47 | ||
48 | .. index:: get_insns, get_last_insn | |
49 | ||
50 | The first insn in the chain is obtained by calling ``get_insns`` ; the | |
51 | last insn is the result of calling ``get_last_insn``. Within the | |
52 | chain delimited by these insns, the ``NEXT_INSN`` and | |
53 | ``PREV_INSN`` pointers must always correspond: if :samp:`{insn}` is not | |
54 | the first insn, | |
55 | ||
56 | .. code-block:: c++ | |
57 | ||
58 | NEXT_INSN (PREV_INSN (insn)) == insn | |
59 | ||
60 | is always true and if :samp:`{insn}` is not the last insn, | |
61 | ||
62 | .. code-block:: c++ | |
63 | ||
64 | PREV_INSN (NEXT_INSN (insn)) == insn | |
65 | ||
66 | is always true. | |
67 | ||
68 | After delay slot scheduling, some of the insns in the chain might be | |
69 | ``sequence`` expressions, which contain a vector of insns. The value | |
70 | of ``NEXT_INSN`` in all but the last of these insns is the next insn | |
71 | in the vector; the value of ``NEXT_INSN`` of the last insn in the vector | |
72 | is the same as the value of ``NEXT_INSN`` for the ``sequence`` in | |
73 | which it is contained. Similar rules apply for ``PREV_INSN``. | |
74 | ||
75 | This means that the above invariants are not necessarily true for insns | |
76 | inside ``sequence`` expressions. Specifically, if :samp:`{insn}` is the | |
77 | first insn in a ``sequence``, ``NEXT_INSN (PREV_INSN (insn))`` | |
78 | is the insn containing the ``sequence`` expression, as is the value | |
79 | of ``PREV_INSN (NEXT_INSN (insn))`` if :samp:`{insn}` is the last | |
80 | insn in the ``sequence`` expression. You can use these expressions | |
81 | to find the containing ``sequence`` expression. | |
82 | ||
83 | Every insn has one of the following expression codes: | |
84 | ||
85 | .. index:: insn | |
86 | ||
87 | ``insn`` | |
88 | The expression code ``insn`` is used for instructions that do not jump | |
89 | and do not do function calls. ``sequence`` expressions are always | |
90 | contained in insns with code ``insn`` even if one of those insns | |
91 | should jump or do function calls. | |
92 | ||
93 | Insns with code ``insn`` have four additional fields beyond the three | |
94 | mandatory ones listed above. These four are described in a table below. | |
95 | ||
96 | .. index:: jump_insn | |
97 | ||
98 | ``jump_insn`` | |
99 | The expression code ``jump_insn`` is used for instructions that may | |
100 | jump (or, more generally, may contain ``label_ref`` expressions to | |
101 | which ``pc`` can be set in that instruction). If there is an | |
102 | instruction to return from the current function, it is recorded as a | |
103 | ``jump_insn``. | |
104 | ||
105 | .. index:: JUMP_LABEL | |
106 | ||
107 | ``jump_insn`` insns have the same extra fields as ``insn`` insns, | |
108 | accessed in the same way and in addition contain a field | |
109 | ``JUMP_LABEL`` which is defined once jump optimization has completed. | |
110 | ||
111 | For simple conditional and unconditional jumps, this field contains | |
112 | the ``code_label`` to which this insn will (possibly conditionally) | |
113 | branch. In a more complex jump, ``JUMP_LABEL`` records one of the | |
114 | labels that the insn refers to; other jump target labels are recorded | |
115 | as ``REG_LABEL_TARGET`` notes. The exception is ``addr_vec`` | |
116 | and ``addr_diff_vec``, where ``JUMP_LABEL`` is ``NULL_RTX`` | |
117 | and the only way to find the labels is to scan the entire body of the | |
118 | insn. | |
119 | ||
120 | Return insns count as jumps, but their ``JUMP_LABEL`` is ``RETURN`` | |
121 | or ``SIMPLE_RETURN``. | |
122 | ||
123 | .. index:: call_insn | |
124 | ||
125 | ``call_insn`` | |
126 | The expression code ``call_insn`` is used for instructions that may do | |
127 | function calls. It is important to distinguish these instructions because | |
128 | they imply that certain registers and memory locations may be altered | |
129 | unpredictably. | |
130 | ||
131 | .. index:: CALL_INSN_FUNCTION_USAGE | |
132 | ||
133 | ``call_insn`` insns have the same extra fields as ``insn`` insns, | |
134 | accessed in the same way and in addition contain a field | |
135 | ``CALL_INSN_FUNCTION_USAGE``, which contains a list (chain of | |
136 | ``expr_list`` expressions) containing ``use``, ``clobber`` and | |
137 | sometimes ``set`` expressions that denote hard registers and | |
138 | ``mem`` s used or clobbered by the called function. | |
139 | ||
140 | A ``mem`` generally points to a stack slot in which arguments passed | |
141 | to the libcall by reference (see :ref:`register-arguments`) are stored. If the argument is | |
142 | caller-copied (see :ref:`register-arguments`), | |
143 | the stack slot will be mentioned in ``clobber`` and ``use`` | |
144 | entries; if it's callee-copied, only a ``use`` will appear, and the | |
145 | ``mem`` may point to addresses that are not stack slots. | |
146 | ||
147 | Registers occurring inside a ``clobber`` in this list augment | |
148 | registers specified in ``CALL_USED_REGISTERS`` (see :ref:`register-basics`). | |
149 | ||
150 | If the list contains a ``set`` involving two registers, it indicates | |
151 | that the function returns one of its arguments. Such a ``set`` may | |
152 | look like a no-op if the same register holds the argument and the return | |
153 | value. | |
154 | ||
155 | .. index:: code_label, CODE_LABEL_NUMBER | |
156 | ||
157 | ``code_label`` | |
158 | A ``code_label`` insn represents a label that a jump insn can jump | |
159 | to. It contains two special fields of data in addition to the three | |
160 | standard ones. ``CODE_LABEL_NUMBER`` is used to hold the :dfn:`label | |
161 | number`, a number that identifies this label uniquely among all the | |
162 | labels in the compilation (not just in the current function). | |
163 | Ultimately, the label is represented in the assembler output as an | |
164 | assembler label, usually of the form :samp:`L{n}` where :samp:`{n}` is | |
165 | the label number. | |
166 | ||
167 | When a ``code_label`` appears in an RTL expression, it normally | |
168 | appears within a ``label_ref`` which represents the address of | |
169 | the label, as a number. | |
170 | ||
171 | Besides as a ``code_label``, a label can also be represented as a | |
172 | ``note`` of type ``NOTE_INSN_DELETED_LABEL``. | |
173 | ||
174 | .. index:: LABEL_NUSES | |
175 | ||
176 | The field ``LABEL_NUSES`` is only defined once the jump optimization | |
177 | phase is completed. It contains the number of times this label is | |
178 | referenced in the current function. | |
179 | ||
180 | .. index:: LABEL_KIND, SET_LABEL_KIND, LABEL_ALT_ENTRY_P, alternate entry points | |
181 | ||
182 | The field ``LABEL_KIND`` differentiates four different types of | |
183 | labels: ``LABEL_NORMAL``, ``LABEL_STATIC_ENTRY``, | |
184 | ``LABEL_GLOBAL_ENTRY``, and ``LABEL_WEAK_ENTRY``. The only labels | |
185 | that do not have type ``LABEL_NORMAL`` are :dfn:`alternate entry | |
186 | points` to the current function. These may be static (visible only in | |
187 | the containing translation unit), global (exposed to all translation | |
188 | units), or weak (global, but can be overridden by another symbol with the | |
189 | same name). | |
190 | ||
191 | Much of the compiler treats all four kinds of label identically. Some | |
192 | of it needs to know whether or not a label is an alternate entry point; | |
193 | for this purpose, the macro ``LABEL_ALT_ENTRY_P`` is provided. It is | |
194 | equivalent to testing whether :samp:`LABEL_KIND (label) == LABEL_NORMAL`. | |
195 | The only place that cares about the distinction between static, global, | |
196 | and weak alternate entry points, besides the front-end code that creates | |
197 | them, is the function ``output_alternate_entry_point``, in | |
198 | :samp:`final.cc`. | |
199 | ||
200 | To set the kind of a label, use the ``SET_LABEL_KIND`` macro. | |
201 | ||
202 | .. index:: jump_table_data | |
203 | ||
204 | ``jump_table_data`` | |
205 | A ``jump_table_data`` insn is a placeholder for the jump-table data | |
206 | of a ``casesi`` or ``tablejump`` insn. They are placed after | |
207 | a ``tablejump_p`` insn. A ``jump_table_data`` insn is not part o | |
208 | a basic blockm but it is associated with the basic block that ends with | |
209 | the ``tablejump_p`` insn. The ``PATTERN`` of a ``jump_table_data`` | |
210 | is always either an ``addr_vec`` or an ``addr_diff_vec``, and a | |
211 | ``jump_table_data`` insn is always preceded by a ``code_label``. | |
212 | The ``tablejump_p`` insn refers to that ``code_label`` via its | |
213 | ``JUMP_LABEL``. | |
214 | ||
215 | .. index:: barrier | |
216 | ||
217 | ``barrier`` | |
218 | Barriers are placed in the instruction stream when control cannot flow | |
219 | past them. They are placed after unconditional jump instructions to | |
220 | indicate that the jumps are unconditional and after calls to | |
221 | ``volatile`` functions, which do not return (e.g., ``exit``). | |
222 | They contain no information beyond the three standard fields. | |
223 | ||
224 | .. index:: note, NOTE_LINE_NUMBER, NOTE_SOURCE_FILE | |
225 | ||
226 | ``note`` | |
227 | ``note`` insns are used to represent additional debugging and | |
228 | declarative information. They contain two nonstandard fields, an | |
229 | integer which is accessed with the macro ``NOTE_LINE_NUMBER`` and a | |
230 | string accessed with ``NOTE_SOURCE_FILE``. | |
231 | ||
232 | If ``NOTE_LINE_NUMBER`` is positive, the note represents the | |
233 | position of a source line and ``NOTE_SOURCE_FILE`` is the source file name | |
234 | that the line came from. These notes control generation of line | |
235 | number data in the assembler output. | |
236 | ||
237 | Otherwise, ``NOTE_LINE_NUMBER`` is not really a line number but a | |
238 | code with one of the following values (and ``NOTE_SOURCE_FILE`` | |
239 | must contain a null pointer): | |
240 | ||
241 | .. index:: NOTE_INSN_DELETED | |
242 | ||
243 | .. envvar:: NOTE_INSN_DELETED | |
244 | ||
245 | Such a note is completely ignorable. Some passes of the compiler | |
246 | delete insns by altering them into notes of this kind. | |
247 | ||
248 | .. envvar:: NOTE_INSN_DELETED_LABEL | |
249 | ||
250 | This marks what used to be a ``code_label``, but was not used for other | |
251 | purposes than taking its address and was transformed to mark that no | |
252 | code jumps to it. | |
253 | ||
254 | .. envvar:: NOTE_INSN_BLOCK_BEG | |
255 | ||
256 | These types of notes indicate the position of the beginning and end | |
257 | of a level of scoping of variable names. They control the output | |
258 | of debugging information. | |
259 | ||
260 | .. envvar:: NOTE_INSN_EH_REGION_BEG | |
261 | ||
262 | These types of notes indicate the position of the beginning and end of a | |
263 | level of scoping for exception handling. ``NOTE_EH_HANDLER`` | |
264 | identifies which region is associated with these notes. | |
265 | ||
266 | .. envvar:: NOTE_INSN_FUNCTION_BEG | |
267 | ||
268 | Appears at the start of the function body, after the function | |
269 | prologue. | |
270 | ||
271 | .. envvar:: NOTE_INSN_VAR_LOCATION | |
272 | ||
273 | This note is used to generate variable location debugging information. | |
274 | It indicates that the user variable in its ``VAR_LOCATION`` operand | |
275 | is at the location given in the RTL expression, or holds a value that | |
276 | can be computed by evaluating the RTL expression from that static | |
277 | point in the program up to the next such note for the same user | |
278 | variable. | |
279 | ||
280 | .. envvar:: NOTE_INSN_BEGIN_STMT | |
281 | ||
282 | This note is used to generate ``is_stmt`` markers in line number | |
283 | debugging information. It indicates the beginning of a user | |
284 | statement. | |
285 | ||
286 | .. envvar:: NOTE_INSN_INLINE_ENTRY | |
287 | ||
288 | This note is used to generate ``entry_pc`` for inlined subroutines in | |
289 | debugging information. It indicates an inspection point at which all | |
290 | arguments for the inlined function have been bound, and before its first | |
291 | statement. | |
292 | ||
293 | These codes are printed symbolically when they appear in debugging dumps. | |
294 | ||
295 | .. index:: debug_insn, INSN_VAR_LOCATION | |
296 | ||
297 | ``debug_insn`` | |
298 | The expression code ``debug_insn`` is used for pseudo-instructions | |
299 | that hold debugging information for variable tracking at assignments | |
300 | (see :option:`-fvar-tracking-assignments` option). They are the RTL | |
301 | representation of ``GIMPLE_DEBUG`` statements | |
302 | (:ref:`GIMPLE_DEBUG`), with a ``VAR_LOCATION`` operand that | |
303 | binds a user variable tree to an RTL representation of the | |
304 | ``value`` in the corresponding statement. A ``DEBUG_EXPR`` in | |
305 | it stands for the value bound to the corresponding | |
306 | ``DEBUG_EXPR_DECL``. | |
307 | ||
308 | ``GIMPLE_DEBUG_BEGIN_STMT`` and ``GIMPLE_DEBUG_INLINE_ENTRY`` are | |
309 | expanded to RTL as a ``DEBUG_INSN`` with a ``DEBUG_MARKER`` | |
310 | ``PATTERN`` ; the difference is the RTL mode: the former's | |
311 | ``DEBUG_MARKER`` is ``VOIDmode``, whereas the latter is | |
312 | ``BLKmode`` ; information about the inlined function can be taken from | |
313 | the lexical block encoded in the ``INSN_LOCATION``. These | |
314 | ``DEBUG_INSN`` s, that do not carry ``VAR_LOCATION`` information, | |
315 | just ``DEBUG_MARKER`` s, can be detected by testing | |
316 | ``DEBUG_MARKER_INSN_P``, whereas those that do can be recognized as | |
317 | ``DEBUG_BIND_INSN_P``. | |
318 | ||
319 | Throughout optimization passes, ``DEBUG_INSN`` s are not reordered | |
320 | with respect to each other, particularly during scheduling. Binding | |
321 | information is kept in pseudo-instruction form, so that, unlike notes, | |
322 | it gets the same treatment and adjustments that regular instructions | |
323 | would. It is the variable tracking pass that turns these | |
324 | pseudo-instructions into ``NOTE_INSN_VAR_LOCATION``, | |
325 | ``NOTE_INSN_BEGIN_STMT`` and ``NOTE_INSN_INLINE_ENTRY`` notes, | |
326 | analyzing control flow, value equivalences and changes to registers and | |
327 | memory referenced in value expressions, propagating the values of debug | |
328 | temporaries and determining expressions that can be used to compute the | |
329 | value of each user variable at as many points (ranges, actually) in the | |
330 | program as possible. | |
331 | ||
332 | Unlike ``NOTE_INSN_VAR_LOCATION``, the value expression in an | |
333 | ``INSN_VAR_LOCATION`` denotes a value at that specific point in the | |
334 | program, rather than an expression that can be evaluated at any later | |
335 | point before an overriding ``VAR_LOCATION`` is encountered. E.g., | |
336 | if a user variable is bound to a ``REG`` and then a subsequent insn | |
337 | modifies the ``REG``, the note location would keep mapping the user | |
338 | variable to the register across the insn, whereas the insn location | |
339 | would keep the variable bound to the value, so that the variable | |
340 | tracking pass would emit another location note for the variable at the | |
341 | point in which the register is modified. | |
342 | ||
343 | .. index:: TImode, in insn, HImode, in insn, QImode, in insn | |
344 | ||
345 | The machine mode of an insn is normally ``VOIDmode``, but some | |
346 | phases use the mode for various purposes. | |
347 | ||
348 | The common subexpression elimination pass sets the mode of an insn to | |
349 | ``QImode`` when it is the first insn in a block that has already | |
350 | been processed. | |
351 | ||
352 | The second Haifa scheduling pass, for targets that can multiple issue, | |
353 | sets the mode of an insn to ``TImode`` when it is believed that the | |
354 | instruction begins an issue group. That is, when the instruction | |
355 | cannot issue simultaneously with the previous. This may be relied on | |
356 | by later passes, in particular machine-dependent reorg. | |
357 | ||
358 | Here is a table of the extra fields of ``insn``, ``jump_insn`` | |
359 | and ``call_insn`` insns: | |
360 | ||
361 | .. index:: PATTERN | |
362 | ||
363 | :samp:`PATTERN ({i})` | |
364 | An expression for the side effect performed by this insn. This must | |
365 | be one of the following codes: ``set``, ``call``, ``use``, | |
366 | ``clobber``, ``return``, ``simple_return``, ``asm_input``, | |
367 | ``asm_output``, ``addr_vec``, ``addr_diff_vec``, | |
368 | ``trap_if``, ``unspec``, ``unspec_volatile``, | |
369 | ``parallel``, ``cond_exec``, or ``sequence``. If it is a | |
370 | ``parallel``, each element of the ``parallel`` must be one these | |
371 | codes, except that ``parallel`` expressions cannot be nested and | |
372 | ``addr_vec`` and ``addr_diff_vec`` are not permitted inside a | |
373 | ``parallel`` expression. | |
374 | ||
375 | .. index:: INSN_CODE | |
376 | ||
377 | :samp:`INSN_CODE ({i})` | |
378 | An integer that says which pattern in the machine description matches | |
379 | this insn, or -1 if the matching has not yet been attempted. | |
380 | ||
381 | Such matching is never attempted and this field remains -1 on an insn | |
382 | whose pattern consists of a single ``use``, ``clobber``, | |
383 | ``asm_input``, ``addr_vec`` or ``addr_diff_vec`` expression. | |
384 | ||
385 | .. index:: asm_noperands | |
386 | ||
387 | Matching is also never attempted on insns that result from an ``asm`` | |
388 | statement. These contain at least one ``asm_operands`` expression. | |
389 | The function ``asm_noperands`` returns a non-negative value for | |
390 | such insns. | |
391 | ||
392 | In the debugging output, this field is printed as a number followed by | |
393 | a symbolic representation that locates the pattern in the :samp:`md` | |
394 | file as some small positive or negative offset from a named pattern. | |
395 | ||
396 | .. index:: REG_NOTES | |
397 | ||
398 | :samp:`REG_NOTES ({i})` | |
399 | A list (chain of ``expr_list``, ``insn_list`` and ``int_list`` | |
400 | expressions) giving miscellaneous information about the insn. It is often | |
401 | information pertaining to the registers used in this insn. | |
402 | ||
403 | The ``REG_NOTES`` field of an insn is a chain that includes | |
404 | ``expr_list`` and ``int_list`` expressions as well as ``insn_list`` | |
405 | expressions. There are several | |
406 | kinds of register notes, which are distinguished by the machine mode, which | |
407 | in a register note is really understood as being an ``enum reg_note``. | |
408 | The first operand :samp:`{op}` of the note is data whose meaning depends on | |
409 | the kind of note. | |
410 | ||
411 | .. index:: REG_NOTE_KIND, PUT_REG_NOTE_KIND | |
412 | ||
413 | The macro ``REG_NOTE_KIND (x)`` returns the kind of | |
414 | register note. Its counterpart, the macro ``PUT_REG_NOTE_KIND | |
415 | (x, newkind)`` sets the register note type of :samp:`{x}` to be | |
416 | :samp:`{newkind}`. | |
417 | ||
418 | Register notes are of three classes: They may say something about an | |
419 | input to an insn, they may say something about an output of an insn, or | |
420 | they may create a linkage between two insns. | |
421 | ||
422 | These register notes annotate inputs to an insn: | |
423 | ||
424 | .. index:: REG_DEAD | |
425 | ||
426 | .. envvar:: REG_DEAD | |
427 | ||
428 | The value in :samp:`{op}` dies in this insn; that is to say, altering the | |
429 | value immediately after this insn would not affect the future behavior | |
430 | of the program. | |
431 | ||
432 | It does not follow that the register :samp:`{op}` has no useful value after | |
433 | this insn since :samp:`{op}` is not necessarily modified by this insn. | |
434 | Rather, no subsequent instruction uses the contents of :samp:`{op}`. | |
435 | ||
436 | .. envvar:: REG_UNUSED | |
437 | ||
438 | The register :samp:`{op}` being set by this insn will not be used in a | |
439 | subsequent insn. This differs from a ``REG_DEAD`` note, which | |
440 | indicates that the value in an input will not be used subsequently. | |
441 | These two notes are independent; both may be present for the same | |
442 | register. | |
443 | ||
444 | .. envvar:: REG_INC | |
445 | ||
446 | The register :samp:`{op}` is incremented (or decremented; at this level | |
447 | there is no distinction) by an embedded side effect inside this insn. | |
448 | This means it appears in a ``post_inc``, ``pre_inc``, | |
449 | ``post_dec`` or ``pre_dec`` expression. | |
450 | ||
451 | .. envvar:: REG_NONNEG | |
452 | ||
453 | The register :samp:`{op}` is known to have a nonnegative value when this | |
454 | insn is reached. This is used by special looping instructions | |
455 | that terminate when the register goes negative. | |
456 | ||
457 | The ``REG_NONNEG`` note is added only to :samp:`doloop_end` | |
458 | insns, if its pattern uses a ``ge`` condition. | |
459 | ||
460 | .. envvar:: REG_LABEL_OPERAND | |
461 | ||
462 | This insn uses :samp:`{op}`, a ``code_label`` or a ``note`` of type | |
463 | ``NOTE_INSN_DELETED_LABEL``, but is not a ``jump_insn``, or it | |
464 | is a ``jump_insn`` that refers to the operand as an ordinary | |
465 | operand. The label may still eventually be a jump target, but if so | |
466 | in an indirect jump in a subsequent insn. The presence of this note | |
467 | allows jump optimization to be aware that :samp:`{op}` is, in fact, being | |
468 | used, and flow optimization to build an accurate flow graph. | |
469 | ||
470 | .. envvar:: REG_LABEL_TARGET | |
471 | ||
472 | This insn is a ``jump_insn`` but not an ``addr_vec`` or | |
473 | ``addr_diff_vec``. It uses :samp:`{op}`, a ``code_label`` as a | |
474 | direct or indirect jump target. Its purpose is similar to that of | |
475 | ``REG_LABEL_OPERAND``. This note is only present if the insn has | |
476 | multiple targets; the last label in the insn (in the highest numbered | |
477 | insn-field) goes into the ``JUMP_LABEL`` field and does not have a | |
478 | ``REG_LABEL_TARGET`` note. See :ref:`insns`. | |
479 | ||
480 | .. envvar:: REG_SETJMP | |
481 | ||
482 | Appears attached to each ``CALL_INSN`` to ``setjmp`` or a | |
483 | related function. | |
484 | ||
485 | The following notes describe attributes of outputs of an insn: | |
486 | ||
487 | .. index:: REG_EQUIV, REG_EQUAL | |
488 | ||
489 | .. envvar:: REG_EQUIV | |
490 | ||
491 | This note is only valid on an insn that sets only one register and | |
492 | indicates that that register will be equal to :samp:`{op}` at run time; the | |
493 | scope of this equivalence differs between the two types of notes. The | |
494 | value which the insn explicitly copies into the register may look | |
495 | different from :samp:`{op}`, but they will be equal at run time. If the | |
496 | output of the single ``set`` is a ``strict_low_part`` or | |
497 | ``zero_extract`` expression, the note refers to the register that | |
498 | is contained in its first operand. | |
499 | ||
500 | For ``REG_EQUIV``, the register is equivalent to :samp:`{op}` throughout | |
501 | the entire function, and could validly be replaced in all its | |
502 | occurrences by :samp:`{op}`. ('Validly' here refers to the data flow of | |
503 | the program; simple replacement may make some insns invalid.) For | |
504 | example, when a constant is loaded into a register that is never | |
505 | assigned any other value, this kind of note is used. | |
506 | ||
507 | When a parameter is copied into a pseudo-register at entry to a function, | |
508 | a note of this kind records that the register is equivalent to the stack | |
509 | slot where the parameter was passed. Although in this case the register | |
510 | may be set by other insns, it is still valid to replace the register | |
511 | by the stack slot throughout the function. | |
512 | ||
513 | A ``REG_EQUIV`` note is also used on an instruction which copies a | |
514 | register parameter into a pseudo-register at entry to a function, if | |
515 | there is a stack slot where that parameter could be stored. Although | |
516 | other insns may set the pseudo-register, it is valid for the compiler to | |
517 | replace the pseudo-register by stack slot throughout the function, | |
518 | provided the compiler ensures that the stack slot is properly | |
519 | initialized by making the replacement in the initial copy instruction as | |
520 | well. This is used on machines for which the calling convention | |
521 | allocates stack space for register parameters. See | |
522 | ``REG_PARM_STACK_SPACE`` in :ref:`stack-arguments`. | |
523 | ||
524 | In the case of ``REG_EQUAL``, the register that is set by this insn | |
525 | will be equal to :samp:`{op}` at run time at the end of this insn but not | |
526 | necessarily elsewhere in the function. In this case, :samp:`{op}` | |
527 | is typically an arithmetic expression. For example, when a sequence of | |
528 | insns such as a library call is used to perform an arithmetic operation, | |
529 | this kind of note is attached to the insn that produces or copies the | |
530 | final value. | |
531 | ||
532 | These two notes are used in different ways by the compiler passes. | |
533 | ``REG_EQUAL`` is used by passes prior to register allocation (such as | |
534 | common subexpression elimination and loop optimization) to tell them how | |
535 | to think of that value. ``REG_EQUIV`` notes are used by register | |
536 | allocation to indicate that there is an available substitute expression | |
537 | (either a constant or a ``mem`` expression for the location of a | |
538 | parameter on the stack) that may be used in place of a register if | |
539 | insufficient registers are available. | |
540 | ||
541 | Except for stack homes for parameters, which are indicated by a | |
542 | ``REG_EQUIV`` note and are not useful to the early optimization | |
543 | passes and pseudo registers that are equivalent to a memory location | |
544 | throughout their entire life, which is not detected until later in | |
545 | the compilation, all equivalences are initially indicated by an attached | |
546 | ``REG_EQUAL`` note. In the early stages of register allocation, a | |
547 | ``REG_EQUAL`` note is changed into a ``REG_EQUIV`` note if | |
548 | :samp:`{op}` is a constant and the insn represents the only set of its | |
549 | destination register. | |
550 | ||
551 | Thus, compiler passes prior to register allocation need only check for | |
552 | ``REG_EQUAL`` notes and passes subsequent to register allocation | |
553 | need only check for ``REG_EQUIV`` notes. | |
554 | ||
555 | These notes describe linkages between insns. They occur in pairs: one | |
556 | insn has one of a pair of notes that points to a second insn, which has | |
557 | the inverse note pointing back to the first insn. | |
558 | ||
559 | .. index:: REG_DEP_TRUE | |
560 | ||
561 | .. envvar:: REG_DEP_TRUE | |
562 | ||
563 | This indicates a true dependence (a read after write dependence). | |
564 | ||
565 | .. envvar:: REG_DEP_OUTPUT | |
566 | ||
567 | This indicates an output dependence (a write after write dependence). | |
568 | ||
569 | .. envvar:: REG_DEP_ANTI | |
570 | ||
571 | This indicates an anti dependence (a write after read dependence). | |
572 | ||
573 | These notes describe information gathered from gcov profile data. They | |
574 | are stored in the ``REG_NOTES`` field of an insn. | |
575 | ||
576 | .. index:: REG_BR_PROB | |
577 | ||
578 | .. envvar:: REG_BR_PROB | |
579 | ||
580 | This is used to specify the ratio of branches to non-branches of a | |
581 | branch insn according to the profile data. The note is represented | |
582 | as an ``int_list`` expression whose integer value is an encoding | |
583 | of ``profile_probability`` type. ``profile_probability`` provide | |
584 | member function ``from_reg_br_prob_note`` and ``to_reg_br_prob_note`` | |
585 | to extract and store the probability into the RTL encoding. | |
586 | ||
587 | .. envvar:: REG_BR_PRED | |
588 | ||
589 | These notes are found in JUMP insns after delayed branch scheduling | |
590 | has taken place. They indicate both the direction and the likelihood | |
591 | of the JUMP. The format is a bitmask of ATTR_FLAG\_\* values. | |
592 | ||
593 | .. envvar:: REG_FRAME_RELATED_EXPR | |
594 | ||
595 | This is used on an RTX_FRAME_RELATED_P insn wherein the attached expression | |
596 | is used in place of the actual insn pattern. This is done in cases where | |
597 | the pattern is either complex or misleading. | |
598 | ||
599 | The note ``REG_CALL_NOCF_CHECK`` is used in conjunction with the | |
600 | :option:`-fcf-protection=branch` option. The note is set if a | |
601 | ``nocf_check`` attribute is specified for a function type or a | |
602 | pointer to function type. The note is stored in the ``REG_NOTES`` | |
603 | field of an insn. | |
604 | ||
605 | .. index:: REG_CALL_NOCF_CHECK | |
606 | ||
607 | .. envvar:: REG_CALL_NOCF_CHECK | |
608 | ||
609 | Users have control through the ``nocf_check`` attribute to identify | |
610 | which calls to a function should be skipped from control-flow instrumentation | |
611 | when the option :option:`-fcf-protection=branch` is specified. The compiler | |
612 | puts a ``REG_CALL_NOCF_CHECK`` note on each ``CALL_INSN`` instruction | |
613 | that has a function type marked with a ``nocf_check`` attribute. | |
614 | ||
615 | For convenience, the machine mode in an ``insn_list`` or | |
616 | ``expr_list`` is printed using these symbolic codes in debugging dumps. | |
617 | ||
618 | .. index:: insn_list, expr_list | |
619 | ||
620 | The only difference between the expression codes ``insn_list`` and | |
621 | ``expr_list`` is that the first operand of an ``insn_list`` is | |
622 | assumed to be an insn and is printed in debugging dumps as the insn's | |
623 | unique id; the first operand of an ``expr_list`` is printed in the | |
624 | ordinary way as an expression. |