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