]>
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:: RTL insn template, generating insns, insns, generating, recognizing insns, insns, recognizing | |
7 | ||
8 | .. _rtl-template: | |
9 | ||
10 | RTL Template | |
11 | ************ | |
12 | ||
13 | The RTL template is used to define which insns match the particular pattern | |
14 | and how to find their operands. For named patterns, the RTL template also | |
15 | says how to construct an insn from specified operands. | |
16 | ||
17 | Construction involves substituting specified operands into a copy of the | |
18 | template. Matching involves determining the values that serve as the | |
19 | operands in the insn being matched. Both of these activities are | |
20 | controlled by special expression types that direct matching and | |
21 | substitution of the operands. | |
22 | ||
23 | .. index:: match_operand | |
24 | ||
25 | :samp:`(match_operand:{m} {n} {predicate} {constraint})` | |
26 | This expression is a placeholder for operand number :samp:`{n}` of | |
27 | the insn. When constructing an insn, operand number :samp:`{n}` | |
28 | will be substituted at this point. When matching an insn, whatever | |
29 | appears at this position in the insn will be taken as operand | |
30 | number :samp:`{n}` ; but it must satisfy :samp:`{predicate}` or this instruction | |
31 | pattern will not match at all. | |
32 | ||
33 | Operand numbers must be chosen consecutively counting from zero in | |
34 | each instruction pattern. There may be only one ``match_operand`` | |
35 | expression in the pattern for each operand number. Usually operands | |
36 | are numbered in the order of appearance in ``match_operand`` | |
37 | expressions. In the case of a ``define_expand``, any operand numbers | |
38 | used only in ``match_dup`` expressions have higher values than all | |
39 | other operand numbers. | |
40 | ||
41 | :samp:`{predicate}` is a string that is the name of a function that | |
42 | accepts two arguments, an expression and a machine mode. | |
43 | See :ref:`predicates`. During matching, the function will be called with | |
44 | the putative operand as the expression and :samp:`{m}` as the mode | |
45 | argument (if :samp:`{m}` is not specified, ``VOIDmode`` will be used, | |
46 | which normally causes :samp:`{predicate}` to accept any mode). If it | |
47 | returns zero, this instruction pattern fails to match. | |
48 | :samp:`{predicate}` may be an empty string; then it means no test is to be | |
49 | done on the operand, so anything which occurs in this position is | |
50 | valid. | |
51 | ||
52 | Most of the time, :samp:`{predicate}` will reject modes other than :samp:`{m}` ---but | |
53 | not always. For example, the predicate ``address_operand`` uses | |
54 | :samp:`{m}` as the mode of memory ref that the address should be valid for. | |
55 | Many predicates accept ``const_int`` nodes even though their mode is | |
56 | ``VOIDmode``. | |
57 | ||
58 | :samp:`{constraint}` controls reloading and the choice of the best register | |
59 | class to use for a value, as explained later (see :ref:`constraints`). | |
60 | If the constraint would be an empty string, it can be omitted. | |
61 | ||
62 | People are often unclear on the difference between the constraint and the | |
63 | predicate. The predicate helps decide whether a given insn matches the | |
64 | pattern. The constraint plays no role in this decision; instead, it | |
65 | controls various decisions in the case of an insn which does match. | |
66 | ||
67 | .. index:: match_scratch | |
68 | ||
69 | :samp:`(match_scratch:{m} {n} {constraint})` | |
70 | This expression is also a placeholder for operand number :samp:`{n}` | |
71 | and indicates that operand must be a ``scratch`` or ``reg`` | |
72 | expression. | |
73 | ||
74 | When matching patterns, this is equivalent to | |
75 | ||
76 | .. code-block:: | |
77 | ||
78 | (match_operand:m n "scratch_operand" constraint) | |
79 | ||
80 | but, when generating RTL, it produces a (``scratch`` : :samp:`{m}`) | |
81 | expression. | |
82 | ||
83 | If the last few expressions in a ``parallel`` are ``clobber`` | |
84 | expressions whose operands are either a hard register or | |
85 | ``match_scratch``, the combiner can add or delete them when | |
86 | necessary. See :ref:`side-effects`. | |
87 | ||
88 | .. index:: match_dup | |
89 | ||
90 | :samp:`(match_dup {n})` | |
91 | This expression is also a placeholder for operand number :samp:`{n}`. | |
92 | It is used when the operand needs to appear more than once in the | |
93 | insn. | |
94 | ||
95 | In construction, ``match_dup`` acts just like ``match_operand`` : | |
96 | the operand is substituted into the insn being constructed. But in | |
97 | matching, ``match_dup`` behaves differently. It assumes that operand | |
98 | number :samp:`{n}` has already been determined by a ``match_operand`` | |
99 | appearing earlier in the recognition template, and it matches only an | |
100 | identical-looking expression. | |
101 | ||
102 | Note that ``match_dup`` should not be used to tell the compiler that | |
103 | a particular register is being used for two operands (example: | |
104 | ``add`` that adds one register to another; the second register is | |
105 | both an input operand and the output operand). Use a matching | |
106 | constraint (see :ref:`simple-constraints`) for those. ``match_dup`` is for the cases where one | |
107 | operand is used in two places in the template, such as an instruction | |
108 | that computes both a quotient and a remainder, where the opcode takes | |
109 | two input operands but the RTL template has to refer to each of those | |
110 | twice; once for the quotient pattern and once for the remainder pattern. | |
111 | ||
112 | .. index:: match_operator | |
113 | ||
114 | :samp:`(match_operator:{m} {n} {predicate} [{operands}...])` | |
115 | This pattern is a kind of placeholder for a variable RTL expression | |
116 | code. | |
117 | ||
118 | When constructing an insn, it stands for an RTL expression whose | |
119 | expression code is taken from that of operand :samp:`{n}`, and whose | |
120 | operands are constructed from the patterns :samp:`{operands}`. | |
121 | ||
122 | When matching an expression, it matches an expression if the function | |
123 | :samp:`{predicate}` returns nonzero on that expression *and* the | |
124 | patterns :samp:`{operands}` match the operands of the expression. | |
125 | ||
126 | Suppose that the function ``commutative_operator`` is defined as | |
127 | follows, to match any expression whose operator is one of the | |
128 | commutative arithmetic operators of RTL and whose mode is :samp:`{mode}` : | |
129 | ||
130 | .. code-block:: | |
131 | ||
132 | int | |
133 | commutative_integer_operator (x, mode) | |
134 | rtx x; | |
135 | machine_mode mode; | |
136 | { | |
137 | enum rtx_code code = GET_CODE (x); | |
138 | if (GET_MODE (x) != mode) | |
139 | return 0; | |
140 | return (GET_RTX_CLASS (code) == RTX_COMM_ARITH | |
141 | || code == EQ || code == NE); | |
142 | } | |
143 | ||
144 | Then the following pattern will match any RTL expression consisting | |
145 | of a commutative operator applied to two general operands: | |
146 | ||
147 | .. code-block:: | |
148 | ||
149 | (match_operator:SI 3 "commutative_operator" | |
150 | [(match_operand:SI 1 "general_operand" "g") | |
151 | (match_operand:SI 2 "general_operand" "g")]) | |
152 | ||
153 | Here the vector ``[operands...]`` contains two patterns | |
154 | because the expressions to be matched all contain two operands. | |
155 | ||
156 | When this pattern does match, the two operands of the commutative | |
157 | operator are recorded as operands 1 and 2 of the insn. (This is done | |
158 | by the two instances of ``match_operand``.) Operand 3 of the insn | |
159 | will be the entire commutative expression: use ``GET_CODE | |
160 | (operands[3])`` to see which commutative operator was used. | |
161 | ||
162 | The machine mode :samp:`{m}` of ``match_operator`` works like that of | |
163 | ``match_operand`` : it is passed as the second argument to the | |
164 | predicate function, and that function is solely responsible for | |
165 | deciding whether the expression to be matched 'has' that mode. | |
166 | ||
167 | When constructing an insn, argument 3 of the gen-function will specify | |
168 | the operation (i.e. the expression code) for the expression to be | |
169 | made. It should be an RTL expression, whose expression code is copied | |
170 | into a new expression whose operands are arguments 1 and 2 of the | |
171 | gen-function. The subexpressions of argument 3 are not used; | |
172 | only its expression code matters. | |
173 | ||
174 | When ``match_operator`` is used in a pattern for matching an insn, | |
175 | it usually best if the operand number of the ``match_operator`` | |
176 | is higher than that of the actual operands of the insn. This improves | |
177 | register allocation because the register allocator often looks at | |
178 | operands 1 and 2 of insns to see if it can do register tying. | |
179 | ||
180 | There is no way to specify constraints in ``match_operator``. The | |
181 | operand of the insn which corresponds to the ``match_operator`` | |
182 | never has any constraints because it is never reloaded as a whole. | |
183 | However, if parts of its :samp:`{operands}` are matched by | |
184 | ``match_operand`` patterns, those parts may have constraints of | |
185 | their own. | |
186 | ||
187 | .. index:: match_op_dup | |
188 | ||
189 | :samp:`(match_op_dup:{m} {n}[{operands}...])` | |
190 | Like ``match_dup``, except that it applies to operators instead of | |
191 | operands. When constructing an insn, operand number :samp:`{n}` will be | |
192 | substituted at this point. But in matching, ``match_op_dup`` behaves | |
193 | differently. It assumes that operand number :samp:`{n}` has already been | |
194 | determined by a ``match_operator`` appearing earlier in the | |
195 | recognition template, and it matches only an identical-looking | |
196 | expression. | |
197 | ||
198 | .. index:: match_parallel | |
199 | ||
200 | :samp:`(match_parallel {n} {predicate} [{subpat}...])` | |
201 | This pattern is a placeholder for an insn that consists of a | |
202 | ``parallel`` expression with a variable number of elements. This | |
203 | expression should only appear at the top level of an insn pattern. | |
204 | ||
205 | When constructing an insn, operand number :samp:`{n}` will be substituted at | |
206 | this point. When matching an insn, it matches if the body of the insn | |
207 | is a ``parallel`` expression with at least as many elements as the | |
208 | vector of :samp:`{subpat}` expressions in the ``match_parallel``, if each | |
209 | :samp:`{subpat}` matches the corresponding element of the ``parallel``, | |
210 | *and* the function :samp:`{predicate}` returns nonzero on the | |
211 | ``parallel`` that is the body of the insn. It is the responsibility | |
212 | of the predicate to validate elements of the ``parallel`` beyond | |
213 | those listed in the ``match_parallel``. | |
214 | ||
215 | A typical use of ``match_parallel`` is to match load and store | |
216 | multiple expressions, which can contain a variable number of elements | |
217 | in a ``parallel``. For example, | |
218 | ||
219 | .. code-block:: | |
220 | ||
221 | (define_insn "" | |
222 | [(match_parallel 0 "load_multiple_operation" | |
223 | [(set (match_operand:SI 1 "gpc_reg_operand" "=r") | |
224 | (match_operand:SI 2 "memory_operand" "m")) | |
225 | (use (reg:SI 179)) | |
226 | (clobber (reg:SI 179))])] | |
227 | "" | |
228 | "loadm 0,0,%1,%2") | |
229 | ||
230 | This example comes from :samp:`a29k.md`. The function | |
231 | ``load_multiple_operation`` is defined in :samp:`a29k.c` and checks | |
232 | that subsequent elements in the ``parallel`` are the same as the | |
233 | ``set`` in the pattern, except that they are referencing subsequent | |
234 | registers and memory locations. | |
235 | ||
236 | An insn that matches this pattern might look like: | |
237 | ||
238 | .. code-block:: | |
239 | ||
240 | (parallel | |
241 | [(set (reg:SI 20) (mem:SI (reg:SI 100))) | |
242 | (use (reg:SI 179)) | |
243 | (clobber (reg:SI 179)) | |
244 | (set (reg:SI 21) | |
245 | (mem:SI (plus:SI (reg:SI 100) | |
246 | (const_int 4)))) | |
247 | (set (reg:SI 22) | |
248 | (mem:SI (plus:SI (reg:SI 100) | |
249 | (const_int 8))))]) | |
250 | ||
251 | .. index:: match_par_dup | |
252 | ||
253 | :samp:`(match_par_dup {n} [{subpat}...])` | |
254 | Like ``match_op_dup``, but for ``match_parallel`` instead of | |
3ed1b4ce | 255 | ``match_operator``. |