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 428
