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
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.
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.
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).
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.
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:
46 #define GET_REGINFO_TARGET_DESC
47 #include "ARMGenRegisterInfo.inc"
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.
54 Sometimes, multiple macros might be defined before the same include file to
55 output multiple blocks:
59 #define GET_REGISTER_MATCHER
60 #define GET_SUBTARGET_FEATURE_NAME
61 #define GET_MATCHER_IMPLEMENTATION
62 #include "ARMGenAsmMatcher.inc"
64 The macros will be undef'd automatically as they're used, in the include file.
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
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.
78 **Output**: C++ code, implementing the target's CodeEmitter
79 class by overriding the virtual functions as ``<Target>CodeEmitter::function()``.
81 **Usage**: Used to include directly at the end of ``<Target>CodeEmitter.cpp``, and
82 with option `-mc-emitter` to be included in ``<Target>MCCodeEmitter.cpp``.
87 **Purpose**: This tablegen backend is responsible for emitting a description of a target
88 register file for a code generator. It uses instances of the Register,
89 RegisterAliases, and RegisterClass classes to gather this information.
91 **Output**: C++ code with enums and structures representing the register mappings,
92 properties, masks, etc.
94 **Usage**: Both on ``<Target>BaseRegisterInfo`` and ``<Target>MCTargetDesc`` (headers
95 and source files) with macros defining in which they are for declaration vs.
96 initialization issues.
101 **Purpose**: This tablegen backend is responsible for emitting a description of the target
102 instruction set for the code generator. (what are the differences from CodeEmitter?)
104 **Output**: C++ code with enums and structures representing the register mappings,
105 properties, masks, etc.
107 **Usage**: Both on ``<Target>BaseInstrInfo`` and ``<Target>MCTargetDesc`` (headers
108 and source files) with macros defining in which they are for declaration vs.
113 **Purpose**: Emits an assembly printer for the current target.
115 **Output**: Implementation of ``<Target>InstPrinter::printInstruction()``, among
118 **Usage**: Included directly into ``InstPrinter/<Target>InstPrinter.cpp``.
123 **Purpose**: Emits a target specifier matcher for
124 converting parsed assembly operands in the MCInst structures. It also
125 emits a matcher for custom operand parsing. Extensive documentation is
126 written on the ``AsmMatcherEmitter.cpp`` file.
128 **Output**: Assembler parsers' matcher functions, declarations, etc.
130 **Usage**: Used in back-ends' ``AsmParser/<Target>AsmParser.cpp`` for
131 building the AsmParser class.
136 **Purpose**: Contains disassembler table emitters for various
137 architectures. Extensive documentation is written on the
138 ``DisassemblerEmitter.cpp`` file.
140 **Output**: Decoding tables, static decoding functions, etc.
142 **Usage**: Directly included in ``Disassembler/<Target>Disassembler.cpp``
143 to cater for all default decodings, after all hand-made ones.
148 **Purpose**: Generate pseudo instruction lowering.
150 **Output**: Implements ``ARMAsmPrinter::emitPseudoExpansionLowering()``.
152 **Usage**: Included directly into ``<Target>AsmPrinter.cpp``.
157 **Purpose**: Responsible for emitting descriptions of the calling
158 conventions supported by this target.
160 **Output**: Implement static functions to deal with calling conventions
161 chained by matching styles, returning false on no match.
163 **Usage**: Used in ISelLowering and FastIsel as function pointers to
164 implementation returned by a CC sellection function.
169 **Purpose**: Generate a DAG instruction selector.
171 **Output**: Creates huge functions for automating DAG selection.
173 **Usage**: Included in ``<Target>ISelDAGToDAG.cpp`` inside the target's
174 implementation of ``SelectionDAGISel``.
179 **Purpose**: This class parses the Schedule.td file and produces an API that
180 can be used to reason about whether an instruction can be added to a packet
181 on a VLIW architecture. The class internally generates a deterministic finite
182 automaton (DFA) that models all possible mappings of machine instructions
183 to functional units as instructions are added to a packet.
185 **Output**: Scheduling tables for GPU back-ends (Hexagon, AMD).
187 **Usage**: Included directly on ``<Target>InstrInfo.cpp``.
192 **Purpose**: This tablegen backend emits code for use by the "fast"
193 instruction selection algorithm. See the comments at the top of
194 lib/CodeGen/SelectionDAG/FastISel.cpp for background. This file
195 scans through the target's tablegen instruction-info files
196 and extracts instructions with obvious-looking patterns, and it emits
197 code to look up these instructions by type and operator.
199 **Output**: Generates ``Predicate`` and ``FastEmit`` methods.
201 **Usage**: Implements private methods of the targets' implementation
202 of ``FastISel`` class.
207 **Purpose**: Generate subtarget enumerations.
209 **Output**: Enums, globals, local tables for sub-target information.
211 **Usage**: Populates ``<Target>Subtarget`` and
212 ``MCTargetDesc/<Target>MCTargetDesc`` files (both headers and source).
217 **Purpose**: Generate (target) intrinsic information.
222 **Purpose**: Print enum values for a class.
227 **Purpose**: This tablegen backend emits an index of definitions in ctags(1)
228 format. A helper script, utils/TableGen/tdtags, provides an easier-to-use
229 interface; run 'tdtags -H' for documentation.
237 **Purpose**: Creates Attrs.inc, which contains semantic attribute class
238 declarations for any attribute in ``Attr.td`` that has not set ``ASTNode = 0``.
239 This file is included as part of ``Attr.h``.
241 ClangAttrParserStringSwitches
242 -----------------------------
244 **Purpose**: Creates AttrParserStringSwitches.inc, which contains
245 StringSwitch::Case statements for parser-related string switches. Each switch
246 is given its own macro (such as ``CLANG_ATTR_ARG_CONTEXT_LIST``, or
247 ``CLANG_ATTR_IDENTIFIER_ARG_LIST``), which is expected to be defined before
248 including AttrParserStringSwitches.inc, and undefined after.
253 **Purpose**: Creates AttrImpl.inc, which contains semantic attribute class
254 definitions for any attribute in ``Attr.td`` that has not set ``ASTNode = 0``.
255 This file is included as part of ``AttrImpl.cpp``.
260 **Purpose**: Creates AttrList.inc, which is used when a list of semantic
261 attribute identifiers is required. For instance, ``AttrKinds.h`` includes this
262 file to generate the list of ``attr::Kind`` enumeration values. This list is
263 separated out into multiple categories: attributes, inheritable attributes, and
264 inheritable parameter attributes. This categorization happens automatically
265 based on information in ``Attr.td`` and is used to implement the ``classof``
266 functionality required for ``dyn_cast`` and similar APIs.
271 **Purpose**: Creates AttrPCHRead.inc, which is used to deserialize attributes
272 in the ``ASTReader::ReadAttributes`` function.
277 **Purpose**: Creates AttrPCHWrite.inc, which is used to serialize attributes in
278 the ``ASTWriter::WriteAttributes`` function.
281 ---------------------
283 **Purpose**: Creates AttrSpellings.inc, which is used to implement the
284 ``__has_attribute`` feature test macro.
286 ClangAttrSpellingListIndex
287 --------------------------
289 **Purpose**: Creates AttrSpellingListIndex.inc, which is used to map parsed
290 attribute spellings (including which syntax or scope was used) to an attribute
291 spelling list index. These spelling list index values are internal
292 implementation details exposed via
293 ``AttributeList::getAttributeSpellingListIndex``.
298 **Purpose**: Creates AttrVisitor.inc, which is used when implementing
299 recursive AST visitors.
301 ClangAttrTemplateInstantiate
302 ----------------------------
304 **Purpose**: Creates AttrTemplateInstantiate.inc, which implements the
305 ``instantiateTemplateAttribute`` function, used when instantiating a template
306 that requires an attribute to be cloned.
308 ClangAttrParsedAttrList
309 -----------------------
311 **Purpose**: Creates AttrParsedAttrList.inc, which is used to generate the
312 ``AttributeList::Kind`` parsed attribute enumeration.
314 ClangAttrParsedAttrImpl
315 -----------------------
317 **Purpose**: Creates AttrParsedAttrImpl.inc, which is used by
318 ``AttributeList.cpp`` to implement several functions on the ``AttributeList``
319 class. This functionality is implemented via the ``AttrInfoMap ParsedAttrInfo``
320 array, which contains one element per parsed attribute object.
322 ClangAttrParsedAttrKinds
323 ------------------------
325 **Purpose**: Creates AttrParsedAttrKinds.inc, which is used to implement the
326 ``AttributeList::getKind`` function, mapping a string (and syntax) to a parsed
327 attribute ``AttributeList::Kind`` enumeration.
332 **Purpose**: Creates AttrDump.inc, which dumps information about an attribute.
333 It is used to implement ``ASTDumper::dumpAttr``.
338 Generate Clang diagnostics definitions.
343 Generate Clang diagnostic groups.
348 Generate Clang diagnostic name index.
353 Generate Clang AST comment nodes.
358 Generate Clang AST declaration nodes.
363 Generate Clang AST statement nodes.
368 Generate Clang Static Analyzer checkers.
373 Generate efficient matchers for HTML tag names that are used in documentation comments.
375 ClangCommentHTMLTagsProperties
376 ------------------------------
378 Generate efficient matchers for HTML tag properties.
380 ClangCommentHTMLNamedCharacterReferences
381 ----------------------------------------
383 Generate function to translate named character references to UTF-8 sequences.
385 ClangCommentCommandInfo
386 -----------------------
388 Generate command properties for commands that are used in documentation comments.
390 ClangCommentCommandList
391 -----------------------
393 Generate list of commands that are used in documentation comments.
398 Generate arm_neon.h for clang.
403 Generate ARM NEON sema support for clang.
408 Generate ARM NEON tests for clang.
413 **Purpose**: Creates ``AttributeReference.rst`` from ``AttrDocs.td``, and is
414 used for documenting user-facing attributes.
416 How to write a back-end
417 =======================
421 Until we get a step-by-step HowTo for writing TableGen backends, you can at
422 least grab the boilerplate (build system, new files, etc.) from Clang's
425 TODO: How they work, how to write one. This section should not contain details
426 about any particular backend, except maybe ``-print-enums`` as an example. This
427 should highlight the APIs in ``TableGen/Record.h``.