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 Generate clang attribute clases.
 238
 239 ClangAttrParserStringSwitches
 240 -----------------------------
 241
 242 Generate all parser-related attribute string switches.
 243
 244 ClangAttrImpl
 245 -------------
 246
 247 Generate clang attribute implementations.
 248
 249 ClangAttrList
 250 -------------
 251
 252 Generate a clang attribute list.
 253
 254 ClangAttrPCHRead
 255 ----------------
 256
 257 Generate clang PCH attribute reader.
 258
 259 ClangAttrPCHWrite
 260 -----------------
 261
 262 Generate clang PCH attribute writer.
 263
 264 ClangAttrSpellingList
 265 ---------------------
 266
 267 Generate a clang attribute spelling list.
 268
 269 ClangAttrSpellingListIndex
 270 --------------------------
 271
 272 Generate a clang attribute spelling index.
 273
 274 ClangAttrASTVisitor
 275 -------------------
 276
 277 Generate a recursive AST visitor for clang attribute.
 278
 279 ClangAttrTemplateInstantiate
 280 ----------------------------
 281
 282 Generate a clang template instantiate code.
 283
 284 ClangAttrParsedAttrList
 285 -----------------------
 286
 287 Generate a clang parsed attribute list.
 288
 289 ClangAttrParsedAttrImpl
 290 -----------------------
 291
 292 Generate the clang parsed attribute helpers.
 293
 294 ClangAttrParsedAttrKinds
 295 ------------------------
 296
 297 Generate a clang parsed attribute kinds.
 298
 299 ClangAttrDump
 300 -------------
 301
 302 Generate clang attribute dumper.
 303
 304 ClangDiagsDefs
 305 --------------
 306
 307 Generate Clang diagnostics definitions.
 308
 309 ClangDiagGroups
 310 ---------------
 311
 312 Generate Clang diagnostic groups.
 313
 314 ClangDiagsIndexName
 315 -------------------
 316
 317 Generate Clang diagnostic name index.
 318
 319 ClangCommentNodes
 320 -----------------
 321
 322 Generate Clang AST comment nodes.
 323
 324 ClangDeclNodes
 325 --------------
 326
 327 Generate Clang AST declaration nodes.
 328
 329 ClangStmtNodes
 330 --------------
 331
 332 Generate Clang AST statement nodes.
 333
 334 ClangSACheckers
 335 ---------------
 336
 337 Generate Clang Static Analyzer checkers.
 338
 339 ClangCommentHTMLTags
 340 --------------------
 341
 342 Generate efficient matchers for HTML tag names that are used in documentation comments.
 343
 344 ClangCommentHTMLTagsProperties
 345 ------------------------------
 346
 347 Generate efficient matchers for HTML tag properties.
 348
 349 ClangCommentHTMLNamedCharacterReferences
 350 ----------------------------------------
 351
 352 Generate function to translate named character references to UTF-8 sequences.
 353
 354 ClangCommentCommandInfo
 355 -----------------------
 356
 357 Generate command properties for commands that are used in documentation comments.
 358
 359 ClangCommentCommandList
 360 -----------------------
 361
 362 Generate list of commands that are used in documentation comments.
 363
 364 ArmNeon
 365 -------
 366
 367 Generate arm_neon.h for clang.
 368
 369 ArmNeonSema
 370 -----------
 371
 372 Generate ARM NEON sema support for clang.
 373
 374 ArmNeonTest
 375 -----------
 376
 377 Generate ARM NEON tests for clang.
 378
 379 AttrDocs
 380 --------
 381
 382 Generate attribute documentation.
 383
 384 How to write a back-end
 385 =======================
 386
 387 TODO.
 388
 389 Until we get a step-by-step HowTo for writing TableGen backends, you can at
 390 least grab the boilerplate (build system, new files, etc.) from Clang's
 391 r173931.
 392
 393 TODO: How they work, how to write one.  This section should not contain details
 394 about any particular backend, except maybe ``-print-enums`` as an example.  This
 395 should highlight the APIs in ``TableGen/Record.h``.
 396