docs/TableGen/BackEnds.rst

   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