From: Renato Golin Date: Fri, 21 Mar 2014 16:49:43 +0000 (+0000) Subject: Add overall description, file comments, some structure X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=ec15d70712b94022cc51f62865daacd1562426a2;p=oota-llvm.git Add overall description, file comments, some structure git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@204479 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/TableGen/BackEnds.rst b/docs/TableGen/BackEnds.rst index 293af622e43..8f4c7d3c402 100644 --- a/docs/TableGen/BackEnds.rst +++ b/docs/TableGen/BackEnds.rst @@ -32,86 +32,201 @@ LLVM BackEnds of its purpose with a list of users, output generated from generic input, and finally why it needed a new backend (in case there's something similar). -Emitter -------- +Overall, each backend will take the same TableGen file type and transform into +similar output for different targets/uses. There is an implicit contract between +the TableGen files, the back-ends and their users. + +For instance, a global contract is that each back-end produces macro-guarded +sections. Based on whether the file is included by a header or a source file, +or even in which context of each file the include is being used, you have +todefine a macro just before including it, to get the right output: + +.. code-block:: c++ + + #define GET_REGINFO_TARGET_DESC + #include "ARMGenRegisterInfo.inc" + +And just part of the generated file would be included. This is useful if +you need the same information in multiple formats (instantiation, initialization, +getter/setter functions, etc) from the same source TableGen file without having +to re-compile the TableGen file multiple times. + +Sometimes, multiple macros might be defined before the same include file to +output multiple blocks: + +.. code-block:: c++ + + #define GET_REGISTER_MATCHER + #define GET_SUBTARGET_FEATURE_NAME + #define GET_MATCHER_IMPLEMENTATION + #include "ARMGenAsmMatcher.inc" + +The macros will be undef'd automatically as they're used, in the include file. + +On all LLVM back-ends, the ``llvm-tblgen`` binary will be executed on the root +TableGen file ``.td``, which should include all others. This guarantees +that all information needed is accessible, and that no duplication is needed +in the TbleGen files. -Generate machine code emitter. +CodeEmitter +----------- + +**Purpose**: CodeEmitterGen uses the descriptions of instructions and their fields to +construct an automated code emitter: a function that, given a MachineInstr, +returns the (currently, 32-bit unsigned) value of the instruction. + +**Output**: C++ code, implementing the target's CodeEmitter +class by overriding the virtual functions as ``CodeEmitter::function()``. + +**Usage**: Used to include directly at the end of ``CodeEmitter.cpp``, and +with option `-mc-emitter` to be included in ``MCCodeEmitter.cpp``. RegisterInfo ------------ -Generate registers and register classes info. +**Purpose**: This tablegen backend is responsible for emitting a description of a target +register file for a code generator. It uses instances of the Register, +RegisterAliases, and RegisterClass classes to gather this information. + +**Output**: C++ code with enums and structures representing the register mappings, +properties, masks, etc. + +**Usage**: Both on ``BaseRegisterInfo`` and ``MCTargetDesc`` (headers +and source files) with macros defining in which they are for declaration vs. +initialization issues. InstrInfo --------- -Generate instruction descriptions. +**Purpose**: This tablegen backend is responsible for emitting a description of the target +instruction set for the code generator. (what are the differences from CodeEmitter?) + +**Output**: C++ code with enums and structures representing the register mappings, +properties, masks, etc. + +**Usage**: Both on ``BaseInstrInfo`` and ``MCTargetDesc`` (headers +and source files) with macros defining in which they are for declaration vs. AsmWriter --------- -Generate calling convention descriptions. +**Purpose**: Emits an assembly printer for the current target. + +**Output**: Implementation of ``InstPrinter::printInstruction()``, among +other things. + +**Usage**: Included directly into ``InstPrinter/InstPrinter.cpp``. AsmMatcher ---------- -Generate assembly writer. +**Purpose**: Emits a target specifier matcher for +converting parsed assembly operands in the MCInst structures. It also +emits a matcher for custom operand parsing. Extensive documentation is +written on the ``AsmMatcherEmitter.cpp`` file. + +**Output**: Assembler parsers' matcher functions, declarations, etc. + +**Usage**: Used in back-ends' ``AsmParser/AsmParser.cpp`` for +building the AsmParser class. Disassembler ------------ -Generate disassembler. +**Purpose**: Contains disassembler table emitters for various +architectures. Extensive documentation is written on the +``DisassemblerEmitter.cpp`` file. + +**Output**: Decoding tables, static decoding functions, etc. + +**Usage**: Directly included in ``Disassembler/Disassembler.cpp`` +to cater for all default decodings, after all hand-made ones. PseudoLowering -------------- -Generate pseudo instruction lowering. +**Purpose**: Generate pseudo instruction lowering. + +**Output**: Implements ``ARMAsmPrinter::emitPseudoExpansionLowering()``. + +**Usage**: Included directly into ``AsmPrinter.cpp``. CallingConv ----------- -Generate assembly instruction matcher. +**Purpose**: Responsible for emitting descriptions of the calling +conventions supported by this target. + +**Output**: Implement static functions to deal with calling conventions +chained by matching styles, returning false on no match. + +**Usage**: Used in ISelLowering and FastIsel as function pointers to +implementation returned by a CC sellection function. DAGISel ------- -Generate a DAG instruction selector. +**Purpose**: Generate a DAG instruction selector. + +**Output**: Creates huge functions for automating DAG selection. + +**Usage**: Included in ``ISelDAGToDAG.cpp`` inside the target's +implementation of ``SelectionDAGISel``. DFAPacketizer ------------- -Generate DFA Packetizer for VLIW targets. +**Purpose**: This class parses the Schedule.td file and produces an API that +can be used to reason about whether an instruction can be added to a packet +on a VLIW architecture. The class internally generates a deterministic finite +automaton (DFA) that models all possible mappings of machine instructions +to functional units as instructions are added to a packet. + +**Output**: Scheduling tables for GPU back-ends (Hexagon, AMD). + +**Usage**: Included directly on ``InstrInfo.cpp``. FastISel -------- -Generate a "fast" instruction selector. +**Purpose**: This tablegen backend emits code for use by the "fast" +instruction selection algorithm. See the comments at the top of +lib/CodeGen/SelectionDAG/FastISel.cpp for background. This file +scans through the target's tablegen instruction-info files +and extracts instructions with obvious-looking patterns, and it emits +code to look up these instructions by type and operator. + +**Output**: Generates ``Predicate`` and ``FastEmit`` methods. + +**Usage**: Implements private methods of the targets' implementation +of ``FastISel`` class. Subtarget --------- -Generate subtarget enumerations. +**Purpose**: Generate subtarget enumerations. -Intrinsic ---------- +**Output**: Enums, globals, local tables for sub-target information. -Generate intrinsic information. +**Usage**: Populates ``Subtarget`` and +``MCTargetDesc/MCTargetDesc`` files (both headers and source). -TgtIntrinsic ------------- +Intrinsic +--------- -Generate target intrinsic information. +**Purpose**: Generate (target) intrinsic information. OptParserDefs ------------- -Print enum values for a class. +**Purpose**: Print enum values for a class. CTags ----- -Generate ctags-compatible index. - +**Purpose**: This tablegen backend emits an index of definitions in ctags(1) +format. A helper script, utils/TableGen/tdtags, provides an easier-to-use +interface; run 'tdtags -H' for documentation. Clang BackEnds ==============