|
221
|
1 ===============================
|
|
|
2 TableGen Programmer's Reference
|
|
|
3 ===============================
|
|
|
4
|
|
|
5 .. sectnum::
|
|
|
6
|
|
|
7 .. contents::
|
|
|
8 :local:
|
|
|
9
|
|
|
10 Introduction
|
|
|
11 ============
|
|
|
12
|
|
|
13 The purpose of TableGen is to generate complex output files based on
|
|
|
14 information from source files that are significantly easier to code than the
|
|
|
15 output files would be, and also easier to maintain and modify over time. The
|
|
|
16 information is coded in a declarative style involving classes and records,
|
|
|
17 which are then processed by TableGen. The internalized records are passed on
|
|
|
18 to various *backends*, which extract information from a subset of the records
|
|
|
19 and generate one or more output files. These output files are typically
|
|
|
20 ``.inc`` files for C++, but may be any type of file that the backend
|
|
|
21 developer needs.
|
|
|
22
|
|
|
23 This document describes the LLVM TableGen facility in detail. It is intended
|
|
|
24 for the programmer who is using TableGen to produce code for a project. If
|
|
|
25 you are looking for a simple overview, check out the :doc:`TableGen Overview
|
|
|
26 <./index>`. The various ``*-tblgen`` commands used to invoke TableGen are
|
|
|
27 described in :doc:`tblgen Family - Description to C++
|
|
|
28 Code<../CommandGuide/tblgen>`.
|
|
|
29
|
|
|
30 An example of a backend is ``RegisterInfo``, which generates the register
|
|
|
31 file information for a particular target machine, for use by the LLVM
|
|
|
32 target-independent code generator. See :doc:`TableGen Backends <./BackEnds>`
|
|
|
33 for a description of the LLVM TableGen backends, and :doc:`TableGen
|
|
|
34 Backend Developer's Guide <./BackGuide>` for a guide to writing a new
|
|
|
35 backend.
|
|
|
36
|
|
|
37 Here are a few of the things backends can do.
|
|
|
38
|
|
|
39 * Generate the register file information for a particular target machine.
|
|
|
40
|
|
|
41 * Generate the instruction definitions for a target.
|
|
|
42
|
|
|
43 * Generate the patterns that the code generator uses to match instructions
|
|
|
44 to intermediate representation (IR) nodes.
|
|
|
45
|
|
|
46 * Generate semantic attribute identifiers for Clang.
|
|
|
47
|
|
|
48 * Generate abstract syntax tree (AST) declaration node definitions for Clang.
|
|
|
49
|
|
|
50 * Generate AST statement node definitions for Clang.
|
|
|
51
|
|
|
52
|
|
|
53 Concepts
|
|
|
54 --------
|
|
|
55
|
|
|
56 TableGen source files contain two primary items: *abstract records* and
|
|
|
57 *concrete records*. In this and other TableGen documents, abstract records
|
|
|
58 are called *classes.* (These classes are different from C++ classes and do
|
|
|
59 not map onto them.) In addition, concrete records are usually just called
|
|
|
60 records, although sometimes the term *record* refers to both classes and
|
|
|
61 concrete records. The distinction should be clear in context.
|
|
|
62
|
|
|
63 Classes and concrete records have a unique *name*, either chosen by
|
|
|
64 the programmer or generated by TableGen. Associated with that name
|
|
|
65 is a list of *fields* with values and an optional list of *parent classes*
|
|
|
66 (sometimes called base or super classes). The fields are the primary data that
|
|
|
67 backends will process. Note that TableGen assigns no meanings to fields; the
|
|
|
68 meanings are entirely up to the backends and the programs that incorporate
|
|
|
69 the output of those backends.
|
|
|
70
|
|
|
71 .. note::
|
|
|
72
|
|
|
73 The term "parent class" can refer to a class that is a parent of another
|
|
|
74 class, and also to a class from which a concrete record inherits. This
|
|
|
75 nonstandard use of the term arises because TableGen treats classes and
|
|
|
76 concrete records similarly.
|
|
|
77
|
|
|
78 A backend processes some subset of the concrete records built by the
|
|
|
79 TableGen parser and emits the output files. These files are usually C++
|
|
|
80 ``.inc`` files that are included by the programs that require the data in
|
|
|
81 those records. However, a backend can produce any type of output files. For
|
|
|
82 example, it could produce a data file containing messages tagged with
|
|
|
83 identifiers and substitution parameters. In a complex use case such as the
|
|
|
84 LLVM code generator, there can be many concrete records and some of them can
|
|
|
85 have an unexpectedly large number of fields, resulting in large output files.
|
|
|
86
|
|
|
87 In order to reduce the complexity of TableGen files, classes are used to
|
|
|
88 abstract out groups of record fields. For example, a few classes may
|
|
|
89 abstract the concept of a machine register file, while other classes may
|
|
|
90 abstract the instruction formats, and still others may abstract the
|
|
|
91 individual instructions. TableGen allows an arbitrary hierarchy of classes,
|
|
|
92 so that the abstract classes for two concepts can share a third superclass that
|
|
|
93 abstracts common "sub-concepts" from the two original concepts.
|
|
|
94
|
|
|
95 In order to make classes more useful, a concrete record (or another class)
|
|
|
96 can request a class as a parent class and pass *template arguments* to it.
|
|
|
97 These template arguments can be used in the fields of the parent class to
|
|
|
98 initialize them in a custom manner. That is, record or class ``A`` can
|
|
|
99 request parent class ``S`` with one set of template arguments, while record or class
|
|
|
100 ``B`` can request ``S`` with a different set of arguments. Without template
|
|
|
101 arguments, many more classes would be required, one for each combination of
|
|
|
102 the template arguments.
|
|
|
103
|
|
|
104 Both classes and concrete records can include fields that are uninitialized.
|
|
|
105 The uninitialized "value" is represented by a question mark (``?``). Classes
|
|
|
106 often have uninitialized fields that are expected to be filled in when those
|
|
|
107 classes are inherited by concrete records. Even so, some fields of concrete
|
|
|
108 records may remain uninitialized.
|
|
|
109
|
|
|
110 TableGen provides *multiclasses* to collect a group of record definitions in
|
|
|
111 one place. A multiclass is a sort of macro that can be "invoked" to define
|
|
|
112 multiple concrete records all at once. A multiclass can inherit from other
|
|
|
113 multiclasses, which means that the multiclass inherits all the definitions
|
|
|
114 from its parent multiclasses.
|
|
|
115
|
|
|
116 `Appendix C: Sample Record`_ illustrates a complex record in the Intel X86
|
|
|
117 target and the simple way in which it is defined.
|
|
|
118
|
|
|
119 Source Files
|
|
|
120 ============
|
|
|
121
|
|
|
122 TableGen source files are plain ASCII text files. The files can contain
|
|
|
123 statements, comments, and blank lines (see `Lexical Analysis`_). The standard file
|
|
|
124 extension for TableGen files is ``.td``.
|
|
|
125
|
|
|
126 TableGen files can grow quite large, so there is an include mechanism that
|
|
|
127 allows one file to include the content of another file (see `Include
|
|
|
128 Files`_). This allows large files to be broken up into smaller ones, and
|
|
|
129 also provides a simple library mechanism where multiple source files can
|
|
|
130 include the same library file.
|
|
|
131
|
|
|
132 TableGen supports a simple preprocessor that can be used to conditionalize
|
|
|
133 portions of ``.td`` files. See `Preprocessing Facilities`_ for more
|
|
|
134 information.
|
|
|
135
|
|
|
136 Lexical Analysis
|
|
|
137 ================
|
|
|
138
|
|
|
139 The lexical and syntax notation used here is intended to imitate
|
|
|
140 `Python's`_ notation. In particular, for lexical definitions, the productions
|
|
|
141 operate at the character level and there is no implied whitespace between
|
|
|
142 elements. The syntax definitions operate at the token level, so there is
|
|
|
143 implied whitespace between tokens.
|
|
|
144
|
|
|
145 .. _`Python's`: http://docs.python.org/py3k/reference/introduction.html#notation
|
|
|
146
|
|
|
147 TableGen supports BCPL-style comments (``// ...``) and nestable C-style
|
|
|
148 comments (``/* ... */``).
|
|
|
149 TableGen also provides simple `Preprocessing Facilities`_.
|
|
|
150
|
|
|
151 Formfeed characters may be used freely in files to produce page breaks when
|
|
|
152 the file is printed for review.
|
|
|
153
|
|
|
154 The following are the basic punctuation tokens::
|
|
|
155
|
|
|
156 - + [ ] { } ( ) < > : ; . ... = ? #
|
|
|
157
|
|
|
158 Literals
|
|
|
159 --------
|
|
|
160
|
|
|
161 Numeric literals take one of the following forms:
|
|
|
162
|
|
|
163 .. productionlist::
|
|
|
164 TokInteger: `DecimalInteger` | `HexInteger` | `BinInteger`
|
|
|
165 DecimalInteger: ["+" | "-"] ("0"..."9")+
|
|
|
166 HexInteger: "0x" ("0"..."9" | "a"..."f" | "A"..."F")+
|
|
|
167 BinInteger: "0b" ("0" | "1")+
|
|
|
168
|
|
|
169 Observe that the :token:`DecimalInteger` token includes the optional ``+``
|
|
|
170 or ``-`` sign, unlike most languages where the sign would be treated as a
|
|
|
171 unary operator.
|
|
|
172
|
|
|
173 TableGen has two kinds of string literals:
|
|
|
174
|
|
|
175 .. productionlist::
|
|
|
176 TokString: '"' (non-'"' characters and escapes) '"'
|
|
|
177 TokCode: "[{" (shortest text not containing "}]") "}]"
|
|
|
178
|
|
|
179 A :token:`TokCode` is nothing more than a multi-line string literal
|
|
|
180 delimited by ``[{`` and ``}]``. It can break across lines and the
|
|
|
181 line breaks are retained in the string.
|
|
|
182
|
|
|
183 The current implementation accepts the following escape sequences::
|
|
|
184
|
|
|
185 \\ \' \" \t \n
|
|
|
186
|
|
|
187 Identifiers
|
|
|
188 -----------
|
|
|
189
|
|
|
190 TableGen has name- and identifier-like tokens, which are case-sensitive.
|
|
|
191
|
|
|
192 .. productionlist::
|
|
|
193 ualpha: "a"..."z" | "A"..."Z" | "_"
|
|
|
194 TokIdentifier: ("0"..."9")* `ualpha` (`ualpha` | "0"..."9")*
|
|
|
195 TokVarName: "$" `ualpha` (`ualpha` | "0"..."9")*
|
|
|
196
|
|
|
197 Note that, unlike most languages, TableGen allows :token:`TokIdentifier` to
|
|
|
198 begin with an integer. In case of ambiguity, a token is interpreted as a
|
|
|
199 numeric literal rather than an identifier.
|
|
|
200
|
|
|
201 TableGen has the following reserved keywords, which cannot be used as
|
|
|
202 identifiers::
|
|
|
203
|
|
|
204 assert bit bits class code
|
|
|
205 dag def else false foreach
|
|
|
206 defm defset defvar field if
|
|
|
207 in include int let list
|
|
|
208 multiclass string then true
|
|
|
209
|
|
|
210 .. warning::
|
|
236
|
211 The ``field`` reserved word is deprecated, except when used with the
|
|
|
212 CodeEmitterGen backend where it's used to distinguish normal record
|
|
|
213 fields from encoding fields.
|
|
221
|
214
|
|
|
215 Bang operators
|
|
|
216 --------------
|
|
|
217
|
|
|
218 TableGen provides "bang operators" that have a wide variety of uses:
|
|
|
219
|
|
|
220 .. productionlist::
|
|
|
221 BangOperator: one of
|
|
236
|
222 : !add !and !cast !con !dag
|
|
|
223 : !div !empty !eq !filter !find
|
|
|
224 : !foldl !foreach !ge !getdagop !gt
|
|
|
225 : !head !if !interleave !isa !le
|
|
|
226 : !listconcat !listsplat !logtwo !lt !mul
|
|
|
227 : !ne !not !or !setdagop !shl
|
|
|
228 : !size !sra !srl !strconcat !sub
|
|
|
229 : !subst !substr !tail !xor
|
|
221
|
230
|
|
|
231 The ``!cond`` operator has a slightly different
|
|
|
232 syntax compared to other bang operators, so it is defined separately:
|
|
|
233
|
|
|
234 .. productionlist::
|
|
|
235 CondOperator: !cond
|
|
|
236
|
|
|
237 See `Appendix A: Bang Operators`_ for a description of each bang operator.
|
|
|
238
|
|
|
239 Include files
|
|
|
240 -------------
|
|
|
241
|
|
|
242 TableGen has an include mechanism. The content of the included file
|
|
|
243 lexically replaces the ``include`` directive and is then parsed as if it was
|
|
|
244 originally in the main file.
|
|
|
245
|
|
|
246 .. productionlist::
|
|
|
247 IncludeDirective: "include" `TokString`
|
|
|
248
|
|
|
249 Portions of the main file and included files can be conditionalized using
|
|
|
250 preprocessor directives.
|
|
|
251
|
|
|
252 .. productionlist::
|
|
|
253 PreprocessorDirective: "#define" | "#ifdef" | "#ifndef"
|
|
|
254
|
|
|
255 Types
|
|
|
256 =====
|
|
|
257
|
|
|
258 The TableGen language is statically typed, using a simple but complete type
|
|
|
259 system. Types are used to check for errors, to perform implicit conversions,
|
|
|
260 and to help interface designers constrain the allowed input. Every value is
|
|
|
261 required to have an associated type.
|
|
|
262
|
|
|
263 TableGen supports a mixture of low-level types (e.g., ``bit``) and
|
|
|
264 high-level types (e.g., ``dag``). This flexibility allows you to describe a
|
|
|
265 wide range of records conveniently and compactly.
|
|
|
266
|
|
|
267 .. productionlist::
|
|
|
268 Type: "bit" | "int" | "string" | "dag"
|
|
|
269 :| "bits" "<" `TokInteger` ">"
|
|
|
270 :| "list" "<" `Type` ">"
|
|
|
271 :| `ClassID`
|
|
|
272 ClassID: `TokIdentifier`
|
|
|
273
|
|
|
274 ``bit``
|
|
|
275 A ``bit`` is a boolean value that can be 0 or 1.
|
|
|
276
|
|
|
277 ``int``
|
|
|
278 The ``int`` type represents a simple 64-bit integer value, such as 5 or
|
|
|
279 -42.
|
|
|
280
|
|
|
281 ``string``
|
|
|
282 The ``string`` type represents an ordered sequence of characters of arbitrary
|
|
|
283 length.
|
|
|
284
|
|
|
285 ``bits<``\ *n*\ ``>``
|
|
|
286 The ``bits`` type is a fixed-sized integer of arbitrary length *n* that
|
|
|
287 is treated as separate bits. These bits can be accessed individually.
|
|
|
288 A field of this type is useful for representing an instruction operation
|
|
|
289 code, register number, or address mode/register/displacement. The bits of
|
|
|
290 the field can be set individually or as subfields. For example, in an
|
|
|
291 instruction address, the addressing mode, base register number, and
|
|
|
292 displacement can be set separately.
|
|
|
293
|
|
|
294 ``list<``\ *type*\ ``>``
|
|
|
295 This type represents a list whose elements are of the *type* specified in
|
|
|
296 angle brackets. The element type is arbitrary; it can even be another
|
|
|
297 list type. List elements are indexed from 0.
|
|
|
298
|
|
|
299 ``dag``
|
|
|
300 This type represents a nestable directed acyclic graph (DAG) of nodes.
|
|
|
301 Each node has an *operator* and zero or more *arguments* (or *operands*).
|
|
|
302 An argument can be
|
|
|
303 another ``dag`` object, allowing an arbitrary tree of nodes and edges.
|
|
|
304 As an example, DAGs are used to represent code patterns for use by
|
|
|
305 the code generator instruction selection algorithms. See `Directed
|
|
|
306 acyclic graphs (DAGs)`_ for more details;
|
|
|
307
|
|
|
308 :token:`ClassID`
|
|
|
309 Specifying a class name in a type context indicates
|
|
|
310 that the type of the defined value must
|
|
|
311 be a subclass of the specified class. This is useful in conjunction with
|
|
|
312 the ``list`` type; for example, to constrain the elements of the list to a
|
|
|
313 common base class (e.g., a ``list<Register>`` can only contain definitions
|
|
|
314 derived from the ``Register`` class).
|
|
|
315 The :token:`ClassID` must name a class that has been previously
|
|
|
316 declared or defined.
|
|
|
317
|
|
|
318
|
|
|
319 Values and Expressions
|
|
|
320 ======================
|
|
|
321
|
|
|
322 There are many contexts in TableGen statements where a value is required. A
|
|
|
323 common example is in the definition of a record, where each field is
|
|
|
324 specified by a name and an optional value. TableGen allows for a reasonable
|
|
|
325 number of different forms when building up value expressions. These forms
|
|
|
326 allow the TableGen file to be written in a syntax that is natural for the
|
|
|
327 application.
|
|
|
328
|
|
|
329 Note that all of the values have rules for converting them from one type to
|
|
|
330 another. For example, these rules allow you to assign a value like ``7``
|
|
|
331 to an entity of type ``bits<4>``.
|
|
|
332
|
|
|
333 .. productionlist::
|
|
|
334 Value: `SimpleValue` `ValueSuffix`*
|
|
236
|
335 :| `Value` "#" [`Value`]
|
|
221
|
336 ValueSuffix: "{" `RangeList` "}"
|
|
|
337 :| "[" `RangeList` "]"
|
|
|
338 :| "." `TokIdentifier`
|
|
|
339 RangeList: `RangePiece` ("," `RangePiece`)*
|
|
|
340 RangePiece: `TokInteger`
|
|
|
341 :| `TokInteger` "..." `TokInteger`
|
|
|
342 :| `TokInteger` "-" `TokInteger`
|
|
|
343 :| `TokInteger` `TokInteger`
|
|
|
344
|
|
|
345 .. warning::
|
|
|
346 The peculiar last form of :token:`RangePiece` is due to the fact that the
|
|
|
347 "``-``" is included in the :token:`TokInteger`, hence ``1-5`` gets lexed as
|
|
|
348 two consecutive tokens, with values ``1`` and ``-5``, instead of "1", "-",
|
|
|
349 and "5". The use of hyphen as the range punctuation is deprecated.
|
|
|
350
|
|
|
351 Simple values
|
|
|
352 -------------
|
|
|
353
|
|
|
354 The :token:`SimpleValue` has a number of forms.
|
|
|
355
|
|
|
356 .. productionlist::
|
|
|
357 SimpleValue: `TokInteger` | `TokString`+ | `TokCode`
|
|
|
358
|
|
|
359 A value can be an integer literal, a string literal, or a code literal.
|
|
|
360 Multiple adjacent string literals are concatenated as in C/C++; the simple
|
|
|
361 value is the concatenation of the strings. Code literals become strings and
|
|
|
362 are then indistinguishable from them.
|
|
|
363
|
|
|
364 .. productionlist::
|
|
|
365 SimpleValue2: "true" | "false"
|
|
|
366
|
|
|
367 The ``true`` and ``false`` literals are essentially syntactic sugar for the
|
|
|
368 integer values 1 and 0. They improve the readability of TableGen files when
|
|
|
369 boolean values are used in field initializations, bit sequences, ``if``
|
|
|
370 statements, etc. When parsed, these literals are converted to integers.
|
|
|
371
|
|
|
372 .. note::
|
|
|
373
|
|
|
374 Although ``true`` and ``false`` are literal names for 1 and 0, we
|
|
|
375 recommend as a stylistic rule that you use them for boolean
|
|
|
376 values only.
|
|
|
377
|
|
|
378 .. productionlist::
|
|
|
379 SimpleValue3: "?"
|
|
|
380
|
|
|
381 A question mark represents an uninitialized value.
|
|
|
382
|
|
|
383 .. productionlist::
|
|
|
384 SimpleValue4: "{" [`ValueList`] "}"
|
|
|
385 ValueList: `ValueListNE`
|
|
|
386 ValueListNE: `Value` ("," `Value`)*
|
|
|
387
|
|
|
388 This value represents a sequence of bits, which can be used to initialize a
|
|
|
389 ``bits<``\ *n*\ ``>`` field (note the braces). When doing so, the values
|
|
|
390 must represent a total of *n* bits.
|
|
|
391
|
|
|
392 .. productionlist::
|
|
|
393 SimpleValue5: "[" `ValueList` "]" ["<" `Type` ">"]
|
|
|
394
|
|
|
395 This value is a list initializer (note the brackets). The values in brackets
|
|
|
396 are the elements of the list. The optional :token:`Type` can be used to
|
|
|
397 indicate a specific element type; otherwise the element type is inferred
|
|
|
398 from the given values. TableGen can usually infer the type, although
|
|
|
399 sometimes not when the value is the empty list (``[]``).
|
|
|
400
|
|
|
401 .. productionlist::
|
|
|
402 SimpleValue6: "(" `DagArg` [`DagArgList`] ")"
|
|
|
403 DagArgList: `DagArg` ("," `DagArg`)*
|
|
|
404 DagArg: `Value` [":" `TokVarName`] | `TokVarName`
|
|
|
405
|
|
|
406 This represents a DAG initializer (note the parentheses). The first
|
|
|
407 :token:`DagArg` is called the "operator" of the DAG and must be a record.
|
|
|
408 See `Directed acyclic graphs (DAGs)`_ for more details.
|
|
|
409
|
|
|
410 .. productionlist::
|
|
|
411 SimpleValue7: `TokIdentifier`
|
|
|
412
|
|
|
413 The resulting value is the value of the entity named by the identifier. The
|
|
|
414 possible identifiers are described here, but the descriptions will make more
|
|
|
415 sense after reading the remainder of this guide.
|
|
|
416
|
|
|
417 .. The code for this is exceptionally abstruse. These examples are a
|
|
|
418 best-effort attempt.
|
|
|
419
|
|
|
420 * A template argument of a ``class``, such as the use of ``Bar`` in::
|
|
|
421
|
|
|
422 class Foo <int Bar> {
|
|
|
423 int Baz = Bar;
|
|
|
424 }
|
|
|
425
|
|
|
426 * The implicit template argument ``NAME`` in a ``class`` or ``multiclass``
|
|
|
427 definition (see `NAME`_).
|
|
|
428
|
|
|
429 * A field local to a ``class``, such as the use of ``Bar`` in::
|
|
|
430
|
|
|
431 class Foo {
|
|
|
432 int Bar = 5;
|
|
|
433 int Baz = Bar;
|
|
|
434 }
|
|
|
435
|
|
|
436 * The name of a record definition, such as the use of ``Bar`` in the
|
|
|
437 definition of ``Foo``::
|
|
|
438
|
|
|
439 def Bar : SomeClass {
|
|
|
440 int X = 5;
|
|
|
441 }
|
|
|
442
|
|
|
443 def Foo {
|
|
|
444 SomeClass Baz = Bar;
|
|
|
445 }
|
|
|
446
|
|
|
447 * A field local to a record definition, such as the use of ``Bar`` in::
|
|
|
448
|
|
|
449 def Foo {
|
|
|
450 int Bar = 5;
|
|
|
451 int Baz = Bar;
|
|
|
452 }
|
|
|
453
|
|
|
454 Fields inherited from the record's parent classes can be accessed the same way.
|
|
|
455
|
|
|
456 * A template argument of a ``multiclass``, such as the use of ``Bar`` in::
|
|
|
457
|
|
|
458 multiclass Foo <int Bar> {
|
|
|
459 def : SomeClass<Bar>;
|
|
|
460 }
|
|
|
461
|
|
|
462 * A variable defined with the ``defvar`` or ``defset`` statements.
|
|
|
463
|
|
|
464 * The iteration variable of a ``foreach``, such as the use of ``i`` in::
|
|
|
465
|
|
|
466 foreach i = 0...5 in
|
|
|
467 def Foo#i;
|
|
|
468
|
|
|
469 .. productionlist::
|
|
|
470 SimpleValue8: `ClassID` "<" `ValueListNE` ">"
|
|
|
471
|
|
|
472 This form creates a new anonymous record definition (as would be created by an
|
|
|
473 unnamed ``def`` inheriting from the given class with the given template
|
|
|
474 arguments; see `def`_) and the value is that record. A field of the record can be
|
|
|
475 obtained using a suffix; see `Suffixed Values`_.
|
|
|
476
|
|
|
477 Invoking a class in this manner can provide a simple subroutine facility.
|
|
|
478 See `Using Classes as Subroutines`_ for more information.
|
|
|
479
|
|
|
480 .. productionlist::
|
|
|
481 SimpleValue9: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"
|
|
|
482 :| `CondOperator` "(" `CondClause` ("," `CondClause`)* ")"
|
|
|
483 CondClause: `Value` ":" `Value`
|
|
|
484
|
|
|
485 The bang operators provide functions that are not available with the other
|
|
|
486 simple values. Except in the case of ``!cond``, a bang operator takes a list
|
|
|
487 of arguments enclosed in parentheses and performs some function on those
|
|
|
488 arguments, producing a value for that bang operator. The ``!cond`` operator
|
|
|
489 takes a list of pairs of arguments separated by colons. See `Appendix A:
|
|
|
490 Bang Operators`_ for a description of each bang operator.
|
|
|
491
|
|
|
492
|
|
|
493 Suffixed values
|
|
|
494 ---------------
|
|
|
495
|
|
|
496 The :token:`SimpleValue` values described above can be specified with
|
|
|
497 certain suffixes. The purpose of a suffix is to obtain a subvalue of the
|
|
|
498 primary value. Here are the possible suffixes for some primary *value*.
|
|
|
499
|
|
|
500 *value*\ ``{17}``
|
|
|
501 The final value is bit 17 of the integer *value* (note the braces).
|
|
|
502
|
|
|
503 *value*\ ``{8...15}``
|
|
|
504 The final value is bits 8--15 of the integer *value*. The order of the
|
|
|
505 bits can be reversed by specifying ``{15...8}``.
|
|
|
506
|
|
|
507 *value*\ ``[4]``
|
|
|
508 The final value is element 4 of the list *value* (note the brackets).
|
|
|
509 In other words, the brackets act as a subscripting operator on the list.
|
|
|
510 This is the case only when a single element is specified.
|
|
|
511
|
|
|
512 *value*\ ``[4...7,17,2...3,4]``
|
|
|
513 The final value is a new list that is a slice of the list *value*.
|
|
|
514 The new list contains elements 4, 5, 6, 7, 17, 2, 3, and 4.
|
|
|
515 Elements may be included multiple times and in any order. This is the result
|
|
|
516 only when more than one element is specified.
|
|
|
517
|
|
|
518 *value*\ ``.``\ *field*
|
|
|
519 The final value is the value of the specified *field* in the specified
|
|
|
520 record *value*.
|
|
|
521
|
|
|
522 The paste operator
|
|
|
523 ------------------
|
|
|
524
|
|
|
525 The paste operator (``#``) is the only infix operator available in TableGen
|
|
|
526 expressions. It allows you to concatenate strings or lists, but has a few
|
|
|
527 unusual features.
|
|
|
528
|
|
|
529 The paste operator can be used when specifying the record name in a
|
|
|
530 :token:`Def` or :token:`Defm` statement, in which case it must construct a
|
|
|
531 string. If an operand is an undefined name (:token:`TokIdentifier`) or the
|
|
|
532 name of a global :token:`Defvar` or :token:`Defset`, it is treated as a
|
|
|
533 verbatim string of characters. The value of a global name is not used.
|
|
|
534
|
|
|
535 The paste operator can be used in all other value expressions, in which case
|
|
|
536 it can construct a string or a list. Rather oddly, but consistent with the
|
|
|
537 previous case, if the *right-hand-side* operand is an undefined name or a
|
|
|
538 global name, it is treated as a verbatim string of characters. The
|
|
|
539 left-hand-side operand is treated normally.
|
|
|
540
|
|
236
|
541 Values can have a trailing paste operator, in which case the left-hand-side
|
|
|
542 operand is concatenated to an empty string.
|
|
|
543
|
|
221
|
544 `Appendix B: Paste Operator Examples`_ presents examples of the behavior of
|
|
|
545 the paste operator.
|
|
|
546
|
|
|
547 Statements
|
|
|
548 ==========
|
|
|
549
|
|
|
550 The following statements may appear at the top level of TableGen source
|
|
|
551 files.
|
|
|
552
|
|
|
553 .. productionlist::
|
|
236
|
554 TableGenFile: (`Statement` | `IncludeDirective`
|
|
|
555 :| `PreprocessorDirective`)*
|
|
221
|
556 Statement: `Assert` | `Class` | `Def` | `Defm` | `Defset` | `Defvar`
|
|
|
557 :| `Foreach` | `If` | `Let` | `MultiClass`
|
|
|
558
|
|
236
|
559 The following sections describe each of these top-level statements.
|
|
221
|
560
|
|
|
561
|
|
|
562 ``class`` --- define an abstract record class
|
|
|
563 ---------------------------------------------
|
|
|
564
|
|
|
565 A ``class`` statement defines an abstract record class from which other
|
|
236
|
566 classes and records can inherit.
|
|
221
|
567
|
|
|
568 .. productionlist::
|
|
|
569 Class: "class" `ClassID` [`TemplateArgList`] `RecordBody`
|
|
|
570 TemplateArgList: "<" `TemplateArgDecl` ("," `TemplateArgDecl`)* ">"
|
|
|
571 TemplateArgDecl: `Type` `TokIdentifier` ["=" `Value`]
|
|
|
572
|
|
|
573 A class can be parameterized by a list of "template arguments," whose values
|
|
|
574 can be used in the class's record body. These template arguments are
|
|
|
575 specified each time the class is inherited by another class or record.
|
|
|
576
|
|
|
577 If a template argument is not assigned a default value with ``=``, it is
|
|
|
578 uninitialized (has the "value" ``?``) and must be specified in the template
|
|
|
579 argument list when the class is inherited (required argument). If an
|
|
|
580 argument is assigned a default value, then it need not be specified in the
|
|
|
581 argument list (optional argument). In the declaration, all required template
|
|
|
582 arguments must precede any optional arguments. The template argument default
|
|
|
583 values are evaluated from left to right.
|
|
|
584
|
|
|
585 The :token:`RecordBody` is defined below. It can include a list of
|
|
|
586 parent classes from which the current class inherits, along with field
|
|
|
587 definitions and other statements. When a class ``C`` inherits from another
|
|
|
588 class ``D``, the fields of ``D`` are effectively merged into the fields of
|
|
|
589 ``C``.
|
|
|
590
|
|
|
591 A given class can only be defined once. A ``class`` statement is
|
|
|
592 considered to define the class if *any* of the following are true (the
|
|
|
593 :token:`RecordBody` elements are described below).
|
|
|
594
|
|
|
595 * The :token:`TemplateArgList` is present, or
|
|
|
596 * The :token:`ParentClassList` in the :token:`RecordBody` is present, or
|
|
|
597 * The :token:`Body` in the :token:`RecordBody` is present and not empty.
|
|
|
598
|
|
|
599 You can declare an empty class by specifying an empty :token:`TemplateArgList`
|
|
|
600 and an empty :token:`RecordBody`. This can serve as a restricted form of
|
|
|
601 forward declaration. Note that records derived from a forward-declared
|
|
|
602 class will inherit no fields from it, because those records are built when
|
|
|
603 their declarations are parsed, and thus before the class is finally defined.
|
|
|
604
|
|
|
605 .. _NAME:
|
|
|
606
|
|
|
607 Every class has an implicit template argument named ``NAME`` (uppercase),
|
|
|
608 which is bound to the name of the :token:`Def` or :token:`Defm` inheriting
|
|
|
609 from the class. If the class is inherited by an anonymous record, the name
|
|
|
610 is unspecified but globally unique.
|
|
|
611
|
|
|
612 See `Examples: classes and records`_ for examples.
|
|
|
613
|
|
|
614 Record Bodies
|
|
|
615 `````````````
|
|
|
616
|
|
|
617 Record bodies appear in both class and record definitions. A record body can
|
|
|
618 include a parent class list, which specifies the classes from which the
|
|
|
619 current class or record inherits fields. Such classes are called the
|
|
|
620 parent classes of the class or record. The record body also
|
|
|
621 includes the main body of the definition, which contains the specification
|
|
|
622 of the fields of the class or record.
|
|
|
623
|
|
|
624 .. productionlist::
|
|
|
625 RecordBody: `ParentClassList` `Body`
|
|
|
626 ParentClassList: [":" `ParentClassListNE`]
|
|
|
627 ParentClassListNE: `ClassRef` ("," `ClassRef`)*
|
|
|
628 ClassRef: (`ClassID` | `MultiClassID`) ["<" [`ValueList`] ">"]
|
|
|
629
|
|
|
630 A :token:`ParentClassList` containing a :token:`MultiClassID` is valid only
|
|
|
631 in the class list of a ``defm`` statement. In that case, the ID must be the
|
|
|
632 name of a multiclass.
|
|
|
633
|
|
|
634 .. productionlist::
|
|
|
635 Body: ";" | "{" `BodyItem`* "}"
|
|
|
636 BodyItem: (`Type` | "code") `TokIdentifier` ["=" `Value`] ";"
|
|
|
637 :| "let" `TokIdentifier` ["{" `RangeList` "}"] "=" `Value` ";"
|
|
|
638 :| "defvar" `TokIdentifier` "=" `Value` ";"
|
|
|
639 :| `Assert`
|
|
|
640
|
|
|
641 A field definition in the body specifies a field to be included in the class
|
|
|
642 or record. If no initial value is specified, then the field's value is
|
|
|
643 uninitialized. The type must be specified; TableGen will not infer it from
|
|
|
644 the value. The keyword ``code`` may be used to emphasize that the field
|
|
|
645 has a string value that is code.
|
|
|
646
|
|
|
647 The ``let`` form is used to reset a field to a new value. This can be done
|
|
|
648 for fields defined directly in the body or fields inherited from parent
|
|
|
649 classes. A :token:`RangeList` can be specified to reset certain bits in a
|
|
|
650 ``bit<n>`` field.
|
|
|
651
|
|
|
652 The ``defvar`` form defines a variable whose value can be used in other
|
|
|
653 value expressions within the body. The variable is not a field: it does not
|
|
|
654 become a field of the class or record being defined. Variables are provided
|
|
|
655 to hold temporary values while processing the body. See `Defvar in a Record
|
|
|
656 Body`_ for more details.
|
|
|
657
|
|
|
658 When class ``C2`` inherits from class ``C1``, it acquires all the field
|
|
|
659 definitions of ``C1``. As those definitions are merged into class ``C2``, any
|
|
|
660 template arguments passed to ``C1`` by ``C2`` are substituted into the
|
|
|
661 definitions. In other words, the abstract record fields defined by ``C1`` are
|
|
|
662 expanded with the template arguments before being merged into ``C2``.
|
|
|
663
|
|
|
664
|
|
|
665 .. _def:
|
|
|
666
|
|
|
667 ``def`` --- define a concrete record
|
|
|
668 ------------------------------------
|
|
|
669
|
|
|
670 A ``def`` statement defines a new concrete record.
|
|
|
671
|
|
|
672 .. productionlist::
|
|
|
673 Def: "def" [`NameValue`] `RecordBody`
|
|
|
674 NameValue: `Value` (parsed in a special mode)
|
|
|
675
|
|
|
676 The name value is optional. If specified, it is parsed in a special mode
|
|
|
677 where undefined (unrecognized) identifiers are interpreted as literal
|
|
|
678 strings. In particular, global identifiers are considered unrecognized.
|
|
|
679 These include global variables defined by ``defvar`` and ``defset``. A
|
|
|
680 record name can be the null string.
|
|
|
681
|
|
|
682 If no name value is given, the record is *anonymous*. The final name of an
|
|
|
683 anonymous record is unspecified but globally unique.
|
|
|
684
|
|
|
685 Special handling occurs if a ``def`` appears inside a ``multiclass``
|
|
|
686 statement. See the ``multiclass`` section below for details.
|
|
|
687
|
|
|
688 A record can inherit from one or more classes by specifying the
|
|
|
689 :token:`ParentClassList` clause at the beginning of its record body. All of
|
|
|
690 the fields in the parent classes are added to the record. If two or more
|
|
|
691 parent classes provide the same field, the record ends up with the field value
|
|
|
692 of the last parent class.
|
|
|
693
|
|
|
694 As a special case, the name of a record can be passed as a template argument
|
|
|
695 to that record's parent classes. For example:
|
|
|
696
|
|
|
697 .. code-block:: text
|
|
|
698
|
|
|
699 class A <dag d> {
|
|
|
700 dag the_dag = d;
|
|
|
701 }
|
|
|
702
|
|
236
|
703 def rec1 : A<(ops rec1)>;
|
|
221
|
704
|
|
|
705 The DAG ``(ops rec1)`` is passed as a template argument to class ``A``. Notice
|
|
|
706 that the DAG includes ``rec1``, the record being defined.
|
|
|
707
|
|
|
708 The steps taken to create a new record are somewhat complex. See `How
|
|
|
709 records are built`_.
|
|
|
710
|
|
|
711 See `Examples: classes and records`_ for examples.
|
|
|
712
|
|
|
713
|
|
|
714 Examples: classes and records
|
|
|
715 -----------------------------
|
|
|
716
|
|
|
717 Here is a simple TableGen file with one class and two record definitions.
|
|
|
718
|
|
|
719 .. code-block:: text
|
|
|
720
|
|
|
721 class C {
|
|
|
722 bit V = true;
|
|
|
723 }
|
|
|
724
|
|
|
725 def X : C;
|
|
|
726 def Y : C {
|
|
|
727 let V = false;
|
|
|
728 string Greeting = "Hello!";
|
|
|
729 }
|
|
|
730
|
|
|
731 First, the abstract class ``C`` is defined. It has one field named ``V``
|
|
|
732 that is a bit initialized to true.
|
|
|
733
|
|
|
734 Next, two records are defined, derived from class ``C``; that is, with ``C``
|
|
|
735 as their parent class. Thus they both inherit the ``V`` field. Record ``Y``
|
|
|
736 also defines another string field, ``Greeting``, which is initialized to
|
|
|
737 ``"Hello!"``. In addition, ``Y`` overrides the inherited ``V`` field,
|
|
|
738 setting it to false.
|
|
|
739
|
|
|
740 A class is useful for isolating the common features of multiple records in
|
|
|
741 one place. A class can initialize common fields to default values, but
|
|
|
742 records inheriting from that class can override the defaults.
|
|
|
743
|
|
|
744 TableGen supports the definition of parameterized classes as well as
|
|
|
745 nonparameterized ones. Parameterized classes specify a list of variable
|
|
|
746 declarations, which may optionally have defaults, that are bound when the
|
|
|
747 class is specified as a parent class of another class or record.
|
|
|
748
|
|
|
749 .. code-block:: text
|
|
|
750
|
|
|
751 class FPFormat <bits<3> val> {
|
|
|
752 bits<3> Value = val;
|
|
|
753 }
|
|
|
754
|
|
|
755 def NotFP : FPFormat<0>;
|
|
|
756 def ZeroArgFP : FPFormat<1>;
|
|
|
757 def OneArgFP : FPFormat<2>;
|
|
|
758 def OneArgFPRW : FPFormat<3>;
|
|
|
759 def TwoArgFP : FPFormat<4>;
|
|
|
760 def CompareFP : FPFormat<5>;
|
|
|
761 def CondMovFP : FPFormat<6>;
|
|
|
762 def SpecialFP : FPFormat<7>;
|
|
|
763
|
|
|
764 The purpose of the ``FPFormat`` class is to act as a sort of enumerated
|
|
|
765 type. It provides a single field, ``Value``, which holds a 3-bit number. Its
|
|
|
766 template argument, ``val``, is used to set the ``Value`` field. Each of the
|
|
|
767 eight records is defined with ``FPFormat`` as its parent class. The
|
|
|
768 enumeration value is passed in angle brackets as the template argument. Each
|
|
|
769 record will inherent the ``Value`` field with the appropriate enumeration
|
|
|
770 value.
|
|
|
771
|
|
|
772 Here is a more complex example of classes with template arguments. First, we
|
|
|
773 define a class similar to the ``FPFormat`` class above. It takes a template
|
|
|
774 argument and uses it to initialize a field named ``Value``. Then we define
|
|
|
775 four records that inherit the ``Value`` field with its four different
|
|
|
776 integer values.
|
|
|
777
|
|
|
778 .. code-block:: text
|
|
|
779
|
|
|
780 class ModRefVal <bits<2> val> {
|
|
|
781 bits<2> Value = val;
|
|
|
782 }
|
|
|
783
|
|
|
784 def None : ModRefVal<0>;
|
|
|
785 def Mod : ModRefVal<1>;
|
|
|
786 def Ref : ModRefVal<2>;
|
|
|
787 def ModRef : ModRefVal<3>;
|
|
|
788
|
|
|
789 This is somewhat contrived, but let's say we would like to examine the two
|
|
|
790 bits of the ``Value`` field independently. We can define a class that
|
|
|
791 accepts a ``ModRefVal`` record as a template argument and splits up its
|
|
|
792 value into two fields, one bit each. Then we can define records that inherit from
|
|
|
793 ``ModRefBits`` and so acquire two fields from it, one for each bit in the
|
|
|
794 ``ModRefVal`` record passed as the template argument.
|
|
|
795
|
|
|
796 .. code-block:: text
|
|
|
797
|
|
|
798 class ModRefBits <ModRefVal mrv> {
|
|
|
799 // Break the value up into its bits, which can provide a nice
|
|
|
800 // interface to the ModRefVal values.
|
|
|
801 bit isMod = mrv.Value{0};
|
|
|
802 bit isRef = mrv.Value{1};
|
|
|
803 }
|
|
|
804
|
|
|
805 // Example uses.
|
|
|
806 def foo : ModRefBits<Mod>;
|
|
|
807 def bar : ModRefBits<Ref>;
|
|
|
808 def snork : ModRefBits<ModRef>;
|
|
|
809
|
|
|
810 This illustrates how one class can be defined to reorganize the
|
|
|
811 fields in another class, thus hiding the internal representation of that
|
|
|
812 other class.
|
|
|
813
|
|
|
814 Running ``llvm-tblgen`` on the example prints the following definitions:
|
|
|
815
|
|
|
816 .. code-block:: text
|
|
|
817
|
|
|
818 def bar { // Value
|
|
|
819 bit isMod = 0;
|
|
|
820 bit isRef = 1;
|
|
|
821 }
|
|
|
822 def foo { // Value
|
|
|
823 bit isMod = 1;
|
|
|
824 bit isRef = 0;
|
|
|
825 }
|
|
|
826 def snork { // Value
|
|
|
827 bit isMod = 1;
|
|
|
828 bit isRef = 1;
|
|
|
829 }
|
|
|
830
|
|
|
831 ``let`` --- override fields in classes or records
|
|
|
832 -------------------------------------------------
|
|
|
833
|
|
|
834 A ``let`` statement collects a set of field values (sometimes called
|
|
|
835 *bindings*) and applies them to all the classes and records defined by
|
|
|
836 statements within the scope of the ``let``.
|
|
|
837
|
|
|
838 .. productionlist::
|
|
|
839 Let: "let" `LetList` "in" "{" `Statement`* "}"
|
|
|
840 :| "let" `LetList` "in" `Statement`
|
|
|
841 LetList: `LetItem` ("," `LetItem`)*
|
|
|
842 LetItem: `TokIdentifier` ["<" `RangeList` ">"] "=" `Value`
|
|
|
843
|
|
|
844 The ``let`` statement establishes a scope, which is a sequence of statements
|
|
|
845 in braces or a single statement with no braces. The bindings in the
|
|
|
846 :token:`LetList` apply to the statements in that scope.
|
|
|
847
|
|
|
848 The field names in the :token:`LetList` must name fields in classes inherited by
|
|
|
849 the classes and records defined in the statements. The field values are
|
|
|
850 applied to the classes and records *after* the records inherit all the fields from
|
|
|
851 their parent classes. So the ``let`` acts to override inherited field
|
|
|
852 values. A ``let`` cannot override the value of a template argument.
|
|
|
853
|
|
|
854 Top-level ``let`` statements are often useful when a few fields need to be
|
|
236
|
855 overridden in several records. Here are two examples. Note that ``let``
|
|
221
|
856 statements can be nested.
|
|
|
857
|
|
|
858 .. code-block:: text
|
|
|
859
|
|
|
860 let isTerminator = true, isReturn = true, isBarrier = true, hasCtrlDep = true in
|
|
|
861 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
|
|
|
862
|
|
|
863 let isCall = true in
|
|
|
864 // All calls clobber the non-callee saved registers...
|
|
|
865 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
|
|
|
866 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, XMM0, XMM1, XMM2,
|
|
|
867 XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
|
|
|
868 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst, variable_ops),
|
|
|
869 "call\t${dst:call}", []>;
|
|
|
870 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
|
|
|
871 "call\t{*}$dst", [(X86call GR32:$dst)]>;
|
|
|
872 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
|
|
|
873 "call\t{*}$dst", []>;
|
|
|
874 }
|
|
|
875
|
|
|
876 Note that a top-level ``let`` will not override fields defined in the classes or records
|
|
|
877 themselves.
|
|
|
878
|
|
|
879
|
|
|
880 ``multiclass`` --- define multiple records
|
|
|
881 ------------------------------------------
|
|
|
882
|
|
|
883 While classes with template arguments are a good way to factor out commonality
|
|
|
884 between multiple records, multiclasses allow a convenient method for
|
|
|
885 defining many records at once. For example, consider a 3-address
|
|
|
886 instruction architecture whose instructions come in two formats: ``reg = reg
|
|
|
887 op reg`` and ``reg = reg op imm`` (e.g., SPARC). We would like to specify in
|
|
|
888 one place that these two common formats exist, then in a separate place
|
|
|
889 specify what all the operations are. The ``multiclass`` and ``defm``
|
|
|
890 statements accomplish this goal. You can think of a multiclass as a macro or
|
|
|
891 template that expands into multiple records.
|
|
|
892
|
|
|
893 .. productionlist::
|
|
|
894 MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]
|
|
236
|
895 : `ParentClassList`
|
|
221
|
896 : "{" `MultiClassStatement`+ "}"
|
|
|
897 MultiClassID: `TokIdentifier`
|
|
|
898 MultiClassStatement: `Assert` | `Def` | `Defm` | `Defvar` | `Foreach` | `If` | `Let`
|
|
|
899
|
|
|
900 As with regular classes, the multiclass has a name and can accept template
|
|
|
901 arguments. A multiclass can inherit from other multiclasses, which causes
|
|
|
902 the other multiclasses to be expanded and contribute to the record
|
|
|
903 definitions in the inheriting multiclass. The body of the multiclass
|
|
|
904 contains a series of statements that define records, using :token:`Def` and
|
|
|
905 :token:`Defm`. In addition, :token:`Defvar`, :token:`Foreach`, and
|
|
|
906 :token:`Let` statements can be used to factor out even more common elements.
|
|
|
907 The :token:`If` and :token:`Assert` statements can also be used.
|
|
|
908
|
|
|
909 Also as with regular classes, the multiclass has the implicit template
|
|
|
910 argument ``NAME`` (see NAME_). When a named (non-anonymous) record is
|
|
|
911 defined in a multiclass and the record's name does not include a use of the
|
|
|
912 template argument ``NAME``, such a use is automatically *prepended*
|
|
|
913 to the name. That is, the following are equivalent inside a multiclass::
|
|
|
914
|
|
|
915 def Foo ...
|
|
|
916 def NAME # Foo ...
|
|
|
917
|
|
|
918 The records defined in a multiclass are created when the multiclass is
|
|
|
919 "instantiated" or "invoked" by a ``defm`` statement outside the multiclass
|
|
|
920 definition. Each ``def`` statement in the multiclass produces a record. As
|
|
|
921 with top-level ``def`` statements, these definitions can inherit from
|
|
|
922 multiple parent classes.
|
|
|
923
|
|
|
924 See `Examples: multiclasses and defms`_ for examples.
|
|
|
925
|
|
|
926
|
|
|
927 ``defm`` --- invoke multiclasses to define multiple records
|
|
|
928 -----------------------------------------------------------
|
|
|
929
|
|
|
930 Once multiclasses have been defined, you use the ``defm`` statement to
|
|
|
931 "invoke" them and process the multiple record definitions in those
|
|
236
|
932 multiclasses. Those record definitions are specified by ``def``
|
|
221
|
933 statements in the multiclasses, and indirectly by ``defm`` statements.
|
|
|
934
|
|
|
935 .. productionlist::
|
|
|
936 Defm: "defm" [`NameValue`] `ParentClassList` ";"
|
|
|
937
|
|
|
938 The optional :token:`NameValue` is formed in the same way as the name of a
|
|
|
939 ``def``. The :token:`ParentClassList` is a colon followed by a list of at
|
|
|
940 least one multiclass and any number of regular classes. The multiclasses
|
|
|
941 must precede the regular classes. Note that the ``defm`` does not have a
|
|
|
942 body.
|
|
|
943
|
|
|
944 This statement instantiates all the records defined in all the specified
|
|
|
945 multiclasses, either directly by ``def`` statements or indirectly by
|
|
|
946 ``defm`` statements. These records also receive the fields defined in any
|
|
|
947 regular classes included in the parent class list. This is useful for adding
|
|
|
948 a common set of fields to all the records created by the ``defm``.
|
|
|
949
|
|
|
950 The name is parsed in the same special mode used by ``def``. If the name is
|
|
|
951 not included, an unspecified but globally unique name is provided. That is,
|
|
|
952 the following examples end up with different names::
|
|
|
953
|
|
|
954 defm : SomeMultiClass<...>; // A globally unique name.
|
|
|
955 defm "" : SomeMultiClass<...>; // An empty name.
|
|
|
956
|
|
|
957 The ``defm`` statement can be used in a multiclass body. When this occurs,
|
|
|
958 the second variant is equivalent to::
|
|
|
959
|
|
|
960 defm NAME : SomeMultiClass<...>;
|
|
|
961
|
|
|
962 More generally, when ``defm`` occurs in a multiclass and its name does not
|
|
|
963 include a use of the implicit template argument ``NAME``, then ``NAME`` will
|
|
|
964 be prepended automatically. That is, the following are equivalent inside a
|
|
|
965 multiclass::
|
|
|
966
|
|
|
967 defm Foo : SomeMultiClass<...>;
|
|
|
968 defm NAME # Foo : SomeMultiClass<...>;
|
|
|
969
|
|
|
970 See `Examples: multiclasses and defms`_ for examples.
|
|
|
971
|
|
|
972 Examples: multiclasses and defms
|
|
|
973 --------------------------------
|
|
|
974
|
|
|
975 Here is a simple example using ``multiclass`` and ``defm``. Consider a
|
|
|
976 3-address instruction architecture whose instructions come in two formats:
|
|
|
977 ``reg = reg op reg`` and ``reg = reg op imm`` (immediate). The SPARC is an
|
|
|
978 example of such an architecture.
|
|
|
979
|
|
|
980 .. code-block:: text
|
|
|
981
|
|
|
982 def ops;
|
|
|
983 def GPR;
|
|
|
984 def Imm;
|
|
|
985 class inst <int opc, string asmstr, dag operandlist>;
|
|
|
986
|
|
|
987 multiclass ri_inst <int opc, string asmstr> {
|
|
|
988 def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
|
|
|
989 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
|
|
|
990 def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
|
|
|
991 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
|
|
|
992 }
|
|
|
993
|
|
|
994 // Define records for each instruction in the RR and RI formats.
|
|
|
995 defm ADD : ri_inst<0b111, "add">;
|
|
|
996 defm SUB : ri_inst<0b101, "sub">;
|
|
|
997 defm MUL : ri_inst<0b100, "mul">;
|
|
|
998
|
|
|
999 Each use of the ``ri_inst`` multiclass defines two records, one with the
|
|
|
1000 ``_rr`` suffix and one with ``_ri``. Recall that the name of the ``defm``
|
|
|
1001 that uses a multiclass is prepended to the names of the records defined in
|
|
|
1002 that multiclass. So the resulting definitions are named::
|
|
|
1003
|
|
|
1004 ADD_rr, ADD_ri
|
|
|
1005 SUB_rr, SUB_ri
|
|
|
1006 MUL_rr, MUL_ri
|
|
|
1007
|
|
|
1008 Without the ``multiclass`` feature, the instructions would have to be
|
|
|
1009 defined as follows.
|
|
|
1010
|
|
|
1011 .. code-block:: text
|
|
|
1012
|
|
|
1013 def ops;
|
|
|
1014 def GPR;
|
|
|
1015 def Imm;
|
|
|
1016 class inst <int opc, string asmstr, dag operandlist>;
|
|
|
1017
|
|
|
1018 class rrinst <int opc, string asmstr>
|
|
|
1019 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
|
|
|
1020 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
|
|
|
1021
|
|
|
1022 class riinst <int opc, string asmstr>
|
|
|
1023 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
|
|
|
1024 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
|
|
|
1025
|
|
|
1026 // Define records for each instruction in the RR and RI formats.
|
|
|
1027 def ADD_rr : rrinst<0b111, "add">;
|
|
|
1028 def ADD_ri : riinst<0b111, "add">;
|
|
|
1029 def SUB_rr : rrinst<0b101, "sub">;
|
|
|
1030 def SUB_ri : riinst<0b101, "sub">;
|
|
|
1031 def MUL_rr : rrinst<0b100, "mul">;
|
|
|
1032 def MUL_ri : riinst<0b100, "mul">;
|
|
|
1033
|
|
|
1034 A ``defm`` can be used in a multiclass to "invoke" other multiclasses and
|
|
|
1035 create the records defined in those multiclasses in addition to the records
|
|
|
1036 defined in the current multiclass. In the following example, the ``basic_s``
|
|
|
1037 and ``basic_p`` multiclasses contain ``defm`` statements that refer to the
|
|
|
1038 ``basic_r`` multiclass. The ``basic_r`` multiclass contains only ``def``
|
|
|
1039 statements.
|
|
|
1040
|
|
|
1041 .. code-block:: text
|
|
|
1042
|
|
|
1043 class Instruction <bits<4> opc, string Name> {
|
|
|
1044 bits<4> opcode = opc;
|
|
|
1045 string name = Name;
|
|
|
1046 }
|
|
|
1047
|
|
|
1048 multiclass basic_r <bits<4> opc> {
|
|
|
1049 def rr : Instruction<opc, "rr">;
|
|
|
1050 def rm : Instruction<opc, "rm">;
|
|
|
1051 }
|
|
|
1052
|
|
|
1053 multiclass basic_s <bits<4> opc> {
|
|
|
1054 defm SS : basic_r<opc>;
|
|
|
1055 defm SD : basic_r<opc>;
|
|
|
1056 def X : Instruction<opc, "x">;
|
|
|
1057 }
|
|
|
1058
|
|
|
1059 multiclass basic_p <bits<4> opc> {
|
|
|
1060 defm PS : basic_r<opc>;
|
|
|
1061 defm PD : basic_r<opc>;
|
|
|
1062 def Y : Instruction<opc, "y">;
|
|
|
1063 }
|
|
|
1064
|
|
|
1065 defm ADD : basic_s<0xf>, basic_p<0xf>;
|
|
|
1066
|
|
|
1067 The final ``defm`` creates the following records, five from the ``basic_s``
|
|
|
1068 multiclass and five from the ``basic_p`` multiclass::
|
|
|
1069
|
|
|
1070 ADDSSrr, ADDSSrm
|
|
|
1071 ADDSDrr, ADDSDrm
|
|
|
1072 ADDX
|
|
|
1073 ADDPSrr, ADDPSrm
|
|
|
1074 ADDPDrr, ADDPDrm
|
|
|
1075 ADDY
|
|
|
1076
|
|
|
1077 A ``defm`` statement, both at top level and in a multiclass, can inherit
|
|
|
1078 from regular classes in addition to multiclasses. The rule is that the
|
|
|
1079 regular classes must be listed after the multiclasses, and there must be at least
|
|
|
1080 one multiclass.
|
|
|
1081
|
|
|
1082 .. code-block:: text
|
|
|
1083
|
|
|
1084 class XD {
|
|
|
1085 bits<4> Prefix = 11;
|
|
|
1086 }
|
|
|
1087 class XS {
|
|
|
1088 bits<4> Prefix = 12;
|
|
|
1089 }
|
|
|
1090 class I <bits<4> op> {
|
|
|
1091 bits<4> opcode = op;
|
|
|
1092 }
|
|
|
1093
|
|
|
1094 multiclass R {
|
|
|
1095 def rr : I<4>;
|
|
|
1096 def rm : I<2>;
|
|
|
1097 }
|
|
|
1098
|
|
|
1099 multiclass Y {
|
|
|
1100 defm SS : R, XD; // First multiclass R, then regular class XD.
|
|
|
1101 defm SD : R, XS;
|
|
|
1102 }
|
|
|
1103
|
|
|
1104 defm Instr : Y;
|
|
|
1105
|
|
|
1106 This example will create four records, shown here in alphabetical order with
|
|
|
1107 their fields.
|
|
|
1108
|
|
|
1109 .. code-block:: text
|
|
|
1110
|
|
|
1111 def InstrSDrm {
|
|
|
1112 bits<4> opcode = { 0, 0, 1, 0 };
|
|
|
1113 bits<4> Prefix = { 1, 1, 0, 0 };
|
|
|
1114 }
|
|
|
1115
|
|
|
1116 def InstrSDrr {
|
|
|
1117 bits<4> opcode = { 0, 1, 0, 0 };
|
|
|
1118 bits<4> Prefix = { 1, 1, 0, 0 };
|
|
|
1119 }
|
|
|
1120
|
|
|
1121 def InstrSSrm {
|
|
|
1122 bits<4> opcode = { 0, 0, 1, 0 };
|
|
|
1123 bits<4> Prefix = { 1, 0, 1, 1 };
|
|
|
1124 }
|
|
|
1125
|
|
|
1126 def InstrSSrr {
|
|
|
1127 bits<4> opcode = { 0, 1, 0, 0 };
|
|
|
1128 bits<4> Prefix = { 1, 0, 1, 1 };
|
|
|
1129 }
|
|
|
1130
|
|
|
1131 It's also possible to use ``let`` statements inside multiclasses, providing
|
|
|
1132 another way to factor out commonality from the records, especially when
|
|
|
1133 using several levels of multiclass instantiations.
|
|
|
1134
|
|
|
1135 .. code-block:: text
|
|
|
1136
|
|
|
1137 multiclass basic_r <bits<4> opc> {
|
|
|
1138 let Predicates = [HasSSE2] in {
|
|
|
1139 def rr : Instruction<opc, "rr">;
|
|
|
1140 def rm : Instruction<opc, "rm">;
|
|
|
1141 }
|
|
|
1142 let Predicates = [HasSSE3] in
|
|
|
1143 def rx : Instruction<opc, "rx">;
|
|
|
1144 }
|
|
|
1145
|
|
|
1146 multiclass basic_ss <bits<4> opc> {
|
|
|
1147 let IsDouble = false in
|
|
|
1148 defm SS : basic_r<opc>;
|
|
|
1149
|
|
|
1150 let IsDouble = true in
|
|
|
1151 defm SD : basic_r<opc>;
|
|
|
1152 }
|
|
|
1153
|
|
|
1154 defm ADD : basic_ss<0xf>;
|
|
|
1155
|
|
|
1156
|
|
|
1157 ``defset`` --- create a definition set
|
|
|
1158 --------------------------------------
|
|
|
1159
|
|
|
1160 The ``defset`` statement is used to collect a set of records into a global
|
|
|
1161 list of records.
|
|
|
1162
|
|
|
1163 .. productionlist::
|
|
|
1164 Defset: "defset" `Type` `TokIdentifier` "=" "{" `Statement`* "}"
|
|
|
1165
|
|
|
1166 All records defined inside the braces via ``def`` and ``defm`` are defined
|
|
|
1167 as usual, and they are also collected in a global list of the given name
|
|
|
1168 (:token:`TokIdentifier`).
|
|
|
1169
|
|
|
1170 The specified type must be ``list<``\ *class*\ ``>``, where *class* is some
|
|
|
1171 record class. The ``defset`` statement establishes a scope for its
|
|
|
1172 statements. It is an error to define a record in the scope of the
|
|
|
1173 ``defset`` that is not of type *class*.
|
|
|
1174
|
|
|
1175 The ``defset`` statement can be nested. The inner ``defset`` adds the
|
|
|
1176 records to its own set, and all those records are also added to the outer
|
|
|
1177 set.
|
|
|
1178
|
|
|
1179 Anonymous records created inside initialization expressions using the
|
|
|
1180 ``ClassID<...>`` syntax are not collected in the set.
|
|
|
1181
|
|
|
1182
|
|
|
1183 ``defvar`` --- define a variable
|
|
|
1184 --------------------------------
|
|
|
1185
|
|
|
1186 A ``defvar`` statement defines a global variable. Its value can be used
|
|
|
1187 throughout the statements that follow the definition.
|
|
|
1188
|
|
|
1189 .. productionlist::
|
|
|
1190 Defvar: "defvar" `TokIdentifier` "=" `Value` ";"
|
|
|
1191
|
|
|
1192 The identifier on the left of the ``=`` is defined to be a global variable
|
|
|
1193 whose value is given by the value expression on the right of the ``=``. The
|
|
|
1194 type of the variable is automatically inferred.
|
|
|
1195
|
|
|
1196 Once a variable has been defined, it cannot be set to another value.
|
|
|
1197
|
|
|
1198 Variables defined in a top-level ``foreach`` go out of scope at the end of
|
|
|
1199 each loop iteration, so their value in one iteration is not available in
|
|
|
1200 the next iteration. The following ``defvar`` will not work::
|
|
|
1201
|
|
236
|
1202 defvar i = !add(i, 1);
|
|
221
|
1203
|
|
|
1204 Variables can also be defined with ``defvar`` in a record body. See
|
|
|
1205 `Defvar in a Record Body`_ for more details.
|
|
|
1206
|
|
|
1207 ``foreach`` --- iterate over a sequence of statements
|
|
|
1208 -----------------------------------------------------
|
|
|
1209
|
|
|
1210 The ``foreach`` statement iterates over a series of statements, varying a
|
|
|
1211 variable over a sequence of values.
|
|
|
1212
|
|
|
1213 .. productionlist::
|
|
|
1214 Foreach: "foreach" `ForeachIterator` "in" "{" `Statement`* "}"
|
|
|
1215 :| "foreach" `ForeachIterator` "in" `Statement`
|
|
|
1216 ForeachIterator: `TokIdentifier` "=" ("{" `RangeList` "}" | `RangePiece` | `Value`)
|
|
|
1217
|
|
|
1218 The body of the ``foreach`` is a series of statements in braces or a
|
|
|
1219 single statement with no braces. The statements are re-evaluated once for
|
|
|
1220 each value in the range list, range piece, or single value. On each
|
|
|
1221 iteration, the :token:`TokIdentifier` variable is set to the value and can
|
|
|
1222 be used in the statements.
|
|
|
1223
|
|
|
1224 The statement list establishes an inner scope. Variables local to a
|
|
|
1225 ``foreach`` go out of scope at the end of each loop iteration, so their
|
|
|
1226 values do not carry over from one iteration to the next. Foreach loops may
|
|
|
1227 be nested.
|
|
|
1228
|
|
|
1229 .. Note that the productions involving RangeList and RangePiece have precedence
|
|
|
1230 over the more generic value parsing based on the first token.
|
|
|
1231
|
|
|
1232 .. code-block:: text
|
|
|
1233
|
|
|
1234 foreach i = [0, 1, 2, 3] in {
|
|
|
1235 def R#i : Register<...>;
|
|
|
1236 def F#i : Register<...>;
|
|
|
1237 }
|
|
|
1238
|
|
|
1239 This loop defines records named ``R0``, ``R1``, ``R2``, and ``R3``, along
|
|
|
1240 with ``F0``, ``F1``, ``F2``, and ``F3``.
|
|
|
1241
|
|
|
1242
|
|
|
1243 ``if`` --- select statements based on a test
|
|
|
1244 --------------------------------------------
|
|
|
1245
|
|
|
1246 The ``if`` statement allows one of two statement groups to be selected based
|
|
|
1247 on the value of an expression.
|
|
|
1248
|
|
|
1249 .. productionlist::
|
|
|
1250 If: "if" `Value` "then" `IfBody`
|
|
|
1251 :| "if" `Value` "then" `IfBody` "else" `IfBody`
|
|
|
1252 IfBody: "{" `Statement`* "}" | `Statement`
|
|
|
1253
|
|
|
1254 The value expression is evaluated. If it evaluates to true (in the same
|
|
|
1255 sense used by the bang operators), then the statements following the
|
|
|
1256 ``then`` reserved word are processed. Otherwise, if there is an ``else``
|
|
|
1257 reserved word, the statements following the ``else`` are processed. If the
|
|
|
1258 value is false and there is no ``else`` arm, no statements are processed.
|
|
|
1259
|
|
|
1260 Because the braces around the ``then`` statements are optional, this grammar rule
|
|
|
1261 has the usual ambiguity with "dangling else" clauses, and it is resolved in
|
|
|
1262 the usual way: in a case like ``if v1 then if v2 then {...} else {...}``, the
|
|
|
1263 ``else`` associates with the inner ``if`` rather than the outer one.
|
|
|
1264
|
|
|
1265 The :token:`IfBody` of the then and else arms of the ``if`` establish an
|
|
|
1266 inner scope. Any ``defvar`` variables defined in the bodies go out of scope
|
|
|
1267 when the bodies are finished (see `Defvar in a Record Body`_ for more details).
|
|
|
1268
|
|
|
1269 The ``if`` statement can also be used in a record :token:`Body`.
|
|
|
1270
|
|
|
1271
|
|
|
1272 ``assert`` --- check that a condition is true
|
|
|
1273 ---------------------------------------------
|
|
|
1274
|
|
|
1275 The ``assert`` statement checks a boolean condition to be sure that it is true
|
|
|
1276 and prints an error message if it is not.
|
|
|
1277
|
|
|
1278 .. productionlist::
|
|
|
1279 Assert: "assert" `condition` "," `message` ";"
|
|
|
1280
|
|
|
1281 If the boolean condition is true, the statement does nothing. If the
|
|
|
1282 condition is false, it prints a nonfatal error message. The **message**, which
|
|
|
1283 can be an arbitrary string expression, is included in the error message as a
|
|
|
1284 note. The exact behavior of the ``assert`` statement depends on its
|
|
|
1285 placement.
|
|
|
1286
|
|
|
1287 * At top level, the assertion is checked immediately.
|
|
|
1288
|
|
|
1289 * In a record definition, the statement is saved and all assertions are
|
|
|
1290 checked after the record is completely built.
|
|
|
1291
|
|
|
1292 * In a class definition, the assertions are saved and inherited by all
|
|
|
1293 the subclasses and records that inherit from the class. The assertions are
|
|
|
1294 then checked when the records are completely built.
|
|
|
1295
|
|
|
1296 * In a multiclass definition, the assertions are saved with the other
|
|
|
1297 components of the multiclass and then checked each time the multiclass
|
|
|
1298 is instantiated with ``defm``.
|
|
|
1299
|
|
|
1300 Using assertions in TableGen files can simplify record checking in TableGen
|
|
|
1301 backends. Here is an example of an ``assert`` in two class definitions.
|
|
|
1302
|
|
|
1303 .. code-block:: text
|
|
|
1304
|
|
|
1305 class PersonName<string name> {
|
|
|
1306 assert !le(!size(name), 32), "person name is too long: " # name;
|
|
|
1307 string Name = name;
|
|
|
1308 }
|
|
|
1309
|
|
|
1310 class Person<string name, int age> : PersonName<name> {
|
|
|
1311 assert !and(!ge(age, 1), !le(age, 120)), "person age is invalid: " # age;
|
|
|
1312 int Age = age;
|
|
|
1313 }
|
|
|
1314
|
|
|
1315 def Rec20 : Person<"Donald Knuth", 60> {
|
|
|
1316 ...
|
|
|
1317 }
|
|
|
1318
|
|
|
1319
|
|
|
1320 Additional Details
|
|
|
1321 ==================
|
|
|
1322
|
|
|
1323 Directed acyclic graphs (DAGs)
|
|
|
1324 ------------------------------
|
|
|
1325
|
|
|
1326 A directed acyclic graph can be represented directly in TableGen using the
|
|
|
1327 ``dag`` datatype. A DAG node consists of an operator and zero or more
|
|
|
1328 arguments (or operands). Each argument can be of any desired type. By using
|
|
|
1329 another DAG node as an argument, an arbitrary graph of DAG nodes can be
|
|
236
|
1330 built.
|
|
221
|
1331
|
|
|
1332 The syntax of a ``dag`` instance is:
|
|
|
1333
|
|
|
1334 ``(`` *operator* *argument1*\ ``,`` *argument2*\ ``,`` ... ``)``
|
|
|
1335
|
|
|
1336 The operator must be present and must be a record. There can be zero or more
|
|
|
1337 arguments, separated by commas. The operator and arguments can have three
|
|
236
|
1338 formats.
|
|
221
|
1339
|
|
|
1340 ====================== =============================================
|
|
|
1341 Format Meaning
|
|
|
1342 ====================== =============================================
|
|
|
1343 *value* argument value
|
|
|
1344 *value*\ ``:``\ *name* argument value and associated name
|
|
|
1345 *name* argument name with unset (uninitialized) value
|
|
|
1346 ====================== =============================================
|
|
|
1347
|
|
|
1348 The *value* can be any TableGen value. The *name*, if present, must be a
|
|
|
1349 :token:`TokVarName`, which starts with a dollar sign (``$``). The purpose of
|
|
|
1350 a name is to tag an operator or argument in a DAG with a particular meaning,
|
|
|
1351 or to associate an argument in one DAG with a like-named argument in another
|
|
|
1352 DAG.
|
|
|
1353
|
|
|
1354 The following bang operators are useful for working with DAGs:
|
|
|
1355 ``!con``, ``!dag``, ``!empty``, ``!foreach``, ``!getdagop``, ``!setdagop``, ``!size``.
|
|
|
1356
|
|
|
1357 Defvar in a record body
|
|
|
1358 -----------------------
|
|
|
1359
|
|
|
1360 In addition to defining global variables, the ``defvar`` statement can
|
|
|
1361 be used inside the :token:`Body` of a class or record definition to define
|
|
|
1362 local variables. The scope of the variable extends from the ``defvar``
|
|
|
1363 statement to the end of the body. It cannot be set to a different value
|
|
|
1364 within its scope. The ``defvar`` statement can also be used in the statement
|
|
|
1365 list of a ``foreach``, which establishes a scope.
|
|
|
1366
|
|
|
1367 A variable named ``V`` in an inner scope shadows (hides) any variables ``V``
|
|
|
1368 in outer scopes. In particular, ``V`` in a record body shadows a global
|
|
|
1369 ``V``, and ``V`` in a ``foreach`` statement list shadows any ``V`` in
|
|
|
1370 surrounding record or global scopes.
|
|
|
1371
|
|
|
1372 Variables defined in a ``foreach`` go out of scope at the end of
|
|
|
1373 each loop iteration, so their value in one iteration is not available in
|
|
|
1374 the next iteration. The following ``defvar`` will not work::
|
|
|
1375
|
|
|
1376 defvar i = !add(i, 1)
|
|
|
1377
|
|
|
1378 How records are built
|
|
|
1379 ---------------------
|
|
|
1380
|
|
|
1381 The following steps are taken by TableGen when a record is built. Classes are simply
|
|
|
1382 abstract records and so go through the same steps.
|
|
|
1383
|
|
|
1384 1. Build the record name (:token:`NameValue`) and create an empty record.
|
|
|
1385
|
|
|
1386 2. Parse the parent classes in the :token:`ParentClassList` from left to
|
|
|
1387 right, visiting each parent class's ancestor classes from top to bottom.
|
|
|
1388
|
|
|
1389 a. Add the fields from the parent class to the record.
|
|
|
1390 b. Substitute the template arguments into those fields.
|
|
|
1391 c. Add the parent class to the record's list of inherited classes.
|
|
|
1392
|
|
|
1393 3. Apply any top-level ``let`` bindings to the record. Recall that top-level
|
|
|
1394 bindings only apply to inherited fields.
|
|
|
1395
|
|
|
1396 4. Parse the body of the record.
|
|
|
1397
|
|
|
1398 * Add any fields to the record.
|
|
|
1399 * Modify the values of fields according to local ``let`` statements.
|
|
|
1400 * Define any ``defvar`` variables.
|
|
|
1401
|
|
|
1402 5. Make a pass over all the fields to resolve any inter-field references.
|
|
|
1403
|
|
236
|
1404 6. Add the record to the final record list.
|
|
221
|
1405
|
|
|
1406 Because references between fields are resolved (step 5) after ``let`` bindings are
|
|
|
1407 applied (step 3), the ``let`` statement has unusual power. For example:
|
|
|
1408
|
|
|
1409 .. code-block:: text
|
|
|
1410
|
|
|
1411 class C <int x> {
|
|
|
1412 int Y = x;
|
|
|
1413 int Yplus1 = !add(Y, 1);
|
|
|
1414 int xplus1 = !add(x, 1);
|
|
|
1415 }
|
|
|
1416
|
|
|
1417 let Y = 10 in {
|
|
|
1418 def rec1 : C<5> {
|
|
|
1419 }
|
|
|
1420 }
|
|
|
1421
|
|
|
1422 def rec2 : C<5> {
|
|
|
1423 let Y = 10;
|
|
|
1424 }
|
|
|
1425
|
|
|
1426 In both cases, one where a top-level ``let`` is used to bind ``Y`` and one
|
|
|
1427 where a local ``let`` does the same thing, the results are:
|
|
|
1428
|
|
|
1429 .. code-block:: text
|
|
|
1430
|
|
|
1431 def rec1 { // C
|
|
|
1432 int Y = 10;
|
|
|
1433 int Yplus1 = 11;
|
|
|
1434 int xplus1 = 6;
|
|
|
1435 }
|
|
|
1436 def rec2 { // C
|
|
|
1437 int Y = 10;
|
|
|
1438 int Yplus1 = 11;
|
|
|
1439 int xplus1 = 6;
|
|
|
1440 }
|
|
|
1441
|
|
|
1442 ``Yplus1`` is 11 because the ``let Y`` is performed before the ``!add(Y,
|
|
|
1443 1)`` is resolved. Use this power wisely.
|
|
|
1444
|
|
|
1445
|
|
|
1446 Using Classes as Subroutines
|
|
|
1447 ============================
|
|
|
1448
|
|
|
1449 As described in `Simple values`_, a class can be invoked in an expression
|
|
|
1450 and passed template arguments. This causes TableGen to create a new anonymous
|
|
|
1451 record inheriting from that class. As usual, the record receives all the
|
|
|
1452 fields defined in the class.
|
|
|
1453
|
|
|
1454 This feature can be employed as a simple subroutine facility. The class can
|
|
|
1455 use the template arguments to define various variables and fields, which end
|
|
|
1456 up in the anonymous record. Those fields can then be retrieved in the
|
|
|
1457 expression invoking the class as follows. Assume that the field ``ret``
|
|
|
1458 contains the final value of the subroutine.
|
|
|
1459
|
|
|
1460 .. code-block:: text
|
|
|
1461
|
|
|
1462 int Result = ... CalcValue<arg>.ret ...;
|
|
|
1463
|
|
|
1464 The ``CalcValue`` class is invoked with the template argument ``arg``. It
|
|
|
1465 calculates a value for the ``ret`` field, which is then retrieved at the
|
|
|
1466 "point of call" in the initialization for the Result field. The anonymous
|
|
|
1467 record created in this example serves no other purpose than to carry the
|
|
|
1468 result value.
|
|
|
1469
|
|
|
1470 Here is a practical example. The class ``isValidSize`` determines whether a
|
|
|
1471 specified number of bytes represents a valid data size. The bit ``ret`` is
|
|
|
1472 set appropriately. The field ``ValidSize`` obtains its initial value by
|
|
|
1473 invoking ``isValidSize`` with the data size and retrieving the ``ret`` field
|
|
|
1474 from the resulting anonymous record.
|
|
|
1475
|
|
|
1476 .. code-block:: text
|
|
|
1477
|
|
|
1478 class isValidSize<int size> {
|
|
|
1479 bit ret = !cond(!eq(size, 1): 1,
|
|
|
1480 !eq(size, 2): 1,
|
|
|
1481 !eq(size, 4): 1,
|
|
|
1482 !eq(size, 8): 1,
|
|
|
1483 !eq(size, 16): 1,
|
|
|
1484 true: 0);
|
|
|
1485 }
|
|
|
1486
|
|
|
1487 def Data1 {
|
|
|
1488 int Size = ...;
|
|
|
1489 bit ValidSize = isValidSize<Size>.ret;
|
|
|
1490 }
|
|
|
1491
|
|
|
1492 Preprocessing Facilities
|
|
|
1493 ========================
|
|
|
1494
|
|
|
1495 The preprocessor embedded in TableGen is intended only for simple
|
|
|
1496 conditional compilation. It supports the following directives, which are
|
|
|
1497 specified somewhat informally.
|
|
|
1498
|
|
|
1499 .. productionlist::
|
|
|
1500 LineBegin: beginning of line
|
|
|
1501 LineEnd: newline | return | EOF
|
|
|
1502 WhiteSpace: space | tab
|
|
|
1503 CComment: "/*" ... "*/"
|
|
|
1504 BCPLComment: "//" ... `LineEnd`
|
|
|
1505 WhiteSpaceOrCComment: `WhiteSpace` | `CComment`
|
|
|
1506 WhiteSpaceOrAnyComment: `WhiteSpace` | `CComment` | `BCPLComment`
|
|
|
1507 MacroName: `ualpha` (`ualpha` | "0"..."9")*
|
|
|
1508 PreDefine: `LineBegin` (`WhiteSpaceOrCComment`)*
|
|
|
1509 : "#define" (`WhiteSpace`)+ `MacroName`
|
|
|
1510 : (`WhiteSpaceOrAnyComment`)* `LineEnd`
|
|
|
1511 PreIfdef: `LineBegin` (`WhiteSpaceOrCComment`)*
|
|
|
1512 : ("#ifdef" | "#ifndef") (`WhiteSpace`)+ `MacroName`
|
|
|
1513 : (`WhiteSpaceOrAnyComment`)* `LineEnd`
|
|
|
1514 PreElse: `LineBegin` (`WhiteSpaceOrCComment`)*
|
|
|
1515 : "#else" (`WhiteSpaceOrAnyComment`)* `LineEnd`
|
|
|
1516 PreEndif: `LineBegin` (`WhiteSpaceOrCComment`)*
|
|
|
1517 : "#endif" (`WhiteSpaceOrAnyComment`)* `LineEnd`
|
|
|
1518
|
|
|
1519 ..
|
|
|
1520 PreRegContentException: `PreIfdef` | `PreElse` | `PreEndif` | EOF
|
|
|
1521 PreRegion: .* - `PreRegContentException`
|
|
|
1522 :| `PreIfdef`
|
|
|
1523 : (`PreRegion`)*
|
|
|
1524 : [`PreElse`]
|
|
|
1525 : (`PreRegion`)*
|
|
|
1526 : `PreEndif`
|
|
|
1527
|
|
|
1528 A :token:`MacroName` can be defined anywhere in a TableGen file. The name has
|
|
|
1529 no value; it can only be tested to see whether it is defined.
|
|
|
1530
|
|
|
1531 A macro test region begins with an ``#ifdef`` or ``#ifndef`` directive. If
|
|
|
1532 the macro name is defined (``#ifdef``) or undefined (``#ifndef``), then the
|
|
|
1533 source code between the directive and the corresponding ``#else`` or
|
|
|
1534 ``#endif`` is processed. If the test fails but there is an ``#else``
|
|
|
1535 clause, the source code between the ``#else`` and the ``#endif`` is
|
|
|
1536 processed. If the test fails and there is no ``#else`` clause, then no
|
|
|
1537 source code in the test region is processed.
|
|
|
1538
|
|
|
1539 Test regions may be nested, but they must be properly nested. A region
|
|
|
1540 started in a file must end in that file; that is, must have its
|
|
|
1541 ``#endif`` in the same file.
|
|
|
1542
|
|
|
1543 A :token:`MacroName` may be defined externally using the ``-D`` option on the
|
|
|
1544 ``*-tblgen`` command line::
|
|
|
1545
|
|
|
1546 llvm-tblgen self-reference.td -Dmacro1 -Dmacro3
|
|
|
1547
|
|
|
1548 Appendix A: Bang Operators
|
|
|
1549 ==========================
|
|
|
1550
|
|
|
1551 Bang operators act as functions in value expressions. A bang operator takes
|
|
|
1552 one or more arguments, operates on them, and produces a result. If the
|
|
|
1553 operator produces a boolean result, the result value will be 1 for true or 0
|
|
|
1554 for false. When an operator tests a boolean argument, it interprets 0 as false
|
|
|
1555 and non-0 as true.
|
|
|
1556
|
|
|
1557 .. warning::
|
|
|
1558 The ``!getop`` and ``!setop`` bang operators are deprecated in favor of
|
|
|
1559 ``!getdagop`` and ``!setdagop``.
|
|
|
1560
|
|
|
1561 ``!add(``\ *a*\ ``,`` *b*\ ``, ...)``
|
|
|
1562 This operator adds *a*, *b*, etc., and produces the sum.
|
|
|
1563
|
|
|
1564 ``!and(``\ *a*\ ``,`` *b*\ ``, ...)``
|
|
|
1565 This operator does a bitwise AND on *a*, *b*, etc., and produces the
|
|
|
1566 result. A logical AND can be performed if all the arguments are either
|
|
|
1567 0 or 1.
|
|
|
1568
|
|
|
1569 ``!cast<``\ *type*\ ``>(``\ *a*\ ``)``
|
|
|
1570 This operator performs a cast on *a* and produces the result.
|
|
|
1571 If *a* is not a string, then a straightforward cast is performed, say
|
|
|
1572 between an ``int`` and a ``bit``, or between record types. This allows
|
|
|
1573 casting a record to a class. If a record is cast to ``string``, the
|
|
|
1574 record's name is produced.
|
|
|
1575
|
|
|
1576 If *a* is a string, then it is treated as a record name and looked up in
|
|
|
1577 the list of all defined records. The resulting record is expected to be of
|
|
|
1578 the specified *type*.
|
|
|
1579
|
|
|
1580 For example, if ``!cast<``\ *type*\ ``>(``\ *name*\ ``)``
|
|
|
1581 appears in a multiclass definition, or in a
|
|
|
1582 class instantiated inside a multiclass definition, and the *name* does not
|
|
|
1583 reference any template arguments of the multiclass, then a record by
|
|
|
1584 that name must have been instantiated earlier
|
|
|
1585 in the source file. If *name* does reference
|
|
|
1586 a template argument, then the lookup is delayed until ``defm`` statements
|
|
|
1587 instantiating the multiclass (or later, if the defm occurs in another
|
|
|
1588 multiclass and template arguments of the inner multiclass that are
|
|
|
1589 referenced by *name* are substituted by values that themselves contain
|
|
|
1590 references to template arguments of the outer multiclass).
|
|
|
1591
|
|
|
1592 If the type of *a* does not match *type*, TableGen raises an error.
|
|
|
1593
|
|
|
1594 ``!con(``\ *a*\ ``,`` *b*\ ``, ...)``
|
|
|
1595 This operator concatenates the DAG nodes *a*, *b*, etc. Their operations
|
|
|
1596 must equal.
|
|
|
1597
|
|
|
1598 ``!con((op a1:$name1, a2:$name2), (op b1:$name3))``
|
|
|
1599
|
|
|
1600 results in the DAG node ``(op a1:$name1, a2:$name2, b1:$name3)``.
|
|
|
1601
|
|
|
1602 ``!cond(``\ *cond1* ``:`` *val1*\ ``,`` *cond2* ``:`` *val2*\ ``, ...,`` *condn* ``:`` *valn*\ ``)``
|
|
|
1603 This operator tests *cond1* and returns *val1* if the result is true.
|
|
|
1604 If false, the operator tests *cond2* and returns *val2* if the result is
|
|
|
1605 true. And so forth. An error is reported if no conditions are true.
|
|
|
1606
|
|
|
1607 This example produces the sign word for an integer::
|
|
|
1608
|
|
|
1609 !cond(!lt(x, 0) : "negative", !eq(x, 0) : "zero", true : "positive")
|
|
|
1610
|
|
|
1611 ``!dag(``\ *op*\ ``,`` *arguments*\ ``,`` *names*\ ``)``
|
|
|
1612 This operator creates a DAG node with the given operator and
|
|
|
1613 arguments. The *arguments* and *names* arguments must be lists
|
|
|
1614 of equal length or uninitialized (``?``). The *names* argument
|
|
|
1615 must be of type ``list<string>``.
|
|
|
1616
|
|
|
1617 Due to limitations of the type system, *arguments* must be a list of items
|
|
|
1618 of a common type. In practice, this means that they should either have the
|
|
|
1619 same type or be records with a common parent class. Mixing ``dag`` and
|
|
|
1620 non-``dag`` items is not possible. However, ``?`` can be used.
|
|
|
1621
|
|
|
1622 Example: ``!dag(op, [a1, a2, ?], ["name1", "name2", "name3"])`` results in
|
|
|
1623 ``(op a1-value:$name1, a2-value:$name2, ?:$name3)``.
|
|
|
1624
|
|
236
|
1625 ``!div(``\ *a*\ ``,`` *b*\ ``)``
|
|
|
1626 This operator preforms signed division of *a* by *b*, and produces the quotient.
|
|
|
1627 Division by 0 produces an error. Division of INT64_MIN by -1 produces an error.
|
|
|
1628
|
|
221
|
1629 ``!empty(``\ *a*\ ``)``
|
|
|
1630 This operator produces 1 if the string, list, or DAG *a* is empty; 0 otherwise.
|
|
|
1631 A dag is empty if it has no arguments; the operator does not count.
|
|
|
1632
|
|
|
1633 ``!eq(`` *a*\ `,` *b*\ ``)``
|
|
|
1634 This operator produces 1 if *a* is equal to *b*; 0 otherwise.
|
|
236
|
1635 The arguments must be ``bit``, ``bits``, ``int``, ``string``, or
|
|
221
|
1636 record values. Use ``!cast<string>`` to compare other types of objects.
|
|
|
1637
|
|
|
1638 ``!filter(``\ *var*\ ``,`` *list*\ ``,`` *predicate*\ ``)``
|
|
|
1639
|
|
|
1640 This operator creates a new ``list`` by filtering the elements in
|
|
|
1641 *list*. To perform the filtering, TableGen binds the variable *var* to each
|
|
|
1642 element and then evaluates the *predicate* expression, which presumably
|
|
|
1643 refers to *var*. The predicate must
|
|
|
1644 produce a boolean value (``bit``, ``bits``, or ``int``). The value is
|
|
|
1645 interpreted as with ``!if``:
|
|
|
1646 if the value is 0, the element is not included in the new list. If the value
|
|
|
1647 is anything else, the element is included.
|
|
|
1648
|
|
|
1649 ``!find(``\ *string1*\ ``,`` *string2*\ [``,`` *start*]\ ``)``
|
|
|
1650 This operator searches for *string2* in *string1* and produces its
|
|
|
1651 position. The starting position of the search may be specified by *start*,
|
|
|
1652 which can range between 0 and the length of *string1*; the default is 0.
|
|
|
1653 If the string is not found, the result is -1.
|
|
|
1654
|
|
|
1655 ``!foldl(``\ *init*\ ``,`` *list*\ ``,`` *acc*\ ``,`` *var*\ ``,`` *expr*\ ``)``
|
|
|
1656 This operator performs a left-fold over the items in *list*. The
|
|
|
1657 variable *acc* acts as the accumulator and is initialized to *init*.
|
|
|
1658 The variable *var* is bound to each element in the *list*. The
|
|
|
1659 expression is evaluated for each element and presumably uses *acc* and
|
|
|
1660 *var* to calculate the accumulated value, which ``!foldl`` stores back in
|
|
|
1661 *acc*. The type of *acc* is the same as *init*; the type of *var* is the
|
|
|
1662 same as the elements of *list*; *expr* must have the same type as *init*.
|
|
|
1663
|
|
|
1664 The following example computes the total of the ``Number`` field in the
|
|
|
1665 list of records in ``RecList``::
|
|
|
1666
|
|
|
1667 int x = !foldl(0, RecList, total, rec, !add(total, rec.Number));
|
|
|
1668
|
|
|
1669 If your goal is to filter the list and produce a new list that includes only
|
|
|
1670 some of the elements, see ``!filter``.
|
|
|
1671
|
|
|
1672 ``!foreach(``\ *var*\ ``,`` *sequence*\ ``,`` *expr*\ ``)``
|
|
|
1673 This operator creates a new ``list``/``dag`` in which each element is a
|
|
|
1674 function of the corresponding element in the *sequence* ``list``/``dag``.
|
|
|
1675 To perform the function, TableGen binds the variable *var* to an element
|
|
|
1676 and then evaluates the expression. The expression presumably refers
|
|
|
1677 to the variable *var* and calculates the result value.
|
|
|
1678
|
|
|
1679 If you simply want to create a list of a certain length containing
|
|
|
1680 the same value repeated multiple times, see ``!listsplat``.
|
|
|
1681
|
|
|
1682 ``!ge(``\ *a*\ `,` *b*\ ``)``
|
|
|
1683 This operator produces 1 if *a* is greater than or equal to *b*; 0 otherwise.
|
|
|
1684 The arguments must be ``bit``, ``bits``, ``int``, or ``string`` values.
|
|
|
1685
|
|
|
1686 ``!getdagop(``\ *dag*\ ``)`` --or-- ``!getdagop<``\ *type*\ ``>(``\ *dag*\ ``)``
|
|
|
1687 This operator produces the operator of the given *dag* node.
|
|
|
1688 Example: ``!getdagop((foo 1, 2))`` results in ``foo``. Recall that
|
|
|
1689 DAG operators are always records.
|
|
|
1690
|
|
|
1691 The result of ``!getdagop`` can be used directly in a context where
|
|
|
1692 any record class at all is acceptable (typically placing it into
|
|
|
1693 another dag value). But in other contexts, it must be explicitly
|
|
|
1694 cast to a particular class. The ``<``\ *type*\ ``>`` syntax is
|
|
|
1695 provided to make this easy.
|
|
|
1696
|
|
|
1697 For example, to assign the result to a value of type ``BaseClass``, you
|
|
|
1698 could write either of these::
|
|
|
1699
|
|
|
1700 BaseClass b = !getdagop<BaseClass>(someDag);
|
|
|
1701 BaseClass b = !cast<BaseClass>(!getdagop(someDag));
|
|
|
1702
|
|
|
1703 But to create a new DAG node that reuses the operator from another, no
|
|
|
1704 cast is necessary::
|
|
|
1705
|
|
|
1706 dag d = !dag(!getdagop(someDag), args, names);
|
|
|
1707
|
|
|
1708 ``!gt(``\ *a*\ `,` *b*\ ``)``
|
|
|
1709 This operator produces 1 if *a* is greater than *b*; 0 otherwise.
|
|
|
1710 The arguments must be ``bit``, ``bits``, ``int``, or ``string`` values.
|
|
|
1711
|
|
|
1712 ``!head(``\ *a*\ ``)``
|
|
|
1713 This operator produces the zeroth element of the list *a*.
|
|
|
1714 (See also ``!tail``.)
|
|
|
1715
|
|
|
1716 ``!if(``\ *test*\ ``,`` *then*\ ``,`` *else*\ ``)``
|
|
|
1717 This operator evaluates the *test*, which must produce a ``bit`` or
|
|
|
1718 ``int``. If the result is not 0, the *then* expression is produced; otherwise
|
|
|
1719 the *else* expression is produced.
|
|
|
1720
|
|
|
1721 ``!interleave(``\ *list*\ ``,`` *delim*\ ``)``
|
|
|
1722 This operator concatenates the items in the *list*, interleaving the
|
|
|
1723 *delim* string between each pair, and produces the resulting string.
|
|
|
1724 The list can be a list of string, int, bits, or bit. An empty list
|
|
|
1725 results in an empty string. The delimiter can be the empty string.
|
|
|
1726
|
|
|
1727 ``!isa<``\ *type*\ ``>(``\ *a*\ ``)``
|
|
|
1728 This operator produces 1 if the type of *a* is a subtype of the given *type*; 0
|
|
|
1729 otherwise.
|
|
|
1730
|
|
236
|
1731 ``!exists<``\ *type*\ ``>(``\ *name*\ ``)``
|
|
|
1732 This operator produces 1 if a record of the given *type* whose name is *name*
|
|
|
1733 exists; 0 otherwise. *name* should be of type *string*.
|
|
|
1734
|
|
221
|
1735 ``!le(``\ *a*\ ``,`` *b*\ ``)``
|
|
|
1736 This operator produces 1 if *a* is less than or equal to *b*; 0 otherwise.
|
|
|
1737 The arguments must be ``bit``, ``bits``, ``int``, or ``string`` values.
|
|
|
1738
|
|
|
1739 ``!listconcat(``\ *list1*\ ``,`` *list2*\ ``, ...)``
|
|
|
1740 This operator concatenates the list arguments *list1*, *list2*, etc., and
|
|
|
1741 produces the resulting list. The lists must have the same element type.
|
|
|
1742
|
|
|
1743 ``!listsplat(``\ *value*\ ``,`` *count*\ ``)``
|
|
|
1744 This operator produces a list of length *count* whose elements are all
|
|
|
1745 equal to the *value*. For example, ``!listsplat(42, 3)`` results in
|
|
|
1746 ``[42, 42, 42]``.
|
|
|
1747
|
|
236
|
1748 ``!logtwo(``\ *a*\ ``)``
|
|
|
1749 This operator produces the base 2 log of *a* and produces the integer
|
|
|
1750 result. The log of 0 or a negative number produces an error. This
|
|
|
1751 is a flooring operation.
|
|
|
1752
|
|
221
|
1753 ``!lt(``\ *a*\ `,` *b*\ ``)``
|
|
|
1754 This operator produces 1 if *a* is less than *b*; 0 otherwise.
|
|
|
1755 The arguments must be ``bit``, ``bits``, ``int``, or ``string`` values.
|
|
|
1756
|
|
|
1757 ``!mul(``\ *a*\ ``,`` *b*\ ``, ...)``
|
|
|
1758 This operator multiplies *a*, *b*, etc., and produces the product.
|
|
|
1759
|
|
|
1760 ``!ne(``\ *a*\ `,` *b*\ ``)``
|
|
|
1761 This operator produces 1 if *a* is not equal to *b*; 0 otherwise.
|
|
|
1762 The arguments must be ``bit``, ``bits``, ``int``, ``string``,
|
|
|
1763 or record values. Use ``!cast<string>`` to compare other types of objects.
|
|
|
1764
|
|
|
1765 ``!not(``\ *a*\ ``)``
|
|
|
1766 This operator performs a logical NOT on *a*, which must be
|
|
|
1767 an integer. The argument 0 results in 1 (true); any other
|
|
|
1768 argument results in 0 (false).
|
|
|
1769
|
|
|
1770 ``!or(``\ *a*\ ``,`` *b*\ ``, ...)``
|
|
|
1771 This operator does a bitwise OR on *a*, *b*, etc., and produces the
|
|
|
1772 result. A logical OR can be performed if all the arguments are either
|
|
|
1773 0 or 1.
|
|
|
1774
|
|
|
1775 ``!setdagop(``\ *dag*\ ``,`` *op*\ ``)``
|
|
|
1776 This operator produces a DAG node with the same arguments as *dag*, but with its
|
|
|
1777 operator replaced with *op*.
|
|
|
1778
|
|
|
1779 Example: ``!setdagop((foo 1, 2), bar)`` results in ``(bar 1, 2)``.
|
|
|
1780
|
|
|
1781 ``!shl(``\ *a*\ ``,`` *count*\ ``)``
|
|
|
1782 This operator shifts *a* left logically by *count* bits and produces the resulting
|
|
|
1783 value. The operation is performed on a 64-bit integer; the result
|
|
|
1784 is undefined for shift counts outside 0...63.
|
|
|
1785
|
|
|
1786 ``!size(``\ *a*\ ``)``
|
|
|
1787 This operator produces the size of the string, list, or dag *a*.
|
|
|
1788 The size of a DAG is the number of arguments; the operator does not count.
|
|
|
1789
|
|
|
1790 ``!sra(``\ *a*\ ``,`` *count*\ ``)``
|
|
|
1791 This operator shifts *a* right arithmetically by *count* bits and produces the resulting
|
|
|
1792 value. The operation is performed on a 64-bit integer; the result
|
|
|
1793 is undefined for shift counts outside 0...63.
|
|
|
1794
|
|
|
1795 ``!srl(``\ *a*\ ``,`` *count*\ ``)``
|
|
|
1796 This operator shifts *a* right logically by *count* bits and produces the resulting
|
|
|
1797 value. The operation is performed on a 64-bit integer; the result
|
|
|
1798 is undefined for shift counts outside 0...63.
|
|
|
1799
|
|
|
1800 ``!strconcat(``\ *str1*\ ``,`` *str2*\ ``, ...)``
|
|
|
1801 This operator concatenates the string arguments *str1*, *str2*, etc., and
|
|
|
1802 produces the resulting string.
|
|
|
1803
|
|
|
1804 ``!sub(``\ *a*\ ``,`` *b*\ ``)``
|
|
|
1805 This operator subtracts *b* from *a* and produces the arithmetic difference.
|
|
|
1806
|
|
|
1807 ``!subst(``\ *target*\ ``,`` *repl*\ ``,`` *value*\ ``)``
|
|
|
1808 This operator replaces all occurrences of the *target* in the *value* with
|
|
|
1809 the *repl* and produces the resulting value. The *value* can
|
|
|
1810 be a string, in which case substring substitution is performed.
|
|
|
1811
|
|
|
1812 The *value* can be a record name, in which case the operator produces the *repl*
|
|
|
1813 record if the *target* record name equals the *value* record name; otherwise it
|
|
|
1814 produces the *value*.
|
|
|
1815
|
|
|
1816 ``!substr(``\ *string*\ ``,`` *start*\ [``,`` *length*]\ ``)``
|
|
|
1817 This operator extracts a substring of the given *string*. The starting
|
|
|
1818 position of the substring is specified by *start*, which can range
|
|
|
1819 between 0 and the length of the string. The length of the substring
|
|
|
1820 is specified by *length*; if not specified, the rest of the string is
|
|
|
1821 extracted. The *start* and *length* arguments must be integers.
|
|
|
1822
|
|
|
1823 ``!tail(``\ *a*\ ``)``
|
|
|
1824 This operator produces a new list with all the elements
|
|
|
1825 of the list *a* except for the zeroth one. (See also ``!head``.)
|
|
|
1826
|
|
|
1827 ``!xor(``\ *a*\ ``,`` *b*\ ``, ...)``
|
|
|
1828 This operator does a bitwise EXCLUSIVE OR on *a*, *b*, etc., and produces
|
|
|
1829 the result. A logical XOR can be performed if all the arguments are either
|
|
|
1830 0 or 1.
|
|
|
1831
|
|
|
1832 Appendix B: Paste Operator Examples
|
|
|
1833 ===================================
|
|
|
1834
|
|
|
1835 Here is an example illustrating the use of the paste operator in record names.
|
|
|
1836
|
|
|
1837 .. code-block:: text
|
|
|
1838
|
|
|
1839 defvar suffix = "_suffstring";
|
|
|
1840 defvar some_ints = [0, 1, 2, 3];
|
|
|
1841
|
|
|
1842 def name # suffix {
|
|
|
1843 }
|
|
|
1844
|
|
|
1845 foreach i = [1, 2] in {
|
|
|
1846 def rec # i {
|
|
|
1847 }
|
|
|
1848 }
|
|
|
1849
|
|
|
1850 The first ``def`` does not use the value of the ``suffix`` variable. The
|
|
|
1851 second def does use the value of the ``i`` iterator variable, because it is not a
|
|
|
1852 global name. The following records are produced.
|
|
|
1853
|
|
|
1854 .. code-block:: text
|
|
|
1855
|
|
|
1856 def namesuffix {
|
|
|
1857 }
|
|
|
1858 def rec1 {
|
|
|
1859 }
|
|
|
1860 def rec2 {
|
|
|
1861 }
|
|
|
1862
|
|
|
1863 Here is a second example illustrating the paste operator in field value expressions.
|
|
|
1864
|
|
|
1865 .. code-block:: text
|
|
|
1866
|
|
|
1867 def test {
|
|
|
1868 string strings = suffix # suffix;
|
|
|
1869 list<int> integers = some_ints # [4, 5, 6];
|
|
|
1870 }
|
|
|
1871
|
|
|
1872 The ``strings`` field expression uses ``suffix`` on both sides of the paste
|
|
|
1873 operator. It is evaluated normally on the left hand side, but taken verbatim
|
|
|
1874 on the right hand side. The ``integers`` field expression uses the value of
|
|
|
1875 the ``some_ints`` variable and a literal list. The following record is
|
|
|
1876 produced.
|
|
|
1877
|
|
|
1878 .. code-block:: text
|
|
|
1879
|
|
|
1880 def test {
|
|
|
1881 string strings = "_suffstringsuffix";
|
|
|
1882 list<int> ints = [0, 1, 2, 3, 4, 5, 6];
|
|
|
1883 }
|
|
|
1884
|
|
|
1885
|
|
|
1886 Appendix C: Sample Record
|
|
|
1887 =========================
|
|
|
1888
|
|
|
1889 One target machine supported by LLVM is the Intel x86. The following output
|
|
|
1890 from TableGen shows the record that is created to represent the 32-bit
|
|
|
1891 register-to-register ADD instruction.
|
|
|
1892
|
|
|
1893 .. code-block:: text
|
|
|
1894
|
|
|
1895 def ADD32rr { // InstructionEncoding Instruction X86Inst I ITy Sched BinOpRR BinOpRR_RF
|
|
|
1896 int Size = 0;
|
|
|
1897 string DecoderNamespace = "";
|
|
|
1898 list<Predicate> Predicates = [];
|
|
|
1899 string DecoderMethod = "";
|
|
|
1900 bit hasCompleteDecoder = 1;
|
|
|
1901 string Namespace = "X86";
|
|
|
1902 dag OutOperandList = (outs GR32:$dst);
|
|
|
1903 dag InOperandList = (ins GR32:$src1, GR32:$src2);
|
|
|
1904 string AsmString = "add{l} {$src2, $src1|$src1, $src2}";
|
|
|
1905 EncodingByHwMode EncodingInfos = ?;
|
|
|
1906 list<dag> Pattern = [(set GR32:$dst, EFLAGS, (X86add_flag GR32:$src1, GR32:$src2))];
|
|
|
1907 list<Register> Uses = [];
|
|
|
1908 list<Register> Defs = [EFLAGS];
|
|
|
1909 int CodeSize = 3;
|
|
|
1910 int AddedComplexity = 0;
|
|
|
1911 bit isPreISelOpcode = 0;
|
|
|
1912 bit isReturn = 0;
|
|
|
1913 bit isBranch = 0;
|
|
|
1914 bit isEHScopeReturn = 0;
|
|
|
1915 bit isIndirectBranch = 0;
|
|
|
1916 bit isCompare = 0;
|
|
|
1917 bit isMoveImm = 0;
|
|
|
1918 bit isMoveReg = 0;
|
|
|
1919 bit isBitcast = 0;
|
|
|
1920 bit isSelect = 0;
|
|
|
1921 bit isBarrier = 0;
|
|
|
1922 bit isCall = 0;
|
|
|
1923 bit isAdd = 0;
|
|
|
1924 bit isTrap = 0;
|
|
|
1925 bit canFoldAsLoad = 0;
|
|
|
1926 bit mayLoad = ?;
|
|
|
1927 bit mayStore = ?;
|
|
|
1928 bit mayRaiseFPException = 0;
|
|
|
1929 bit isConvertibleToThreeAddress = 1;
|
|
|
1930 bit isCommutable = 1;
|
|
|
1931 bit isTerminator = 0;
|
|
|
1932 bit isReMaterializable = 0;
|
|
|
1933 bit isPredicable = 0;
|
|
|
1934 bit isUnpredicable = 0;
|
|
|
1935 bit hasDelaySlot = 0;
|
|
|
1936 bit usesCustomInserter = 0;
|
|
|
1937 bit hasPostISelHook = 0;
|
|
|
1938 bit hasCtrlDep = 0;
|
|
|
1939 bit isNotDuplicable = 0;
|
|
|
1940 bit isConvergent = 0;
|
|
|
1941 bit isAuthenticated = 0;
|
|
|
1942 bit isAsCheapAsAMove = 0;
|
|
|
1943 bit hasExtraSrcRegAllocReq = 0;
|
|
|
1944 bit hasExtraDefRegAllocReq = 0;
|
|
|
1945 bit isRegSequence = 0;
|
|
|
1946 bit isPseudo = 0;
|
|
|
1947 bit isExtractSubreg = 0;
|
|
|
1948 bit isInsertSubreg = 0;
|
|
|
1949 bit variadicOpsAreDefs = 0;
|
|
|
1950 bit hasSideEffects = ?;
|
|
|
1951 bit isCodeGenOnly = 0;
|
|
|
1952 bit isAsmParserOnly = 0;
|
|
|
1953 bit hasNoSchedulingInfo = 0;
|
|
|
1954 InstrItinClass Itinerary = NoItinerary;
|
|
|
1955 list<SchedReadWrite> SchedRW = [WriteALU];
|
|
|
1956 string Constraints = "$src1 = $dst";
|
|
|
1957 string DisableEncoding = "";
|
|
|
1958 string PostEncoderMethod = "";
|
|
|
1959 bits<64> TSFlags = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 1, 0, 0, 0 };
|
|
|
1960 string AsmMatchConverter = "";
|
|
|
1961 string TwoOperandAliasConstraint = "";
|
|
|
1962 string AsmVariantName = "";
|
|
|
1963 bit UseNamedOperandTable = 0;
|
|
|
1964 bit FastISelShouldIgnore = 0;
|
|
|
1965 bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
|
|
|
1966 Format Form = MRMDestReg;
|
|
|
1967 bits<7> FormBits = { 0, 1, 0, 1, 0, 0, 0 };
|
|
|
1968 ImmType ImmT = NoImm;
|
|
|
1969 bit ForceDisassemble = 0;
|
|
|
1970 OperandSize OpSize = OpSize32;
|
|
|
1971 bits<2> OpSizeBits = { 1, 0 };
|
|
|
1972 AddressSize AdSize = AdSizeX;
|
|
|
1973 bits<2> AdSizeBits = { 0, 0 };
|
|
|
1974 Prefix OpPrefix = NoPrfx;
|
|
|
1975 bits<3> OpPrefixBits = { 0, 0, 0 };
|
|
|
1976 Map OpMap = OB;
|
|
|
1977 bits<3> OpMapBits = { 0, 0, 0 };
|
|
|
1978 bit hasREX_WPrefix = 0;
|
|
|
1979 FPFormat FPForm = NotFP;
|
|
|
1980 bit hasLockPrefix = 0;
|
|
|
1981 Domain ExeDomain = GenericDomain;
|
|
|
1982 bit hasREPPrefix = 0;
|
|
|
1983 Encoding OpEnc = EncNormal;
|
|
|
1984 bits<2> OpEncBits = { 0, 0 };
|
|
|
1985 bit HasVEX_W = 0;
|
|
|
1986 bit IgnoresVEX_W = 0;
|
|
|
1987 bit EVEX_W1_VEX_W0 = 0;
|
|
|
1988 bit hasVEX_4V = 0;
|
|
|
1989 bit hasVEX_L = 0;
|
|
|
1990 bit ignoresVEX_L = 0;
|
|
|
1991 bit hasEVEX_K = 0;
|
|
|
1992 bit hasEVEX_Z = 0;
|
|
|
1993 bit hasEVEX_L2 = 0;
|
|
|
1994 bit hasEVEX_B = 0;
|
|
|
1995 bits<3> CD8_Form = { 0, 0, 0 };
|
|
|
1996 int CD8_EltSize = 0;
|
|
|
1997 bit hasEVEX_RC = 0;
|
|
|
1998 bit hasNoTrackPrefix = 0;
|
|
|
1999 bits<7> VectSize = { 0, 0, 1, 0, 0, 0, 0 };
|
|
|
2000 bits<7> CD8_Scale = { 0, 0, 0, 0, 0, 0, 0 };
|
|
|
2001 string FoldGenRegForm = ?;
|
|
|
2002 string EVEX2VEXOverride = ?;
|
|
|
2003 bit isMemoryFoldable = 1;
|
|
|
2004 bit notEVEX2VEXConvertible = 0;
|
|
|
2005 }
|
|
|
2006
|
|
|
2007 On the first line of the record, you can see that the ``ADD32rr`` record
|
|
|
2008 inherited from eight classes. Although the inheritance hierarchy is complex,
|
|
|
2009 using parent classes is much simpler than specifying the 109 individual
|
|
|
2010 fields for each instruction.
|
|
|
2011
|
|
|
2012 Here is the code fragment used to define ``ADD32rr`` and multiple other
|
|
|
2013 ``ADD`` instructions:
|
|
|
2014
|
|
|
2015 .. code-block:: text
|
|
|
2016
|
|
|
2017 defm ADD : ArithBinOp_RF<0x00, 0x02, 0x04, "add", MRM0r, MRM0m,
|
|
|
2018 X86add_flag, add, 1, 1, 1>;
|
|
|
2019
|
|
|
2020 The ``defm`` statement tells TableGen that ``ArithBinOp_RF`` is a
|
|
|
2021 multiclass, which contains multiple concrete record definitions that inherit
|
|
|
2022 from ``BinOpRR_RF``. That class, in turn, inherits from ``BinOpRR``, which
|
|
|
2023 inherits from ``ITy`` and ``Sched``, and so forth. The fields are inherited
|
|
|
2024 from all the parent classes; for example, ``IsIndirectBranch`` is inherited
|
|
|
2025 from the ``Instruction`` class.
|
