1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>TableGen Overview — LLVM 13 documentation</title>
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="TableGen BackEnds" href="BackEnds.html" />
<link rel="prev" title="Support Library" href="../SupportLibrary.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="../index.html">
<img src="../_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="BackEnds.html" title="TableGen BackEnds"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../SupportLibrary.html" title="Support Library"
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="../index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="../UserGuides.html" accesskey="U">User Guides</a> »</li>
<li class="nav-item nav-item-this"><a href="">TableGen Overview</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/TableGen/index.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="tablegen-overview">
<h1>TableGen Overview<a class="headerlink" href="#tablegen-overview" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#introduction" id="id1">Introduction</a></p></li>
<li><p><a class="reference internal" href="#the-tablegen-program" id="id2">The TableGen program</a></p>
<ul>
<li><p><a class="reference internal" href="#running-tablegen" id="id3">Running TableGen</a></p></li>
<li><p><a class="reference internal" href="#example" id="id4">Example</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#syntax" id="id5">Syntax</a></p>
<ul>
<li><p><a class="reference internal" href="#basic-concepts" id="id6">Basic concepts</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#tablegen-backends" id="id7">TableGen backends</a></p></li>
<li><p><a class="reference internal" href="#tablegen-deficiencies" id="id8">TableGen Deficiencies</a></p></li>
</ul>
</div>
<div class="toctree-wrapper compound">
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>TableGen’s purpose is to help a human develop and maintain records of
domain-specific information. Because there may be a large number of these
records, it is specifically designed to allow writing flexible descriptions and
for common features of these records to be factored out. This reduces the
amount of duplication in the description, reduces the chance of error, and makes
it easier to structure domain specific information.</p>
<p>The TableGen front end parses a file, instantiates the declarations, and
hands the result off to a domain-specific <a class="reference internal" href="#backend">backend</a> for processing. See
the <a class="reference internal" href="ProgRef.html"><span class="doc">TableGen Programmer’s Reference</span></a> for an in-depth
description of TableGen. See <a class="reference internal" href="../CommandGuide/tblgen.html"><span class="doc">tblgen - Description to C++ Code</span></a> for details on the <code class="docutils literal notranslate"><span class="pre">*-tblgen</span></code> commands
that run the various flavors of TableGen.</p>
<p>The current major users of TableGen are <a class="reference internal" href="../CodeGenerator.html"><span class="doc">The LLVM Target-Independent
Code Generator</span></a> and the <a class="reference external" href="https://clang.llvm.org/docs/UsersManual.html#controlling-errors-and-warnings">Clang diagnostics and attributes</a>.</p>
<p>Note that if you work with TableGen frequently and use emacs or vim,
you can find an emacs “TableGen mode” and a vim language file in the
<code class="docutils literal notranslate"><span class="pre">llvm/utils/emacs</span></code> and <code class="docutils literal notranslate"><span class="pre">llvm/utils/vim</span></code> directories of your LLVM
distribution, respectively.</p>
</div>
<div class="section" id="the-tablegen-program">
<span id="intro"></span><h2><a class="toc-backref" href="#id2">The TableGen program</a><a class="headerlink" href="#the-tablegen-program" title="Permalink to this headline">¶</a></h2>
<p>TableGen files are interpreted by the TableGen program: <cite>llvm-tblgen</cite> available
on your build directory under <cite>bin</cite>. It is not installed in the system (or where
your sysroot is set to), since it has no use beyond LLVM’s build process.</p>
<div class="section" id="running-tablegen">
<h3><a class="toc-backref" href="#id3">Running TableGen</a><a class="headerlink" href="#running-tablegen" title="Permalink to this headline">¶</a></h3>
<p>TableGen runs just like any other LLVM tool. The first (optional) argument
specifies the file to read. If a filename is not specified, <code class="docutils literal notranslate"><span class="pre">llvm-tblgen</span></code>
reads from standard input.</p>
<p>To be useful, one of the <a class="reference internal" href="#backends">backends</a> must be used. These backends are
selectable on the command line (type ‘<code class="docutils literal notranslate"><span class="pre">llvm-tblgen</span> <span class="pre">-help</span></code>’ for a list). For
example, to get a list of all of the definitions that subclass a particular type
(which can be useful for building up an enum list of these records), use the
<code class="docutils literal notranslate"><span class="pre">-print-enums</span></code> option:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llvm-tblgen X86.td -print-enums -class<span class="o">=</span>Register
AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
XMM6, XMM7, XMM8, XMM9,
$ llvm-tblgen X86.td -print-enums -class<span class="o">=</span>Instruction
ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
</pre></div>
</div>
<p>The default backend prints out all of the records. There is also a general
backend which outputs all the records as a JSON data structure, enabled using
the <cite>-dump-json</cite> option.</p>
<p>If you plan to use TableGen, you will most likely have to write a <a class="reference internal" href="#backend">backend</a>
that extracts the information specific to what you need and formats it in the
appropriate way. You can do this by extending TableGen itself in C++, or by
writing a script in any language that can consume the JSON output.</p>
</div>
<div class="section" id="example">
<h3><a class="toc-backref" href="#id4">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
<p>With no other arguments, <cite>llvm-tblgen</cite> parses the specified file and prints out all
of the classes, then all of the definitions. This is a good way to see what the
various definitions expand to fully. Running this on the <code class="docutils literal notranslate"><span class="pre">X86.td</span></code> file prints
this (at the time of this writing):</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>...
def ADD32rr { // Instruction X86Inst I
string Namespace = "X86";
dag OutOperandList = (outs GR32:$dst);
dag InOperandList = (ins GR32:$src1, GR32:$src2);
string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
list<Register> Uses = [];
list<Register> Defs = [EFLAGS];
list<Predicate> Predicates = [];
int CodeSize = 3;
int AddedComplexity = 0;
bit isReturn = 0;
bit isBranch = 0;
bit isIndirectBranch = 0;
bit isBarrier = 0;
bit isCall = 0;
bit canFoldAsLoad = 0;
bit mayLoad = 0;
bit mayStore = 0;
bit isImplicitDef = 0;
bit isConvertibleToThreeAddress = 1;
bit isCommutable = 1;
bit isTerminator = 0;
bit isReMaterializable = 0;
bit isPredicable = 0;
bit hasDelaySlot = 0;
bit usesCustomInserter = 0;
bit hasCtrlDep = 0;
bit isNotDuplicable = 0;
bit hasSideEffects = 0;
InstrItinClass Itinerary = NoItinerary;
string Constraints = "";
string DisableEncoding = "";
bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
Format Form = MRMDestReg;
bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
ImmType ImmT = NoImm;
bits<3> ImmTypeBits = { 0, 0, 0 };
bit hasOpSizePrefix = 0;
bit hasAdSizePrefix = 0;
bits<4> Prefix = { 0, 0, 0, 0 };
bit hasREX_WPrefix = 0;
FPFormat FPForm = ?;
bits<3> FPFormBits = { 0, 0, 0 };
}
...
</pre></div>
</div>
<p>This definition corresponds to the 32-bit register-register <code class="docutils literal notranslate"><span class="pre">add</span></code> instruction
of the x86 architecture. <code class="docutils literal notranslate"><span class="pre">def</span> <span class="pre">ADD32rr</span></code> defines a record named
<code class="docutils literal notranslate"><span class="pre">ADD32rr</span></code>, and the comment at the end of the line indicates the superclasses
of the definition. The body of the record contains all of the data that
TableGen assembled for the record, indicating that the instruction is part of
the “X86” namespace, the pattern indicating how the instruction is selected by
the code generator, that it is a two-address instruction, has a particular
encoding, etc. The contents and semantics of the information in the record are
specific to the needs of the X86 backend, and are only shown as an example.</p>
<p>As you can see, a lot of information is needed for every instruction supported
by the code generator, and specifying it all manually would be unmaintainable,
prone to bugs, and tiring to do in the first place. Because we are using
TableGen, all of the information was derived from the following definition:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>let Defs = [EFLAGS],
isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
isConvertibleToThreeAddress = 1 in // Can transform into LEA.
def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),
(ins GR32:$src1, GR32:$src2),
"add{l}\t{$src2, $dst|$dst, $src2}",
[(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
</pre></div>
</div>
<p>This definition makes use of the custom class <code class="docutils literal notranslate"><span class="pre">I</span></code> (extended from the custom
class <code class="docutils literal notranslate"><span class="pre">X86Inst</span></code>), which is defined in the X86-specific TableGen file, to
factor out the common features that instructions of its class share. A key
feature of TableGen is that it allows the end-user to define the abstractions
they prefer to use when describing their information.</p>
</div>
</div>
<div class="section" id="syntax">
<h2><a class="toc-backref" href="#id5">Syntax</a><a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<p>TableGen has a syntax that is loosely based on C++ templates, with built-in
types and specification. In addition, TableGen’s syntax introduces some
automation concepts like multiclass, foreach, let, etc.</p>
<div class="section" id="basic-concepts">
<h3><a class="toc-backref" href="#id6">Basic concepts</a><a class="headerlink" href="#basic-concepts" title="Permalink to this headline">¶</a></h3>
<p>TableGen files consist of two key parts: ‘classes’ and ‘definitions’, both of
which are considered ‘records’.</p>
<p><strong>TableGen records</strong> have a unique name, a list of values, and a list of
superclasses. The list of values is the main data that TableGen builds for each
record; it is this that holds the domain specific information for the
application. The interpretation of this data is left to a specific <a class="reference internal" href="#backend">backend</a>,
but the structure and format rules are taken care of and are fixed by
TableGen.</p>
<p><strong>TableGen definitions</strong> are the concrete form of ‘records’. These generally do
not have any undefined values, and are marked with the ‘<code class="docutils literal notranslate"><span class="pre">def</span></code>’ keyword.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>def FeatureFPARMv8 : SubtargetFeature<"fp-armv8", "HasFPARMv8", "true",
"Enable ARMv8 FP">;
</pre></div>
</div>
<p>In this example, FeatureFPARMv8 is <code class="docutils literal notranslate"><span class="pre">SubtargetFeature</span></code> record initialised
with some values. The names of the classes are defined via the
keyword <cite>class</cite> either on the same file or some other included. Most target
TableGen files include the generic ones in <code class="docutils literal notranslate"><span class="pre">include/llvm/Target</span></code>.</p>
<p><strong>TableGen classes</strong> are abstract records that are used to build and describe
other records. These classes allow the end-user to build abstractions for
either the domain they are targeting (such as “Register”, “RegisterClass”, and
“Instruction” in the LLVM code generator) or for the implementor to help factor
out common properties of records (such as “FPInst”, which is used to represent
floating point instructions in the X86 backend). TableGen keeps track of all of
the classes that are used to build up a definition, so the backend can find all
definitions of a particular class, such as “Instruction”.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>class ProcNoItin<string Name, list<SubtargetFeature> Features>
: Processor<Name, NoItineraries, Features>;
</pre></div>
</div>
<p>Here, the class ProcNoItin, receiving parameters <cite>Name</cite> of type <cite>string</cite> and
a list of target features is specializing the class Processor by passing the
arguments down as well as hard-coding NoItineraries.</p>
<p><strong>TableGen multiclasses</strong> are groups of abstract records that are instantiated
all at once. Each instantiation can result in multiple TableGen definitions.
If a multiclass inherits from another multiclass, the definitions in the
sub-multiclass become part of the current multiclass, as if they were declared
in the current multiclass.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>multiclass ro_signed_pats<string T, string Rm, dag Base, dag Offset, dag Extend,
dag address, ValueType sty> {
def : Pat<(i32 (!cast<SDNode>("sextload" # sty) address)),
(!cast<Instruction>("LDRS" # T # "w_" # Rm # "_RegOffset")
Base, Offset, Extend)>;
def : Pat<(i64 (!cast<SDNode>("sextload" # sty) address)),
(!cast<Instruction>("LDRS" # T # "x_" # Rm # "_RegOffset")
Base, Offset, Extend)>;
}
defm : ro_signed_pats<"B", Rm, Base, Offset, Extend,
!foreach(decls.pattern, address,
!subst(SHIFT, imm_eq0, decls.pattern)),
i8>;
</pre></div>
</div>
<p>See the <a class="reference internal" href="ProgRef.html"><span class="doc">TableGen Programmer’s Reference</span></a> for an in-depth
description of TableGen.</p>
</div>
</div>
<div class="section" id="tablegen-backends">
<span id="backends"></span><span id="backend"></span><h2><a class="toc-backref" href="#id7">TableGen backends</a><a class="headerlink" href="#tablegen-backends" title="Permalink to this headline">¶</a></h2>
<p>TableGen files have no real meaning without a backend. The default operation
when running <code class="docutils literal notranslate"><span class="pre">*-tblgen</span></code> is to print the information in a textual format, but
that’s only useful for debugging the TableGen files themselves. The power
in TableGen is, however, to interpret the source files into an internal
representation that can be generated into anything you want.</p>
<p>Current usage of TableGen is to create huge include files with tables that you
can either include directly (if the output is in the language you’re coding),
or be used in pre-processing via macros surrounding the include of the file.</p>
<p>Direct output can be used if the backend already prints a table in C format
or if the output is just a list of strings (for error and warning messages).
Pre-processed output should be used if the same information needs to be used
in different contexts (like Instruction names), so your backend should print
a meta-information list that can be shaped into different compile-time formats.</p>
<p>See <a class="reference internal" href="BackEnds.html"><span class="doc">TableGen BackEnds</span></a> for a list of available
backends, and see the <a class="reference internal" href="BackGuide.html"><span class="doc">TableGen Backend Developer’s Guide</span></a>
for information on how to write and debug a new backend.</p>
</div>
<div class="section" id="tablegen-deficiencies">
<h2><a class="toc-backref" href="#id8">TableGen Deficiencies</a><a class="headerlink" href="#tablegen-deficiencies" title="Permalink to this headline">¶</a></h2>
<p>Despite being very generic, TableGen has some deficiencies that have been
pointed out numerous times. The common theme is that, while TableGen allows
you to build domain specific languages, the final languages that you create
lack the power of other DSLs, which in turn increase considerably the size
and complexity of TableGen files.</p>
<p>At the same time, TableGen allows you to create virtually any meaning of
the basic concepts via custom-made backends, which can pervert the original
design and make it very hard for newcomers to understand the evil TableGen
file.</p>
<p>There are some in favor of extending the semantics even more, but making sure
backends adhere to strict rules. Others are suggesting we should move to less,
more powerful DSLs designed with specific purposes, or even reusing existing
DSLs.</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="BackEnds.html" title="TableGen BackEnds"
>next</a> |</li>
<li class="right" >
<a href="../SupportLibrary.html" title="Support Library"
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="../index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="../UserGuides.html" >User Guides</a> »</li>
<li class="nav-item nav-item-this"><a href="">TableGen Overview</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
