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>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