]>
Commit | Line | Data |
---|---|---|
1 | ================= | |
2 | TableGen BackEnds | |
3 | ================= | |
4 | ||
5 | .. contents:: | |
6 | :local: | |
7 | ||
8 | Introduction | |
9 | ============ | |
10 | ||
11 | TableGen backends are at the core of TableGen's functionality. The source files | |
12 | provide the semantics to a generated (in memory) structure, but it's up to the | |
13 | backend to print this out in a way that is meaningful to the user (normally a | |
14 | C program including a file or a textual list of warnings, options and error | |
15 | messages). | |
16 | ||
17 | TableGen is used by both LLVM and Clang with very different goals. LLVM uses it | |
18 | as a way to automate the generation of massive amounts of information regarding | |
19 | instructions, schedules, cores and architecture features. Some backends generate | |
20 | output that is consumed by more than one source file, so they need to be created | |
21 | in a way that is easy to use pre-processor tricks. Some backends can also print | |
22 | C code structures, so that they can be directly included as-is. | |
23 | ||
24 | Clang, on the other hand, uses it mainly for diagnostic messages (errors, | |
25 | warnings, tips) and attributes, so more on the textual end of the scale. | |
26 | ||
27 | LLVM BackEnds | |
28 | ============= | |
29 | ||
30 | .. warning:: | |
31 | This document is raw. Each section below needs three sub-sections: description | |
32 | of its purpose with a list of users, output generated from generic input, and | |
33 | finally why it needed a new backend (in case there's something similar). | |
34 | ||
35 | Overall, each backend will take the same TableGen file type and transform into | |
36 | similar output for different targets/uses. There is an implicit contract between | |
37 | the TableGen files, the back-ends and their users. | |
38 | ||
39 | For instance, a global contract is that each back-end produces macro-guarded | |
40 | sections. Based on whether the file is included by a header or a source file, | |
41 | or even in which context of each file the include is being used, you have | |
42 | todefine a macro just before including it, to get the right output: | |
43 | ||
44 | .. code-block:: c++ | |
45 | ||
46 | #define GET_REGINFO_TARGET_DESC | |
47 | #include "ARMGenRegisterInfo.inc" | |
48 | ||
49 | And just part of the generated file would be included. This is useful if | |
50 | you need the same information in multiple formats (instantiation, initialization, | |
51 | getter/setter functions, etc) from the same source TableGen file without having | |
52 | to re-compile the TableGen file multiple times. | |
53 | ||
54 | Sometimes, multiple macros might be defined before the same include file to | |
55 | output multiple blocks: | |
56 | ||
57 | .. code-block:: c++ | |
58 | ||
59 | #define GET_REGISTER_MATCHER | |
60 | #define GET_SUBTARGET_FEATURE_NAME | |
61 | #define GET_MATCHER_IMPLEMENTATION | |
62 | #include "ARMGenAsmMatcher.inc" | |
63 | ||
64 | The macros will be undef'd automatically as they're used, in the include file. | |
65 | ||
66 | On all LLVM back-ends, the ``llvm-tblgen`` binary will be executed on the root | |
67 | TableGen file ``<Target>.td``, which should include all others. This guarantees | |
68 | that all information needed is accessible, and that no duplication is needed | |
69 | in the TbleGen files. | |
70 | ||
71 | CodeEmitter | |
72 | ----------- | |
73 | ||
74 | **Purpose**: CodeEmitterGen uses the descriptions of instructions and their fields to | |
75 | construct an automated code emitter: a function that, given a MachineInstr, | |
76 | returns the (currently, 32-bit unsigned) value of the instruction. | |
77 | ||
78 | **Output**: C++ code, implementing the target's CodeEmitter | |
79 | class by overriding the virtual functions as ``<Target>CodeEmitter::function()``. | |
80 | ||
81 | **Usage**: Used to include directly at the end of ``<Target>MCCodeEmitter.cpp``. | |
82 | ||
83 | RegisterInfo | |
84 | ------------ | |
85 | ||
86 | **Purpose**: This tablegen backend is responsible for emitting a description of a target | |
87 | register file for a code generator. It uses instances of the Register, | |
88 | RegisterAliases, and RegisterClass classes to gather this information. | |
89 | ||
90 | **Output**: C++ code with enums and structures representing the register mappings, | |
91 | properties, masks, etc. | |
92 | ||
93 | **Usage**: Both on ``<Target>BaseRegisterInfo`` and ``<Target>MCTargetDesc`` (headers | |
94 | and source files) with macros defining in which they are for declaration vs. | |
95 | initialization issues. | |
96 | ||
97 | InstrInfo | |
98 | --------- | |
99 | ||
100 | **Purpose**: This tablegen backend is responsible for emitting a description of the target | |
101 | instruction set for the code generator. (what are the differences from CodeEmitter?) | |
102 | ||
103 | **Output**: C++ code with enums and structures representing the register mappings, | |
104 | properties, masks, etc. | |
105 | ||
106 | **Usage**: Both on ``<Target>BaseInstrInfo`` and ``<Target>MCTargetDesc`` (headers | |
107 | and source files) with macros defining in which they are for declaration vs. | |
108 | ||
109 | AsmWriter | |
110 | --------- | |
111 | ||
112 | **Purpose**: Emits an assembly printer for the current target. | |
113 | ||
114 | **Output**: Implementation of ``<Target>InstPrinter::printInstruction()``, among | |
115 | other things. | |
116 | ||
117 | **Usage**: Included directly into ``InstPrinter/<Target>InstPrinter.cpp``. | |
118 | ||
119 | AsmMatcher | |
120 | ---------- | |
121 | ||
122 | **Purpose**: Emits a target specifier matcher for | |
123 | converting parsed assembly operands in the MCInst structures. It also | |
124 | emits a matcher for custom operand parsing. Extensive documentation is | |
125 | written on the ``AsmMatcherEmitter.cpp`` file. | |
126 | ||
127 | **Output**: Assembler parsers' matcher functions, declarations, etc. | |
128 | ||
129 | **Usage**: Used in back-ends' ``AsmParser/<Target>AsmParser.cpp`` for | |
130 | building the AsmParser class. | |
131 | ||
132 | Disassembler | |
133 | ------------ | |
134 | ||
135 | **Purpose**: Contains disassembler table emitters for various | |
136 | architectures. Extensive documentation is written on the | |
137 | ``DisassemblerEmitter.cpp`` file. | |
138 | ||
139 | **Output**: Decoding tables, static decoding functions, etc. | |
140 | ||
141 | **Usage**: Directly included in ``Disassembler/<Target>Disassembler.cpp`` | |
142 | to cater for all default decodings, after all hand-made ones. | |
143 | ||
144 | PseudoLowering | |
145 | -------------- | |
146 | ||
147 | **Purpose**: Generate pseudo instruction lowering. | |
148 | ||
149 | **Output**: Implements ``ARMAsmPrinter::emitPseudoExpansionLowering()``. | |
150 | ||
151 | **Usage**: Included directly into ``<Target>AsmPrinter.cpp``. | |
152 | ||
153 | CallingConv | |
154 | ----------- | |
155 | ||
156 | **Purpose**: Responsible for emitting descriptions of the calling | |
157 | conventions supported by this target. | |
158 | ||
159 | **Output**: Implement static functions to deal with calling conventions | |
160 | chained by matching styles, returning false on no match. | |
161 | ||
162 | **Usage**: Used in ISelLowering and FastIsel as function pointers to | |
163 | implementation returned by a CC sellection function. | |
164 | ||
165 | DAGISel | |
166 | ------- | |
167 | ||
168 | **Purpose**: Generate a DAG instruction selector. | |
169 | ||
170 | **Output**: Creates huge functions for automating DAG selection. | |
171 | ||
172 | **Usage**: Included in ``<Target>ISelDAGToDAG.cpp`` inside the target's | |
173 | implementation of ``SelectionDAGISel``. | |
174 | ||
175 | DFAPacketizer | |
176 | ------------- | |
177 | ||
178 | **Purpose**: This class parses the Schedule.td file and produces an API that | |
179 | can be used to reason about whether an instruction can be added to a packet | |
180 | on a VLIW architecture. The class internally generates a deterministic finite | |
181 | automaton (DFA) that models all possible mappings of machine instructions | |
182 | to functional units as instructions are added to a packet. | |
183 | ||
184 | **Output**: Scheduling tables for GPU back-ends (Hexagon, AMD). | |
185 | ||
186 | **Usage**: Included directly on ``<Target>InstrInfo.cpp``. | |
187 | ||
188 | FastISel | |
189 | -------- | |
190 | ||
191 | **Purpose**: This tablegen backend emits code for use by the "fast" | |
192 | instruction selection algorithm. See the comments at the top of | |
193 | lib/CodeGen/SelectionDAG/FastISel.cpp for background. This file | |
194 | scans through the target's tablegen instruction-info files | |
195 | and extracts instructions with obvious-looking patterns, and it emits | |
196 | code to look up these instructions by type and operator. | |
197 | ||
198 | **Output**: Generates ``Predicate`` and ``FastEmit`` methods. | |
199 | ||
200 | **Usage**: Implements private methods of the targets' implementation | |
201 | of ``FastISel`` class. | |
202 | ||
203 | Subtarget | |
204 | --------- | |
205 | ||
206 | **Purpose**: Generate subtarget enumerations. | |
207 | ||
208 | **Output**: Enums, globals, local tables for sub-target information. | |
209 | ||
210 | **Usage**: Populates ``<Target>Subtarget`` and | |
211 | ``MCTargetDesc/<Target>MCTargetDesc`` files (both headers and source). | |
212 | ||
213 | Intrinsic | |
214 | --------- | |
215 | ||
216 | **Purpose**: Generate (target) intrinsic information. | |
217 | ||
218 | OptParserDefs | |
219 | ------------- | |
220 | ||
221 | **Purpose**: Print enum values for a class. | |
222 | ||
223 | CTags | |
224 | ----- | |
225 | ||
226 | **Purpose**: This tablegen backend emits an index of definitions in ctags(1) | |
227 | format. A helper script, utils/TableGen/tdtags, provides an easier-to-use | |
228 | interface; run 'tdtags -H' for documentation. | |
229 | ||
230 | Clang BackEnds | |
231 | ============== | |
232 | ||
233 | ClangAttrClasses | |
234 | ---------------- | |
235 | ||
236 | **Purpose**: Creates Attrs.inc, which contains semantic attribute class | |
237 | declarations for any attribute in ``Attr.td`` that has not set ``ASTNode = 0``. | |
238 | This file is included as part of ``Attr.h``. | |
239 | ||
240 | ClangAttrParserStringSwitches | |
241 | ----------------------------- | |
242 | ||
243 | **Purpose**: Creates AttrParserStringSwitches.inc, which contains | |
244 | StringSwitch::Case statements for parser-related string switches. Each switch | |
245 | is given its own macro (such as ``CLANG_ATTR_ARG_CONTEXT_LIST``, or | |
246 | ``CLANG_ATTR_IDENTIFIER_ARG_LIST``), which is expected to be defined before | |
247 | including AttrParserStringSwitches.inc, and undefined after. | |
248 | ||
249 | ClangAttrImpl | |
250 | ------------- | |
251 | ||
252 | **Purpose**: Creates AttrImpl.inc, which contains semantic attribute class | |
253 | definitions for any attribute in ``Attr.td`` that has not set ``ASTNode = 0``. | |
254 | This file is included as part of ``AttrImpl.cpp``. | |
255 | ||
256 | ClangAttrList | |
257 | ------------- | |
258 | ||
259 | **Purpose**: Creates AttrList.inc, which is used when a list of semantic | |
260 | attribute identifiers is required. For instance, ``AttrKinds.h`` includes this | |
261 | file to generate the list of ``attr::Kind`` enumeration values. This list is | |
262 | separated out into multiple categories: attributes, inheritable attributes, and | |
263 | inheritable parameter attributes. This categorization happens automatically | |
264 | based on information in ``Attr.td`` and is used to implement the ``classof`` | |
265 | functionality required for ``dyn_cast`` and similar APIs. | |
266 | ||
267 | ClangAttrPCHRead | |
268 | ---------------- | |
269 | ||
270 | **Purpose**: Creates AttrPCHRead.inc, which is used to deserialize attributes | |
271 | in the ``ASTReader::ReadAttributes`` function. | |
272 | ||
273 | ClangAttrPCHWrite | |
274 | ----------------- | |
275 | ||
276 | **Purpose**: Creates AttrPCHWrite.inc, which is used to serialize attributes in | |
277 | the ``ASTWriter::WriteAttributes`` function. | |
278 | ||
279 | ClangAttrSpellings | |
280 | --------------------- | |
281 | ||
282 | **Purpose**: Creates AttrSpellings.inc, which is used to implement the | |
283 | ``__has_attribute`` feature test macro. | |
284 | ||
285 | ClangAttrSpellingListIndex | |
286 | -------------------------- | |
287 | ||
288 | **Purpose**: Creates AttrSpellingListIndex.inc, which is used to map parsed | |
289 | attribute spellings (including which syntax or scope was used) to an attribute | |
290 | spelling list index. These spelling list index values are internal | |
291 | implementation details exposed via | |
292 | ``AttributeList::getAttributeSpellingListIndex``. | |
293 | ||
294 | ClangAttrVisitor | |
295 | ------------------- | |
296 | ||
297 | **Purpose**: Creates AttrVisitor.inc, which is used when implementing | |
298 | recursive AST visitors. | |
299 | ||
300 | ClangAttrTemplateInstantiate | |
301 | ---------------------------- | |
302 | ||
303 | **Purpose**: Creates AttrTemplateInstantiate.inc, which implements the | |
304 | ``instantiateTemplateAttribute`` function, used when instantiating a template | |
305 | that requires an attribute to be cloned. | |
306 | ||
307 | ClangAttrParsedAttrList | |
308 | ----------------------- | |
309 | ||
310 | **Purpose**: Creates AttrParsedAttrList.inc, which is used to generate the | |
311 | ``AttributeList::Kind`` parsed attribute enumeration. | |
312 | ||
313 | ClangAttrParsedAttrImpl | |
314 | ----------------------- | |
315 | ||
316 | **Purpose**: Creates AttrParsedAttrImpl.inc, which is used by | |
317 | ``AttributeList.cpp`` to implement several functions on the ``AttributeList`` | |
318 | class. This functionality is implemented via the ``AttrInfoMap ParsedAttrInfo`` | |
319 | array, which contains one element per parsed attribute object. | |
320 | ||
321 | ClangAttrParsedAttrKinds | |
322 | ------------------------ | |
323 | ||
324 | **Purpose**: Creates AttrParsedAttrKinds.inc, which is used to implement the | |
325 | ``AttributeList::getKind`` function, mapping a string (and syntax) to a parsed | |
326 | attribute ``AttributeList::Kind`` enumeration. | |
327 | ||
328 | ClangAttrDump | |
329 | ------------- | |
330 | ||
331 | **Purpose**: Creates AttrDump.inc, which dumps information about an attribute. | |
332 | It is used to implement ``ASTDumper::dumpAttr``. | |
333 | ||
334 | ClangDiagsDefs | |
335 | -------------- | |
336 | ||
337 | Generate Clang diagnostics definitions. | |
338 | ||
339 | ClangDiagGroups | |
340 | --------------- | |
341 | ||
342 | Generate Clang diagnostic groups. | |
343 | ||
344 | ClangDiagsIndexName | |
345 | ------------------- | |
346 | ||
347 | Generate Clang diagnostic name index. | |
348 | ||
349 | ClangCommentNodes | |
350 | ----------------- | |
351 | ||
352 | Generate Clang AST comment nodes. | |
353 | ||
354 | ClangDeclNodes | |
355 | -------------- | |
356 | ||
357 | Generate Clang AST declaration nodes. | |
358 | ||
359 | ClangStmtNodes | |
360 | -------------- | |
361 | ||
362 | Generate Clang AST statement nodes. | |
363 | ||
364 | ClangSACheckers | |
365 | --------------- | |
366 | ||
367 | Generate Clang Static Analyzer checkers. | |
368 | ||
369 | ClangCommentHTMLTags | |
370 | -------------------- | |
371 | ||
372 | Generate efficient matchers for HTML tag names that are used in documentation comments. | |
373 | ||
374 | ClangCommentHTMLTagsProperties | |
375 | ------------------------------ | |
376 | ||
377 | Generate efficient matchers for HTML tag properties. | |
378 | ||
379 | ClangCommentHTMLNamedCharacterReferences | |
380 | ---------------------------------------- | |
381 | ||
382 | Generate function to translate named character references to UTF-8 sequences. | |
383 | ||
384 | ClangCommentCommandInfo | |
385 | ----------------------- | |
386 | ||
387 | Generate command properties for commands that are used in documentation comments. | |
388 | ||
389 | ClangCommentCommandList | |
390 | ----------------------- | |
391 | ||
392 | Generate list of commands that are used in documentation comments. | |
393 | ||
394 | ArmNeon | |
395 | ------- | |
396 | ||
397 | Generate arm_neon.h for clang. | |
398 | ||
399 | ArmNeonSema | |
400 | ----------- | |
401 | ||
402 | Generate ARM NEON sema support for clang. | |
403 | ||
404 | ArmNeonTest | |
405 | ----------- | |
406 | ||
407 | Generate ARM NEON tests for clang. | |
408 | ||
409 | AttrDocs | |
410 | -------- | |
411 | ||
412 | **Purpose**: Creates ``AttributeReference.rst`` from ``AttrDocs.td``, and is | |
413 | used for documenting user-facing attributes. | |
414 | ||
415 | How to write a back-end | |
416 | ======================= | |
417 | ||
418 | TODO. | |
419 | ||
420 | Until we get a step-by-step HowTo for writing TableGen backends, you can at | |
421 | least grab the boilerplate (build system, new files, etc.) from Clang's | |
422 | r173931. | |
423 | ||
424 | TODO: How they work, how to write one. This section should not contain details | |
425 | about any particular backend, except maybe ``-print-enums`` as an example. This | |
426 | should highlight the APIs in ``TableGen/Record.h``. | |
427 |