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>CodeEmitter.cpp``, and 82 with option `-mc-emitter` to be included in ``<Target>MCCodeEmitter.cpp``. 83 84 RegisterInfo 85 ------------ 86 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. 90 91 **Output**: C++ code with enums and structures representing the register mappings, 92 properties, masks, etc. 93 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. 97 98 InstrInfo 99 --------- 100 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?) 103 104 **Output**: C++ code with enums and structures representing the register mappings, 105 properties, masks, etc. 106 107 **Usage**: Both on ``<Target>BaseInstrInfo`` and ``<Target>MCTargetDesc`` (headers 108 and source files) with macros defining in which they are for declaration vs. 109 110 AsmWriter 111 --------- 112 113 **Purpose**: Emits an assembly printer for the current target. 114 115 **Output**: Implementation of ``<Target>InstPrinter::printInstruction()``, among 116 other things. 117 118 **Usage**: Included directly into ``InstPrinter/<Target>InstPrinter.cpp``. 119 120 AsmMatcher 121 ---------- 122 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. 127 128 **Output**: Assembler parsers' matcher functions, declarations, etc. 129 130 **Usage**: Used in back-ends' ``AsmParser/<Target>AsmParser.cpp`` for 131 building the AsmParser class. 132 133 Disassembler 134 ------------ 135 136 **Purpose**: Contains disassembler table emitters for various 137 architectures. Extensive documentation is written on the 138 ``DisassemblerEmitter.cpp`` file. 139 140 **Output**: Decoding tables, static decoding functions, etc. 141 142 **Usage**: Directly included in ``Disassembler/<Target>Disassembler.cpp`` 143 to cater for all default decodings, after all hand-made ones. 144 145 PseudoLowering 146 -------------- 147 148 **Purpose**: Generate pseudo instruction lowering. 149 150 **Output**: Implements ``ARMAsmPrinter::emitPseudoExpansionLowering()``. 151 152 **Usage**: Included directly into ``<Target>AsmPrinter.cpp``. 153 154 CallingConv 155 ----------- 156 157 **Purpose**: Responsible for emitting descriptions of the calling 158 conventions supported by this target. 159 160 **Output**: Implement static functions to deal with calling conventions 161 chained by matching styles, returning false on no match. 162 163 **Usage**: Used in ISelLowering and FastIsel as function pointers to 164 implementation returned by a CC sellection function. 165 166 DAGISel 167 ------- 168 169 **Purpose**: Generate a DAG instruction selector. 170 171 **Output**: Creates huge functions for automating DAG selection. 172 173 **Usage**: Included in ``<Target>ISelDAGToDAG.cpp`` inside the target's 174 implementation of ``SelectionDAGISel``. 175 176 DFAPacketizer 177 ------------- 178 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. 184 185 **Output**: Scheduling tables for GPU back-ends (Hexagon, AMD). 186 187 **Usage**: Included directly on ``<Target>InstrInfo.cpp``. 188 189 FastISel 190 -------- 191 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. 198 199 **Output**: Generates ``Predicate`` and ``FastEmit`` methods. 200 201 **Usage**: Implements private methods of the targets' implementation 202 of ``FastISel`` class. 203 204 Subtarget 205 --------- 206 207 **Purpose**: Generate subtarget enumerations. 208 209 **Output**: Enums, globals, local tables for sub-target information. 210 211 **Usage**: Populates ``<Target>Subtarget`` and 212 ``MCTargetDesc/<Target>MCTargetDesc`` files (both headers and source). 213 214 Intrinsic 215 --------- 216 217 **Purpose**: Generate (target) intrinsic information. 218 219 OptParserDefs 220 ------------- 221 222 **Purpose**: Print enum values for a class. 223 224 CTags 225 ----- 226 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. 230 231 Clang BackEnds 232 ============== 233 234 ClangAttrClasses 235 ---------------- 236 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``. 240 241 ClangAttrParserStringSwitches 242 ----------------------------- 243 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. 249 250 ClangAttrImpl 251 ------------- 252 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``. 256 257 ClangAttrList 258 ------------- 259 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. 267 268 ClangAttrPCHRead 269 ---------------- 270 271 **Purpose**: Creates AttrPCHRead.inc, which is used to deserialize attributes 272 in the ``ASTReader::ReadAttributes`` function. 273 274 ClangAttrPCHWrite 275 ----------------- 276 277 **Purpose**: Creates AttrPCHWrite.inc, which is used to serialize attributes in 278 the ``ASTWriter::WriteAttributes`` function. 279 280 ClangAttrSpellings 281 --------------------- 282 283 **Purpose**: Creates AttrSpellings.inc, which is used to implement the 284 ``__has_attribute`` feature test macro. 285 286 ClangAttrSpellingListIndex 287 -------------------------- 288 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``. 294 295 ClangAttrVisitor 296 ------------------- 297 298 **Purpose**: Creates AttrVisitor.inc, which is used when implementing 299 recursive AST visitors. 300 301 ClangAttrTemplateInstantiate 302 ---------------------------- 303 304 **Purpose**: Creates AttrTemplateInstantiate.inc, which implements the 305 ``instantiateTemplateAttribute`` function, used when instantiating a template 306 that requires an attribute to be cloned. 307 308 ClangAttrParsedAttrList 309 ----------------------- 310 311 **Purpose**: Creates AttrParsedAttrList.inc, which is used to generate the 312 ``AttributeList::Kind`` parsed attribute enumeration. 313 314 ClangAttrParsedAttrImpl 315 ----------------------- 316 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. 321 322 ClangAttrParsedAttrKinds 323 ------------------------ 324 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. 328 329 ClangAttrDump 330 ------------- 331 332 **Purpose**: Creates AttrDump.inc, which dumps information about an attribute. 333 It is used to implement ``ASTDumper::dumpAttr``. 334 335 ClangDiagsDefs 336 -------------- 337 338 Generate Clang diagnostics definitions. 339 340 ClangDiagGroups 341 --------------- 342 343 Generate Clang diagnostic groups. 344 345 ClangDiagsIndexName 346 ------------------- 347 348 Generate Clang diagnostic name index. 349 350 ClangCommentNodes 351 ----------------- 352 353 Generate Clang AST comment nodes. 354 355 ClangDeclNodes 356 -------------- 357 358 Generate Clang AST declaration nodes. 359 360 ClangStmtNodes 361 -------------- 362 363 Generate Clang AST statement nodes. 364 365 ClangSACheckers 366 --------------- 367 368 Generate Clang Static Analyzer checkers. 369 370 ClangCommentHTMLTags 371 -------------------- 372 373 Generate efficient matchers for HTML tag names that are used in documentation comments. 374 375 ClangCommentHTMLTagsProperties 376 ------------------------------ 377 378 Generate efficient matchers for HTML tag properties. 379 380 ClangCommentHTMLNamedCharacterReferences 381 ---------------------------------------- 382 383 Generate function to translate named character references to UTF-8 sequences. 384 385 ClangCommentCommandInfo 386 ----------------------- 387 388 Generate command properties for commands that are used in documentation comments. 389 390 ClangCommentCommandList 391 ----------------------- 392 393 Generate list of commands that are used in documentation comments. 394 395 ArmNeon 396 ------- 397 398 Generate arm_neon.h for clang. 399 400 ArmNeonSema 401 ----------- 402 403 Generate ARM NEON sema support for clang. 404 405 ArmNeonTest 406 ----------- 407 408 Generate ARM NEON tests for clang. 409 410 AttrDocs 411 -------- 412 413 **Purpose**: Creates ``AttributeReference.rst`` from ``AttrDocs.td``, and is 414 used for documenting user-facing attributes. 415 416 How to write a back-end 417 ======================= 418 419 TODO. 420 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 423 r173931. 424 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``. 428 429
