llvm.org GIT mirror llvm / 1625937
Re-factor TableGen docs This is mainly a movement of content around to give place to new content allowing different people to add bits to it in the right place. There is some new content, but mostly to fill the gaps left by text movement. I'm dropping the old syntax documentation as it has the problem of being quickly outdated by changes and largely unnecessary to people not involved in creating the language, but using it, which is the whole point of the documentation. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@204351 91177308-0d34-0410-b5e6-96231b3b80d8 Renato Golin 5 years ago
5 changed file(s) with 1203 addition(s) and 369 deletion(s). Raw diff Collapse all Expand all
0 =================
1 TableGen BackEnds
2 =================
3
4 .. contents::
5 :local:
6
7 Introduction
8 ============
9
10 TableGen backends are at the core of TableGen's functionality. The source files
11 provide the semantics to a generated (in memory) structure, but it's up to the
12 backend to print this out in a way that is meaningful to the user (normally a
13 C program including a file or a textual list of warnings, options and error
14 messages).
15
16 TableGen is used by both LLVM and Clang with very different goals. LLVM uses it
17 as a way to automate the generation of massive amounts of information regarding
18 instructions, schedules, cores and architecture features. Some backends generate
19 output that is consumed by more than one source file, so they need to be created
20 in a way that is easy to use pre-processor tricks. Some backends can also print
21 C code structures, so that they can be directly included as-is.
22
23 Clang, on the other hand, uses it mainly for diagnostic messages (errors,
24 warnings, tips) and attributes, so more on the textual end of the scale.
25
26 LLVM BackEnds
27 =============
28
29 .. warning::
30 This document is raw. Each section below needs three sub-sections: description
31 of its purpose with a list of users, output generated from generic input, and
32 finally why it needed a new backend (in case there's something similar).
33
34 Emitter
35 -------
36
37 Generate machine code emitter.
38
39 RegisterInfo
40 ------------
41
42 Generate registers and register classes info.
43
44 InstrInfo
45 ---------
46
47 Generate instruction descriptions.
48
49 AsmWriter
50 ---------
51
52 Generate calling convention descriptions.
53
54 AsmMatcher
55 ----------
56
57 Generate assembly writer.
58
59 Disassembler
60 ------------
61
62 Generate disassembler.
63
64 PseudoLowering
65 --------------
66
67 Generate pseudo instruction lowering.
68
69 CallingConv
70 -----------
71
72 Generate assembly instruction matcher.
73
74 DAGISel
75 -------
76
77 Generate a DAG instruction selector.
78
79 DFAPacketizer
80 -------------
81
82 Generate DFA Packetizer for VLIW targets.
83
84 FastISel
85 --------
86
87 Generate a "fast" instruction selector.
88
89 Subtarget
90 ---------
91
92 Generate subtarget enumerations.
93
94 Intrinsic
95 ---------
96
97 Generate intrinsic information.
98
99 TgtIntrinsic
100 ------------
101
102 Generate target intrinsic information.
103
104 OptParserDefs
105 -------------
106
107 Print enum values for a class.
108
109 CTags
110 -----
111
112 Generate ctags-compatible index.
113
114
115 Clang BackEnds
116 ==============
117
118 ClangAttrClasses
119 ----------------
120
121 Generate clang attribute clases.
122
123 ClangAttrParserStringSwitches
124 -----------------------------
125
126 Generate all parser-related attribute string switches.
127
128 ClangAttrImpl
129 -------------
130
131 Generate clang attribute implementations.
132
133 ClangAttrList
134 -------------
135
136 Generate a clang attribute list.
137
138 ClangAttrPCHRead
139 ----------------
140
141 Generate clang PCH attribute reader.
142
143 ClangAttrPCHWrite
144 -----------------
145
146 Generate clang PCH attribute writer.
147
148 ClangAttrSpellingList
149 ---------------------
150
151 Generate a clang attribute spelling list.
152
153 ClangAttrSpellingListIndex
154 --------------------------
155
156 Generate a clang attribute spelling index.
157
158 ClangAttrASTVisitor
159 -------------------
160
161 Generate a recursive AST visitor for clang attribute.
162
163 ClangAttrTemplateInstantiate
164 ----------------------------
165
166 Generate a clang template instantiate code.
167
168 ClangAttrParsedAttrList
169 -----------------------
170
171 Generate a clang parsed attribute list.
172
173 ClangAttrParsedAttrImpl
174 -----------------------
175
176 Generate the clang parsed attribute helpers.
177
178 ClangAttrParsedAttrKinds
179 ------------------------
180
181 Generate a clang parsed attribute kinds.
182
183 ClangAttrDump
184 -------------
185
186 Generate clang attribute dumper.
187
188 ClangDiagsDefs
189 --------------
190
191 Generate Clang diagnostics definitions.
192
193 ClangDiagGroups
194 ---------------
195
196 Generate Clang diagnostic groups.
197
198 ClangDiagsIndexName
199 -------------------
200
201 Generate Clang diagnostic name index.
202
203 ClangCommentNodes
204 -----------------
205
206 Generate Clang AST comment nodes.
207
208 ClangDeclNodes
209 --------------
210
211 Generate Clang AST declaration nodes.
212
213 ClangStmtNodes
214 --------------
215
216 Generate Clang AST statement nodes.
217
218 ClangSACheckers
219 ---------------
220
221 Generate Clang Static Analyzer checkers.
222
223 ClangCommentHTMLTags
224 --------------------
225
226 Generate efficient matchers for HTML tag names that are used in documentation comments.
227
228 ClangCommentHTMLTagsProperties
229 ------------------------------
230
231 Generate efficient matchers for HTML tag properties.
232
233 ClangCommentHTMLNamedCharacterReferences
234 ----------------------------------------
235
236 Generate function to translate named character references to UTF-8 sequences.
237
238 ClangCommentCommandInfo
239 -----------------------
240
241 Generate command properties for commands that are used in documentation comments.
242
243 ClangCommentCommandList
244 -----------------------
245
246 Generate list of commands that are used in documentation comments.
247
248 ArmNeon
249 -------
250
251 Generate arm_neon.h for clang.
252
253 ArmNeonSema
254 -----------
255
256 Generate ARM NEON sema support for clang.
257
258 ArmNeonTest
259 -----------
260
261 Generate ARM NEON tests for clang.
262
263 AttrDocs
264 --------
265
266 Generate attribute documentation.
267
268 How to write a back-end
269 =======================
270
271 TODO.
272
273 Until we get a step-by-step HowTo for writing TableGen backends, you can at
274 least grab the boilerplate (build system, new files, etc.) from Clang's
275 r173931.
276
277 TODO: How they work, how to write one. This section should not contain details
278 about any particular backend, except maybe ``-print-enums`` as an example. This
279 should highlight the APIs in ``TableGen/Record.h``.
280
0 =====================
1 TableGen Deficiencies
2 =====================
3
4 .. contents::
5 :local:
6
7 Introduction
8 ============
9
10 Despite being very generic, TableGen has some deficiencies that have been
11 pointed out numerous times. The common theme is that, while TableGen allows
12 you to build Domain-Specific-Languages, the final languages that you create
13 lack the power of other DSLs, which in turn increase considerably the size
14 and complexity of TableGen files.
15
16 At the same time, TableGen allows you to create virtually any meaning of
17 the basic concepts via custom-made back-ends, which can pervert the original
18 design and make it very hard for newcomers to understand it.
19
20 There are some in favour of extending the semantics even more, but making sure
21 back-ends adhere to strict rules. Others suggesting we should move to more
22 powerful DSLs designed with specific purposes, or even re-using existing
23 DSLs.
24
25 Known Problems
26 ==============
27
28 TODO: Add here frequently asked questions about why TableGen doesn't do
29 what you want, how it might, and how we could extend/restrict it to
30 be more use friendly.
0 ===========================
11 TableGen Language Reference
22 ===========================
3
4 .. sectionauthor:: Sean Silva
53
64 .. contents::
75 :local:
1715 in and of itself (i.e. how to understand a given construct in terms of how
1816 it affects the final set of records represented by the TableGen file). If
1917 you are unsure if this document is really what you are looking for, please
20 read :doc:`/TableGenFundamentals` first.
21
22 Notation
23 ========
24
25 The lexical and syntax notation used here is intended to imitate
26 `Python's`_. In particular, for lexical definitions, the productions
27 operate at the character level and there is no implied whitespace between
28 elements. The syntax definitions operate at the token level, so there is
29 implied whitespace between tokens.
30
31 .. _`Python's`: http://docs.python.org/py3k/reference/introduction.html#notation
32
33 Lexical Analysis
34 ================
35
36 TableGen supports BCPL (``// ...``) and nestable C-style (``/* ... */``)
37 comments.
38
39 The following is a listing of the basic punctuation tokens::
40
41 - + [ ] { } ( ) < > : ; . = ? #
42
43 Numeric literals take one of the following forms:
44
45 .. TableGen actually will lex some pretty strange sequences an interpret
46 them as numbers. What is shown here is an attempt to approximate what it
47 "should" accept.
48
49 .. productionlist::
50 TokInteger: `DecimalInteger` | `HexInteger` | `BinInteger`
51 DecimalInteger: ["+" | "-"] ("0"..."9")+
52 HexInteger: "0x" ("0"..."9" | "a"..."f" | "A"..."F")+
53 BinInteger: "0b" ("0" | "1")+
54
55 One aspect to note is that the :token:`DecimalInteger` token *includes* the
56 ``+`` or ``-``, as opposed to having ``+`` and ``-`` be unary operators as
57 most languages do.
58
59 TableGen has identifier-like tokens:
60
61 .. productionlist::
62 ualpha: "a"..."z" | "A"..."Z" | "_"
63 TokIdentifier: ("0"..."9")* `ualpha` (`ualpha` | "0"..."9")*
64 TokVarName: "$" `ualpha` (`ualpha` | "0"..."9")*
65
66 Note that unlike most languages, TableGen allows :token:`TokIdentifier` to
67 begin with a number. In case of ambiguity, a token will be interpreted as a
68 numeric literal rather than an identifier.
69
70 TableGen also has two string-like literals:
71
72 .. productionlist::
73 TokString: '"' '"'
74 TokCodeFragment: "[{" "}]"
75
76 :token:`TokCodeFragment` is essentially a multiline string literal
77 delimited by ``[{`` and ``}]``.
78
79 .. note::
80 The current implementation accepts the following C-like escapes::
81
82 \\ \' \" \t \n
83
84 TableGen also has the following keywords::
85
86 bit bits class code dag
87 def foreach defm field in
88 int let list multiclass string
89
90 TableGen also has "bang operators" which have a
91 wide variety of meanings:
92
93 .. productionlist::
94 BangOperator: one of
95 :!eq !if !head !tail !con
96 :!add !shl !sra !srl
97 :!cast !empty !subst !foreach !strconcat
98
99 Syntax
100 ======
101
102 TableGen has an ``include`` mechanism. It does not play a role in the
103 syntax per se, since it is lexically replaced with the contents of the
104 included file.
105
106 .. productionlist::
107 IncludeDirective: "include" `TokString`
108
109 TableGen's top-level production consists of "objects".
110
111 .. productionlist::
112 TableGenFile: `Object`*
113 Object: `Class` | `Def` | `Defm` | `Let` | `MultiClass` | `Foreach`
114
115 ``class``\es
116 ------------
117
118 .. productionlist::
119 Class: "class" `TokIdentifier` [`TemplateArgList`] `ObjectBody`
120
121 A ``class`` declaration creates a record which other records can inherit
122 from. A class can be parametrized by a list of "template arguments", whose
123 values can be used in the class body.
124
125 A given class can only be defined once. A ``class`` declaration is
126 considered to define the class if any of the following is true:
127
128 .. break ObjectBody into its consituents so that they are present here?
129
130 #. The :token:`TemplateArgList` is present.
131 #. The :token:`Body` in the :token:`ObjectBody` is present and is not empty.
132 #. The :token:`BaseClassList` in the :token:`ObjectBody` is present.
133
134 You can declare an empty class by giving and empty :token:`TemplateArgList`
135 and an empty :token:`ObjectBody`. This can serve as a restricted form of
136 forward declaration: note that records deriving from the forward-declared
137 class will inherit no fields from it since the record expansion is done
138 when the record is parsed.
139
140 .. productionlist::
141 TemplateArgList: "<" `Declaration` ("," `Declaration`)* ">"
142
143 Declarations
144 ------------
145
146 .. Omitting mention of arcane "field" prefix to discourage its use.
147
148 The declaration syntax is pretty much what you would expect as a C++
149 programmer.
150
151 .. productionlist::
152 Declaration: `Type` `TokIdentifier` ["=" `Value`]
153
154 It assigns the value to the identifer.
155
156 Types
157 -----
158
159 .. productionlist::
160 Type: "string" | "code" | "bit" | "int" | "dag"
161 :| "bits" "<" `TokInteger` ">"
162 :| "list" "<" `Type` ">"
163 :| `ClassID`
164 ClassID: `TokIdentifier`
165
166 Both ``string`` and ``code`` correspond to the string type; the difference
167 is purely to indicate programmer intention.
168
169 The :token:`ClassID` must identify a class that has been previously
170 declared or defined.
171
172 Values
173 ------
174
175 .. productionlist::
176 Value: `SimpleValue` `ValueSuffix`*
177 ValueSuffix: "{" `RangeList` "}"
178 :| "[" `RangeList` "]"
179 :| "." `TokIdentifier`
180 RangeList: `RangePiece` ("," `RangePiece`)*
181 RangePiece: `TokInteger`
182 :| `TokInteger` "-" `TokInteger`
183 :| `TokInteger` `TokInteger`
184
185 The peculiar last form of :token:`RangePiece` is due to the fact that the
186 "``-``" is included in the :token:`TokInteger`, hence ``1-5`` gets lexed as
187 two consecutive :token:`TokInteger`'s, with values ``1`` and ``-5``,
188 instead of "1", "-", and "5".
189 The :token:`RangeList` can be thought of as specifying "list slice" in some
190 contexts.
191
192
193 :token:`SimpleValue` has a number of forms:
194
195
196 .. productionlist::
197 SimpleValue: `TokIdentifier`
198
199 The value will be the variable referenced by the identifier. It can be one
200 of:
201
202 .. The code for this is exceptionally abstruse. These examples are a
203 best-effort attempt.
204
205 * name of a ``def``, such as the use of ``Bar`` in::
206
207 def Bar : SomeClass {
208 int X = 5;
209 }
210
211 def Foo {
212 SomeClass Baz = Bar;
213 }
214
215 * value local to a ``def``, such as the use of ``Bar`` in::
216
217 def Foo {
218 int Bar = 5;
219 int Baz = Bar;
220 }
221
222 * a template arg of a ``class``, such as the use of ``Bar`` in::
223
224 class Foo {
225 int Baz = Bar;
226 }
227
228 * value local to a ``multiclass``, such as the use of ``Bar`` in::
229
230 multiclass Foo {
231 int Bar = 5;
232 int Baz = Bar;
233 }
234
235 * a template arg to a ``multiclass``, such as the use of ``Bar`` in::
236
237 multiclass Foo {
238 int Baz = Bar;
239 }
240
241 .. productionlist::
242 SimpleValue: `TokInteger`
243
244 This represents the numeric value of the integer.
245
246 .. productionlist::
247 SimpleValue: `TokString`+
248
249 Multiple adjacent string literals are concatenated like in C/C++. The value
250 is the concatenation of the strings.
251
252 .. productionlist::
253 SimpleValue: `TokCodeFragment`
254
255 The value is the string value of the code fragment.
256
257 .. productionlist::
258 SimpleValue: "?"
259
260 ``?`` represents an "unset" initializer.
261
262 .. productionlist::
263 SimpleValue: "{" `ValueList` "}"
264 ValueList: [`ValueListNE`]
265 ValueListNE: `Value` ("," `Value`)*
266
267 This represents a sequence of bits, as would be used to initialize a
268 ``bits`` field (where ``n`` is the number of bits).
269
270 .. productionlist::
271 SimpleValue: `ClassID` "<" `ValueListNE` ">"
272
273 This generates a new anonymous record definition (as would be created by an
274 unnamed ``def`` inheriting from the given class with the given template
275 arguments) and the value is the value of that record definition.
276
277 .. productionlist::
278 SimpleValue: "[" `ValueList` "]" ["<" `Type` ">"]
279
280 A list initializer. The optional :token:`Type` can be used to indicate a
281 specific element type, otherwise the element type will be deduced from the
282 given values.
283
284 .. The initial `DagArg` of the dag must start with an identifier or
285 !cast, but this is more of an implementation detail and so for now just
286 leave it out.
287
288 .. productionlist::
289 SimpleValue: "(" `DagArg` `DagArgList` ")"
290 DagArgList: `DagArg` ("," `DagArg`)*
291 DagArg: `Value` [":" `TokVarName`] | `TokVarName`
292
293 The initial :token:`DagArg` is called the "operator" of the dag.
294
295 .. productionlist::
296 SimpleValue: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"
297
298 Bodies
299 ------
300
301 .. productionlist::
302 ObjectBody: `BaseClassList` `Body`
303 BaseClassList: [":" `BaseClassListNE`]
304 BaseClassListNE: `SubClassRef` ("," `SubClassRef`)*
305 SubClassRef: (`ClassID` | `MultiClassID`) ["<" `ValueList` ">"]
306 DefmID: `TokIdentifier`
307
308 The version with the :token:`MultiClassID` is only valid in the
309 :token:`BaseClassList` of a ``defm``.
310 The :token:`MultiClassID` should be the name of a ``multiclass``.
311
312 .. put this somewhere else
313
314 It is after parsing the base class list that the "let stack" is applied.
315
316 .. productionlist::
317 Body: ";" | "{" BodyList "}"
318 BodyList: BodyItem*
319 BodyItem: `Declaration` ";"
320 :| "let" `TokIdentifier` [`RangeList`] "=" `Value` ";"
321
322 The ``let`` form allows overriding the value of an inherited field.
323
324 ``def``
325 -------
326
327 .. TODO::
328 There can be pastes in the names here, like ``#NAME#``. Look into that
329 and document it (it boils down to ParseIDValue with IDParseMode ==
330 ParseNameMode). ParseObjectName calls into the general ParseValue, with
331 the only different from "arbitrary expression parsing" being IDParseMode
332 == Mode.
333
334 .. productionlist::
335 Def: "def" `TokIdentifier` `ObjectBody`
336
337 Defines a record whose name is given by the :token:`TokIdentifier`. The
338 fields of the record are inherited from the base classes and defined in the
339 body.
340
341 Special handling occurs if this ``def`` appears inside a ``multiclass`` or
342 a ``foreach``.
343
344 ``defm``
345 --------
346
347 .. productionlist::
348 Defm: "defm" `TokIdentifier` ":" `BaseClassListNE` ";"
349
350 Note that in the :token:`BaseClassList`, all of the ``multiclass``'s must
351 precede any ``class``'s that appear.
352
353 ``foreach``
354 -----------
355
356 .. productionlist::
357 Foreach: "foreach" `Declaration` "in" "{" `Object`* "}"
358 :| "foreach" `Declaration` "in" `Object`
359
360 The value assigned to the variable in the declaration is iterated over and
361 the object or object list is reevaluated with the variable set at each
362 iterated value.
363
364 Top-Level ``let``
365 -----------------
366
367 .. productionlist::
368 Let: "let" `LetList` "in" "{" `Object`* "}"
369 :| "let" `LetList` "in" `Object`
370 LetList: `LetItem` ("," `LetItem`)*
371 LetItem: `TokIdentifier` [`RangeList`] "=" `Value`
372
373 This is effectively equivalent to ``let`` inside the body of a record
374 except that it applies to multiple records at a time. The bindings are
375 applied at the end of parsing the base classes of a record.
376
377 ``multiclass``
378 --------------
379
380 .. productionlist::
381 MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]
382 : [":" `BaseMultiClassList`] "{" `MultiClassObject`+ "}"
383 BaseMultiClassList: `MultiClassID` ("," `MultiClassID`)*
384 MultiClassID: `TokIdentifier`
385 MultiClassObject: `Def` | `Defm` | `Let` | `Foreach`
18 read :doc:`the introduction ` first.
19
20 TableGen syntax
21 ===============
22
23 TableGen doesn't care about the meaning of data (that is up to the backend to
24 define), but it does care about syntax, and it enforces a simple type system.
25 This section describes the syntax and the constructs allowed in a TableGen file.
26
27 TableGen primitives
28 -------------------
29
30 TableGen comments
31 ^^^^^^^^^^^^^^^^^
32
33 TableGen supports C++ style "``//``" comments, which run to the end of the
34 line, and it also supports **nestable** "``/* */``" comments.
35
36 .. _TableGen type:
37
38 The TableGen type system
39 ^^^^^^^^^^^^^^^^^^^^^^^^
40
41 TableGen files are strongly typed, in a simple (but complete) type-system.
42 These types are used to perform automatic conversions, check for errors, and to
43 help interface designers constrain the input that they allow. Every `value
44 definition`_ is required to have an associated type.
45
46 TableGen supports a mixture of very low-level types (such as ``bit``) and very
47 high-level types (such as ``dag``). This flexibility is what allows it to
48 describe a wide range of information conveniently and compactly. The TableGen
49 types are:
50
51 ``bit``
52 A 'bit' is a boolean value that can hold either 0 or 1.
53
54 ``int``
55 The 'int' type represents a simple 32-bit integer value, such as 5.
56
57 ``string``
58 The 'string' type represents an ordered sequence of characters of arbitrary
59 length.
60
61 ``bits``
62 A 'bits' type is an arbitrary, but fixed, size integer that is broken up
63 into individual bits. This type is useful because it can handle some bits
64 being defined while others are undefined.
65
66 ``list``
67 This type represents a list whose elements are some other type. The
68 contained type is arbitrary: it can even be another list type.
69
70 Class type
71 Specifying a class name in a type context means that the defined value must
72 be a subclass of the specified class. This is useful in conjunction with
73 the ``list`` type, for example, to constrain the elements of the list to a
74 common base class (e.g., a ``list`` can only contain definitions
75 derived from the "``Register``" class).
76
77 ``dag``
78 This type represents a nestable directed graph of elements.
79
80 To date, these types have been sufficient for describing things that TableGen
81 has been used for, but it is straight-forward to extend this list if needed.
82
83 .. _TableGen expressions:
84
85 TableGen values and expressions
86 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
87
88 TableGen allows for a pretty reasonable number of different expression forms
89 when building up values. These forms allow the TableGen file to be written in a
90 natural syntax and flavor for the application. The current expression forms
91 supported include:
92
93 ``?``
94 uninitialized field
95
96 ``0b1001011``
97 binary integer value
98
99 ``07654321``
100 octal integer value (indicated by a leading 0)
101
102 ``7``
103 decimal integer value
104
105 ``0x7F``
106 hexadecimal integer value
107
108 ``"foo"``
109 string value
110
111 ``[{ ... }]``
112 usually called a "code fragment", but is just a multiline string literal
113
114 ``[ X, Y, Z ]``
115 list value. is the type of the list element and is usually optional.
116 In rare cases, TableGen is unable to deduce the element type in which case
117 the user must specify it explicitly.
118
119 ``{ a, b, c }``
120 initializer for a "bits<3>" value
121
122 ``value``
123 value reference
124
125 ``value{17}``
126 access to one bit of a value
127
128 ``value{15-17}``
129 access to multiple bits of a value
130
131 ``DEF``
132 reference to a record definition
133
134 ``CLASS``
135 reference to a new anonymous definition of CLASS with the specified template
136 arguments.
137
138 ``X.Y``
139 reference to the subfield of a value
140
141 ``list[4-7,17,2-3]``
142 A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it.
143 Elements may be included multiple times.
144
145 ``foreach = [ ] in { }``
146
147 ``foreach = [ ] in ``
148 Replicate or , replacing instances of with each value
149 in . is scoped at the level of the ``foreach`` loop and must
150 not conflict with any other object introduced in or . Currently
151 only ``def``\s are expanded within .
152
153 ``foreach = 0-15 in ...``
154
155 ``foreach = {0-15,32-47} in ...``
156 Loop over ranges of integers. The braces are required for multiple ranges.
157
158 ``(DEF a, b)``
159 a dag value. The first element is required to be a record definition, the
160 remaining elements in the list may be arbitrary other values, including
161 nested ```dag``' values.
162
163 ``!strconcat(a, b)``
164 A string value that is the result of concatenating the 'a' and 'b' strings.
165
166 ``str1#str2``
167 "#" (paste) is a shorthand for !strconcat. It may concatenate things that
168 are not quoted strings, in which case an implicit !cast is done on
169 the operand of the paste.
170
171 ``!cast(a)``
172 A symbol of type *type* obtained by looking up the string 'a' in the symbol
173 table. If the type of 'a' does not match *type*, TableGen aborts with an
174 error. !cast is a special case in that the argument must be an
175 object defined by a 'def' construct.
176
177 ``!subst(a, b, c)``
178 If 'a' and 'b' are of string type or are symbol references, substitute 'b'
179 for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.
180
181 ``!foreach(a, b, c)``
182 For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a dummy
183 variable that should be declared as a member variable of an instantiated
184 class. This operation is analogous to $(foreach) in GNU make.
185
186 ``!head(a)``
187 The first element of list 'a.'
188
189 ``!tail(a)``
190 The 2nd-N elements of list 'a.'
191
192 ``!empty(a)``
193 An integer {0,1} indicating whether list 'a' is empty.
194
195 ``!if(a,b,c)``
196 'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
197
198 ``!eq(a,b)``
199 'bit 1' if string a is equal to string b, 0 otherwise. This only operates
200 on string, int and bit objects. Use !cast to compare other types of
201 objects.
202
203 Note that all of the values have rules specifying how they convert to values
204 for different types. These rules allow you to assign a value like "``7``"
205 to a "``bits<4>``" value, for example.
206
207 Classes and definitions
208 -----------------------
209
210 As mentioned in the :doc:`introduction `, classes and definitions (collectively known as
211 'records') in TableGen are the main high-level unit of information that TableGen
212 collects. Records are defined with a ``def`` or ``class`` keyword, the record
213 name, and an optional list of "`template arguments`_". If the record has
214 superclasses, they are specified as a comma separated list that starts with a
215 colon character ("``:``"). If `value definitions`_ or `let expressions`_ are
216 needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
217 the record ends with a semicolon.
218
219 Here is a simple TableGen file:
220
221 .. code-block:: llvm
222
223 class C { bit V = 1; }
224 def X : C;
225 def Y : C {
226 string Greeting = "hello";
227 }
228
229 This example defines two definitions, ``X`` and ``Y``, both of which derive from
230 the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y``
231 definition also gets the Greeting member as well.
232
233 In general, classes are useful for collecting together the commonality between a
234 group of records and isolating it in a single place. Also, classes permit the
235 specification of default values for their subclasses, allowing the subclasses to
236 override them as they wish.
237
238 .. _value definition:
239 .. _value definitions:
240
241 Value definitions
242 ^^^^^^^^^^^^^^^^^
243
244 Value definitions define named entries in records. A value must be defined
245 before it can be referred to as the operand for another value definition or
246 before the value is reset with a `let expression`_. A value is defined by
247 specifying a `TableGen type`_ and a name. If an initial value is available, it
248 may be specified after the type with an equal sign. Value definitions require
249 terminating semicolons.
250
251 .. _let expression:
252 .. _let expressions:
253 .. _"let" expressions within a record:
254
255 'let' expressions
256 ^^^^^^^^^^^^^^^^^
257
258 A record-level let expression is used to change the value of a value definition
259 in a record. This is primarily useful when a superclass defines a value that a
260 derived class or definition wants to override. Let expressions consist of the
261 '``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
262 value. For example, a new class could be added to the example above, redefining
263 the ``V`` field for all of its subclasses:
264
265 .. code-block:: llvm
266
267 class D : C { let V = 0; }
268 def Z : D;
269
270 In this case, the ``Z`` definition will have a zero value for its ``V`` value,
271 despite the fact that it derives (indirectly) from the ``C`` class, because the
272 ``D`` class overrode its value.
273
274 .. _template arguments:
275
276 Class template arguments
277 ^^^^^^^^^^^^^^^^^^^^^^^^
278
279 TableGen permits the definition of parameterized classes as well as normal
280 concrete classes. Parameterized TableGen classes specify a list of variable
281 bindings (which may optionally have defaults) that are bound when used. Here is
282 a simple example:
283
284 .. code-block:: llvm
285
286 class FPFormat val> {
287 bits<3> Value = val;
288 }
289 def NotFP : FPFormat<0>;
290 def ZeroArgFP : FPFormat<1>;
291 def OneArgFP : FPFormat<2>;
292 def OneArgFPRW : FPFormat<3>;
293 def TwoArgFP : FPFormat<4>;
294 def CompareFP : FPFormat<5>;
295 def CondMovFP : FPFormat<6>;
296 def SpecialFP : FPFormat<7>;
297
298 In this case, template arguments are used as a space efficient way to specify a
299 list of "enumeration values", each with a "``Value``" field set to the specified
300 integer.
301
302 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
303 with template arguments. As an example:
304
305 .. code-block:: llvm
306
307 class ModRefVal val> {
308 bits<2> Value = val;
309 }
310
311 def None : ModRefVal<0>;
312 def Mod : ModRefVal<1>;
313 def Ref : ModRefVal<2>;
314 def ModRef : ModRefVal<3>;
315
316 class Value {
317 // Decode some information into a more convenient format, while providing
318 // a nice interface to the user of the "Value" class.
319 bit isMod = MR.Value{0};
320 bit isRef = MR.Value{1};
321
322 // other stuff...
323 }
324
325 // Example uses
326 def bork : Value;
327 def zork : Value;
328 def hork : Value;
329
330 This is obviously a contrived example, but it shows how template arguments can
331 be used to decouple the interface provided to the user of the class from the
332 actual internal data representation expected by the class. In this case,
333 running ``llvm-tblgen`` on the example prints the following definitions:
334
335 .. code-block:: llvm
336
337 def bork { // Value
338 bit isMod = 1;
339 bit isRef = 0;
340 }
341 def hork { // Value
342 bit isMod = 1;
343 bit isRef = 1;
344 }
345 def zork { // Value
346 bit isMod = 0;
347 bit isRef = 1;
348 }
349
350 This shows that TableGen was able to dig into the argument and extract a piece
351 of information that was requested by the designer of the "Value" class. For
352 more realistic examples, please see existing users of TableGen, such as the X86
353 backend.
354
355 Multiclass definitions and instances
356 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
357
358 While classes with template arguments are a good way to factor commonality
359 between two instances of a definition, multiclasses allow a convenient notation
360 for defining multiple definitions at once (instances of implicitly constructed
361 classes). For example, consider an 3-address instruction set whose instructions
362 come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
363 (e.g. SPARC). In this case, you'd like to specify in one place that this
364 commonality exists, then in a separate place indicate what all the ops are.
365
366 Here is an example TableGen fragment that shows this idea:
367
368 .. code-block:: llvm
369
370 def ops;
371 def GPR;
372 def Imm;
373 class inst;
374
375 multiclass ri_inst {
376 def _rr : inst
377 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
378 def _ri : inst
379 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
380 }
381
382 // Instantiations of the ri_inst multiclass.
383 defm ADD : ri_inst<0b111, "add">;
384 defm SUB : ri_inst<0b101, "sub">;
385 defm MUL : ri_inst<0b100, "mul">;
386 ...
387
388 The name of the resultant definitions has the multidef fragment names appended
389 to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may
390 inherit from multiple multiclasses, instantiating definitions from each
391 multiclass. Using a multiclass this way is exactly equivalent to instantiating
392 the classes multiple times yourself, e.g. by writing:
393
394 .. code-block:: llvm
395
396 def ops;
397 def GPR;
398 def Imm;
399 class inst;
400
401 class rrinst
402 : inst
403 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
404
405 class riinst
406 : inst
407 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
408
409 // Instantiations of the ri_inst multiclass.
410 def ADD_rr : rrinst<0b111, "add">;
411 def ADD_ri : riinst<0b111, "add">;
412 def SUB_rr : rrinst<0b101, "sub">;
413 def SUB_ri : riinst<0b101, "sub">;
414 def MUL_rr : rrinst<0b100, "mul">;
415 def MUL_ri : riinst<0b100, "mul">;
416 ...
417
418 A ``defm`` can also be used inside a multiclass providing several levels of
419 multiclass instantiations.
420
421 .. code-block:: llvm
422
423 class Instruction opc, string Name> {
424 bits<4> opcode = opc;
425 string name = Name;
426 }
427
428 multiclass basic_r opc> {
429 def rr : Instruction;
430 def rm : Instruction;
431 }
432
433 multiclass basic_s opc> {
434 defm SS : basic_r;
435 defm SD : basic_r;
436 def X : Instruction;
437 }
438
439 multiclass basic_p opc> {
440 defm PS : basic_r;
441 defm PD : basic_r;
442 def Y : Instruction;
443 }
444
445 defm ADD : basic_s<0xf>, basic_p<0xf>;
446 ...
447
448 // Results
449 def ADDPDrm { ...
450 def ADDPDrr { ...
451 def ADDPSrm { ...
452 def ADDPSrr { ...
453 def ADDSDrm { ...
454 def ADDSDrr { ...
455 def ADDY { ...
456 def ADDX { ...
457
458 ``defm`` declarations can inherit from classes too, the rule to follow is that
459 the class list must start after the last multiclass, and there must be at least
460 one multiclass before them.
461
462 .. code-block:: llvm
463
464 class XD { bits<4> Prefix = 11; }
465 class XS { bits<4> Prefix = 12; }
466
467 class I op> {
468 bits<4> opcode = op;
469 }
470
471 multiclass R {
472 def rr : I<4>;
473 def rm : I<2>;
474 }
475
476 multiclass Y {
477 defm SS : R, XD;
478 defm SD : R, XS;
479 }
480
481 defm Instr : Y;
482
483 // Results
484 def InstrSDrm {
485 bits<4> opcode = { 0, 0, 1, 0 };
486 bits<4> Prefix = { 1, 1, 0, 0 };
487 }
488 ...
489 def InstrSSrr {
490 bits<4> opcode = { 0, 1, 0, 0 };
491 bits<4> Prefix = { 1, 0, 1, 1 };
492 }
493
494 File scope entities
495 -------------------
496
497 File inclusion
498 ^^^^^^^^^^^^^^
499
500 TableGen supports the '``include``' token, which textually substitutes the
501 specified file in place of the include directive. The filename should be
502 specified as a double quoted string immediately after the '``include``' keyword.
503 Example:
504
505 .. code-block:: llvm
506
507 include "foo.td"
508
509 'let' expressions
510 ^^^^^^^^^^^^^^^^^
511
512 "Let" expressions at file scope are similar to `"let" expressions within a
513 record`_, except they can specify a value binding for multiple records at a
514 time, and may be useful in certain other cases. File-scope let expressions are
515 really just another way that TableGen allows the end-user to factor out
516 commonality from the records.
517
518 File-scope "let" expressions take a comma-separated list of bindings to apply,
519 and one or more records to bind the values in. Here are some examples:
520
521 .. code-block:: llvm
522
523 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
524 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
525
526 let isCall = 1 in
527 // All calls clobber the non-callee saved registers...
528 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
529 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
530 XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
531 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
532 "call\t${dst:call}", []>;
533 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
534 "call\t{*}$dst", [(X86call GR32:$dst)]>;
535 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
536 "call\t{*}$dst", []>;
537 }
538
539 File-scope "let" expressions are often useful when a couple of definitions need
540 to be added to several records, and the records do not otherwise need to be
541 opened, as in the case with the ``CALL*`` instructions above.
542
543 It's also possible to use "let" expressions inside multiclasses, providing more
544 ways to factor out commonality from the records, specially if using several
545 levels of multiclass instantiations. This also avoids the need of using "let"
546 expressions within subsequent records inside a multiclass.
547
548 .. code-block:: llvm
549
550 multiclass basic_r opc> {
551 let Predicates = [HasSSE2] in {
552 def rr : Instruction;
553 def rm : Instruction;
554 }
555 let Predicates = [HasSSE3] in
556 def rx : Instruction;
557 }
558
559 multiclass basic_ss opc> {
560 let IsDouble = 0 in
561 defm SS : basic_r;
562
563 let IsDouble = 1 in
564 defm SD : basic_r;
565 }
566
567 defm ADD : basic_ss<0xf>;
568
569 Looping
570 ^^^^^^^
571
572 TableGen supports the '``foreach``' block, which textually replicates the loop
573 body, substituting iterator values for iterator references in the body.
574 Example:
575
576 .. code-block:: llvm
577
578 foreach i = [0, 1, 2, 3] in {
579 def R#i : Register<...>;
580 def F#i : Register<...>;
581 }
582
583 This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks
584 may be nested. If there is only one item in the body the braces may be
585 elided:
586
587 .. code-block:: llvm
588
589 foreach i = [0, 1, 2, 3] in
590 def R#i : Register<...>;
591
592 Code Generator backend info
593 ===========================
594
595 Expressions used by code generator to describe instructions and isel patterns:
596
597 ``(implicit a)``
598 an implicitly defined physical register. This tells the dag instruction
599 selection emitter the input pattern's extra definitions matches implicit
600 physical register definitions.
601
0 ========
1 TableGen
2 ========
3
4 .. contents::
5 :local:
6
7 .. toctree::
8 :hidden:
9
10 BackEnds
11 LangRef
12 Deficiencies
13
14 Introduction
15 ============
16
17 TableGen's purpose is to help a human develop and maintain records of
18 domain-specific information. Because there may be a large number of these
19 records, it is specifically designed to allow writing flexible descriptions and
20 for common features of these records to be factored out. This reduces the
21 amount of duplication in the description, reduces the chance of error, and makes
22 it easier to structure domain specific information.
23
24 The core part of TableGen parses a file, instantiates the declarations, and
25 hands the result off to a domain-specific `backends`_ for processing.
26
27 The current major users of TableGen are :doc:`../CodeGenerator`
28 and the
29 `Clang diagnostics and attributes `_.
30
31 Note that if you work on TableGen much, and use emacs or vim, that you can find
32 an emacs "TableGen mode" and a vim language file in the ``llvm/utils/emacs`` and
33 ``llvm/utils/vim`` directories of your LLVM distribution, respectively.
34
35 .. _intro:
36
37
38 The TableGen program
39 ====================
40
41 TableGen files are interpreted by the TableGen program: `llvm-tblgen` available
42 on your build directory under `bin`. It is not installed in the system (or where
43 your sysroot is set to), since it has no use beyond LLVM's build process.
44
45 Running TableGen
46 ----------------
47
48 TableGen runs just like any other LLVM tool. The first (optional) argument
49 specifies the file to read. If a filename is not specified, ``llvm-tblgen``
50 reads from standard input.
51
52 To be useful, one of the `backends`_ must be used. These backends are
53 selectable on the command line (type '``llvm-tblgen -help``' for a list). For
54 example, to get a list of all of the definitions that subclass a particular type
55 (which can be useful for building up an enum list of these records), use the
56 ``-print-enums`` option:
57
58 .. code-block:: bash
59
60 $ llvm-tblgen X86.td -print-enums -class=Register
61 AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
62 ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
63 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
64 R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
65 R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
66 RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
67 XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
68 XMM6, XMM7, XMM8, XMM9,
69
70 $ llvm-tblgen X86.td -print-enums -class=Instruction
71 ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
72 ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
73 ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
74 ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
75 ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
76
77 The default backend prints out all of the records.
78
79 If you plan to use TableGen, you will most likely have to write a `backend`_
80 that extracts the information specific to what you need and formats it in the
81 appropriate way.
82
83 Example
84 -------
85
86 With no other arguments, `llvm-tblgen` parses the specified file and prints out all
87 of the classes, then all of the definitions. This is a good way to see what the
88 various definitions expand to fully. Running this on the ``X86.td`` file prints
89 this (at the time of this writing):
90
91 .. code-block:: llvm
92
93 ...
94 def ADD32rr { // Instruction X86Inst I
95 string Namespace = "X86";
96 dag OutOperandList = (outs GR32:$dst);
97 dag InOperandList = (ins GR32:$src1, GR32:$src2);
98 string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
99 list Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
100 list Uses = [];
101 list Defs = [EFLAGS];
102 list Predicates = [];
103 int CodeSize = 3;
104 int AddedComplexity = 0;
105 bit isReturn = 0;
106 bit isBranch = 0;
107 bit isIndirectBranch = 0;
108 bit isBarrier = 0;
109 bit isCall = 0;
110 bit canFoldAsLoad = 0;
111 bit mayLoad = 0;
112 bit mayStore = 0;
113 bit isImplicitDef = 0;
114 bit isConvertibleToThreeAddress = 1;
115 bit isCommutable = 1;
116 bit isTerminator = 0;
117 bit isReMaterializable = 0;
118 bit isPredicable = 0;
119 bit hasDelaySlot = 0;
120 bit usesCustomInserter = 0;
121 bit hasCtrlDep = 0;
122 bit isNotDuplicable = 0;
123 bit hasSideEffects = 0;
124 bit neverHasSideEffects = 0;
125 InstrItinClass Itinerary = NoItinerary;
126 string Constraints = "";
127 string DisableEncoding = "";
128 bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
129 Format Form = MRMDestReg;
130 bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
131 ImmType ImmT = NoImm;
132 bits<3> ImmTypeBits = { 0, 0, 0 };
133 bit hasOpSizePrefix = 0;
134 bit hasAdSizePrefix = 0;
135 bits<4> Prefix = { 0, 0, 0, 0 };
136 bit hasREX_WPrefix = 0;
137 FPFormat FPForm = ?;
138 bits<3> FPFormBits = { 0, 0, 0 };
139 }
140 ...
141
142 This definition corresponds to the 32-bit register-register ``add`` instruction
143 of the x86 architecture. ``def ADD32rr`` defines a record named
144 ``ADD32rr``, and the comment at the end of the line indicates the superclasses
145 of the definition. The body of the record contains all of the data that
146 TableGen assembled for the record, indicating that the instruction is part of
147 the "X86" namespace, the pattern indicating how the instruction should be
148 emitted into the assembly file, that it is a two-address instruction, has a
149 particular encoding, etc. The contents and semantics of the information in the
150 record are specific to the needs of the X86 backend, and are only shown as an
151 example.
152
153 As you can see, a lot of information is needed for every instruction supported
154 by the code generator, and specifying it all manually would be unmaintainable,
155 prone to bugs, and tiring to do in the first place. Because we are using
156 TableGen, all of the information was derived from the following definition:
157
158 .. code-block:: llvm
159
160 let Defs = [EFLAGS],
161 isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
162 isConvertibleToThreeAddress = 1 in // Can transform into LEA.
163 def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),
164 (ins GR32:$src1, GR32:$src2),
165 "add{l}\t{$src2, $dst|$dst, $src2}",
166 [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
167
168 This definition makes use of the custom class ``I`` (extended from the custom
169 class ``X86Inst``), which is defined in the X86-specific TableGen file, to
170 factor out the common features that instructions of its class share. A key
171 feature of TableGen is that it allows the end-user to define the abstractions
172 they prefer to use when describing their information.
173
174 Each ``def`` record has a special entry called "NAME". This is the name of the
175 record ("``ADD32rr``" above). In the general case ``def`` names can be formed
176 from various kinds of string processing expressions and ``NAME`` resolves to the
177 final value obtained after resolving all of those expressions. The user may
178 refer to ``NAME`` anywhere she desires to use the ultimate name of the ``def``.
179 ``NAME`` should not be defined anywhere else in user code to avoid conflicts.
180
181 Syntax
182 ======
183
184 TableGen has a syntax that is losely based on C++ templates, with built-in
185 types and specification. In addition, TableGen's syntax introduces some
186 automation concepts like multiclass, foreach, let, etc.
187
188 Basic concepts
189 --------------
190
191 TableGen files consist of two key parts: 'classes' and 'definitions', both of
192 which are considered 'records'.
193
194 **TableGen records** have a unique name, a list of values, and a list of
195 superclasses. The list of values is the main data that TableGen builds for each
196 record; it is this that holds the domain specific information for the
197 application. The interpretation of this data is left to a specific `backends`_,
198 but the structure and format rules are taken care of and are fixed by
199 TableGen.
200
201 **TableGen definitions** are the concrete form of 'records'. These generally do
202 not have any undefined values, and are marked with the '``def``' keyword.
203
204 .. code-block:: llvm
205
206 def FeatureFPARMv8 : SubtargetFeature<"fp-armv8", "HasFPARMv8", "true",
207 "Enable ARMv8 FP">;
208
209 In this example, FeatureFPARMv8 is ``SubtargetFeature`` record initialised
210 with some values. The names of the classes are defined via the
211 keyword `class` either on the same file or some other included. Most target
212 TableGen files include the generic ones in ``include/llvm/Target``.
213
214 **TableGen classes** are abstract records that are used to build and describe
215 other records. These classes allow the end-user to build abstractions for
216 either the domain they are targeting (such as "Register", "RegisterClass", and
217 "Instruction" in the LLVM code generator) or for the implementor to help factor
218 out common properties of records (such as "FPInst", which is used to represent
219 floating point instructions in the X86 backend). TableGen keeps track of all of
220 the classes that are used to build up a definition, so the backend can find all
221 definitions of a particular class, such as "Instruction".
222
223 .. code-block:: llvm
224
225 class ProcNoItin Features>
226 : Processor;
227
228 Here, the class ProcNoItin, receiving parameters `Name` of type `string` and
229 a list of target features is specializing the class Processor by passing the
230 arguments down as well as hard-coding NoItineraries.
231
232 **TableGen multiclasses** are groups of abstract records that are instantiated
233 all at once. Each instantiation can result in multiple TableGen definitions.
234 If a multiclass inherits from another multiclass, the definitions in the
235 sub-multiclass become part of the current multiclass, as if they were declared
236 in the current multiclass.
237
238 .. code-block:: llvm
239
240 multiclass ro_signed_pats
241 dag address, ValueType sty> {
242 def : Pat<(i32 (!cast("sextload" # sty) address)),
243 (!cast("LDRS" # T # "w_" # Rm # "_RegOffset")
244 Base, Offset, Extend)>;
245
246 def : Pat<(i64 (!cast("sextload" # sty) address)),
247 (!cast("LDRS" # T # "x_" # Rm # "_RegOffset")
248 Base, Offset, Extend)>;
249 }
250
251 defm : ro_signed_pats<"B", Rm, Base, Offset, Extend,
252 !foreach(decls.pattern, address,
253 !subst(SHIFT, imm_eq0, decls.pattern)),
254 i8>;
255
256
257
258 See the `TableGen Language Reference `_ for more information.
259
260 .. _backend:
261 .. _backends:
262
263 TableGen backends
264 =================
265
266 TableGen files have no real meaning without a back-end. The default operation
267 of running ``llvm-tblgen`` is to print the information in a textual format, but
268 that's only useful for debugging of the TableGen files themselves. The power
269 in TableGen is, however, to interpret the source files into an internal
270 representation that can be generated into anything you want.
271
272 Current usage of TableGen is to create include huge files with tables that you
273 can either include directly (if the output is in the language you're coding),
274 or be used in pre-processing via macros surrounding the include of the file.
275
276 Direct output can be used if the back-end already prints a table in C format
277 or if the output is just a list of strings (for error and warning messages).
278 Pre-processed output should be used if the same information needs to be used
279 in different contexts (like Instruction names), so your back-end should print
280 a meta-information list that can be shaped into different compile-time formats.
281
282 See the `TableGen BackEnds `_ for more information.
283
284 TableGen Deficiencies
285 =====================
286
287 Despite being very generic, TableGen has some deficiencies that have been
288 pointed out numerous times. The common theme is that, while TableGen allows
289 you to build Domain-Specific-Languages, the final languages that you create
290 lack the power of other DSLs, which in turn increase considerably the size
291 and complecity of TableGen files.
292
293 At the same time, TableGen allows you to create virtually any meaning of
294 the basic concepts via custom-made back-ends, which can pervert the original
295 design and make it very hard for newcomers to understand the evil TableGen
296 file.
297
298 There are some in favour of extending the semantics even more, but makeing sure
299 back-ends adhere to strict rules. Others suggesting we should move to less,
300 more powerful DSLs designed with specific purposes, or even re-using existing
301 DSLs.
302
303 Either way, this is a discussion that is likely spanning across several years,
304 if not decades. You can read more in the `TableGen Deficiencies `_
305 document.
221221 LinkTimeOptimization
222222 SegmentedStacks
223223 TableGenFundamentals
224 TableGen/index
224225 DebuggingJITedCode
225226 GoldPlugin
226227 MarkedUpDisassembly
230231 WritingAnLLVMBackend
231232 GarbageCollection
232233 WritingAnLLVMPass
233 TableGen/LangRef
234234 HowToUseAttributes
235235 NVPTXUsage
236236 StackMaps