diff --git a/llvm/docs/CommandGuide/tblgen.rst b/llvm/docs/CommandGuide/tblgen.rst --- a/llvm/docs/CommandGuide/tblgen.rst +++ b/llvm/docs/CommandGuide/tblgen.rst @@ -1,41 +1,56 @@ -tblgen - Target Description To C++ Code Generator -================================================= +xxx-tblgen: Target Description to C++ Code +========================================== .. program:: tblgen SYNOPSIS -------- -:program:`tblgen` [*options*] [*filename*] +:program:`xxx-tblgen` [*options*] [*filename*] DESCRIPTION ----------- -:program:`tblgen` translates from target description (``.td``) files into C++ -code that can be included in the definition of an LLVM target library. Most -users of LLVM will not need to use this program. It is only for assisting with -writing an LLVM target backend. +:program:`xxx-tblgen` is a family of programs that translates target +description (``.td``) files into C++ code and other output formats. Most +users of LLVM will not need to use this program. It is used only for +writing parts of the compiler or LLVM target backends. -The input and output of :program:`tblgen` is beyond the scope of this short -introduction; please see the :doc:`introduction to TableGen -<../TableGen/index>`. +The details of the input and output of :program:`xxx-tblgen` is beyond the +scope of this short introduction; please see the :doc:`TableGen Overview +<../TableGen/index>` for an introduction and for references to additional +TableGen documents. -The *filename* argument specifies the name of a Target Description (``.td``) -file to read as input. +The *filename* argument specifies the name of the Target Description (``.td``) +file that TableGen processes. OPTIONS ------- -.. program:: tblgen +General Options +~~~~~~~~~~~~~~~ .. option:: -help Print a summary of command line options. -.. option:: -o filename +.. option:: -D=macroname - Specify the output file name. If ``filename`` is ``-``, then - :program:`tblgen` sends its output to standard output. + Specify the name of a macro to be defined. The name is defined, but it + has no particular value. + +.. option:: -d=filename + + Specify the name of the dependency filename. + +.. option:: --debug + + Enable debug output. + +.. option:: -dump-json + + Print a JSON representation of all records, suitable for further + automated processing. .. option:: -I directory @@ -43,105 +58,642 @@ ``directory`` value should be a full or partial path to a directory that contains target description files. -.. option:: -asmparsernum N +.. option:: -o filename - Make -gen-asm-parser emit assembly writer number ``N``. + Specify the output file name. If ``filename`` is ``-``, then + :program:`xxx-tblgen` sends its output to standard output. -.. option:: -asmwriternum N +.. option:: -print-records - Make -gen-asm-writer emit assembly writer number ``N``. + Print all classes and records to standard output (default option). -.. option:: -class className +.. option:: -print-detailed-records - Print the enumeration list for this class. + Print a detailed report of all global variables, classes, and records + to standard output. -.. option:: -print-records +.. option:: --stats - Print all records to standard output (default). + Enable statistics output. -.. option:: -dump-json +.. option:: -write-if-changed - Print a JSON representation of all records, suitable for further - automated processing. + Write the output file only if it is new or has changed. The default + is true. -.. option:: -print-enums +llvm-tblgen Options +~~~~~~~~~~~~~~~~~~~ - Print enumeration values for a class. +.. option:: -gen-asm-matcher -.. option:: -print-sets + Generate assembly instruction matcher. - Print expanded sets for testing DAG exprs. +.. option:: -match-prefix=prefix + + Make -gen-asm-matcher match only instructions with the given *prefix*. + +.. option:: -gen-asm-parser + + Generate assembly instruction parser. + +.. option:: -asmparsernum=n + + Make -gen-asm-parser emit assembly parser number *n*. + +.. option:: -gen-asm-writer + + Generate assembly writer. + +.. option:: -asmwriternum=n + + Make -gen-asm-writer emit assembly writer number *n*. + +.. option:: -gen-attrs + + Geneerate attributes. + +.. option:: -gen-automata + + Generate generic automata. + +.. option:: -gen-callingconv + + Generate calling convention descriptions. + +.. option:: -gen-compress-inst-emitter + + Generate RISCV compressed instructions. + +.. option:: -gen-ctags + + Generate ctags-compatible index. + +.. option:: -gen-dag-isel + + Generate a DAG (directed acyclic graph) instruction selector. + +.. option:: -instrument-coverage + + Make -gen-dag-isel generate tables to help identify the patterns matched. + +.. option:: -omit-comments + + Make -gen-dag-isel omit comments. The default is false. + +.. option:: -gen-dfa-packetizer + + Generate DFA Packetizer for VLIW targets. + +.. option:: -gen-directive-decl + + Generate directive related declaration code (header file). + +.. option:: -gen-directive-gen + + Generate directive related implementation code part. + +.. option:: -gen-directive-impl + + Generate directive related implementation code. + +.. option:: -gen-disassembler + + Generate disassembler. .. option:: -gen-emitter Generate machine code emitter. -.. option:: -gen-register-info +.. option:: -gen-exegesis + + Generate llvm-exegesis tables. + +.. option:: -gen-fast-isel + + Generate a "fast" instruction selector. + +.. option:: -gen-global-isel + + Generate GlobalISel selector. + +.. option:: -gisel-coverage-file=filename + + Specify the file from which to retrieve coverage information. + +.. option:: -instrument-gisel-coverage + + Make -gen-global-isel generate coverage instrumentation. + +.. option:: -optimize-match-table + + Make -gen-global-isel generate an optimized version of the match table. + +.. option:: -warn-on-skipped-patterns - Generate registers and register classes info. + Make -gen-global-isel explain why a pattern was skipped for inclusion. + +.. option:: -gen-global-isel-combiner + + Generate GlobalISel combiner. + +.. option:: -combiners=list + + Make -gen-global-isel-combiner emit the specified combiners. + +.. option:: -gicombiner-show-expansions + + Make -gen-global-isel-combiner use C++ comments to indicate occurences + of code expansion. + +.. option:: -gicombiner-stop-after-build + + Make -gen-global-isel-combiner stop processing after building the match tree. + +.. option:: -gicombiner-stop-after-parse + + Make -gen-global-isel-combiner stop processing after parsing rules + and dump state. .. option:: -gen-instr-info Generate instruction descriptions. -.. option:: -gen-asm-writer +.. option:: -gen-instr-docs - Generate the assembly writer. + Generate instruction documentation. -.. option:: -gen-disassembler +.. option:: -gen-intrinsic-enums + + Generate intrinsic enums. + +.. option:: -intrinsic-prefix=prefix + + Make -gen-intrinsic-enums generate intrinsics with this target *prefix*. + +.. option:: -gen-intrinsic-impl + + Generate intrinsic information. - Generate disassembler. +.. option:: -gen-opt-parser-defs + + Generate options definitions. + +.. option:: -gen-opt-rst + + Generate option RST. .. option:: -gen-pseudo-lowering Generate pseudo instruction lowering. -.. option:: -gen-dag-isel +.. option:: -gen-register-bank - Generate a DAG (Directed Acyclic Graph) instruction selector. + Generate register bank descriptions. -.. option:: -gen-asm-matcher +.. option:: -gen-register-info - Generate assembly instruction matcher. + Generate registers and register classes info. -.. option:: -gen-dfa-packetizer +.. option:: -register-info-debug - Generate DFA Packetizer for VLIW targets. + Make -gen-register-info dump register information for debugging. -.. option:: -gen-fast-isel +.. option:: -gen-searchable-tables - Generate a "fast" instruction selector. + Generate generic searchable tables. See :doc:`TableGen BackEnds <./BackEnds>` + for a detailed description. .. option:: -gen-subtarget Generate subtarget enumerations. -.. option:: -gen-intrinsic-enums +.. option:: -gen-x86-EVEX2VEX-tables - Generate intrinsic enums. + Generate X86 EVEX to VEX compress tables. -.. option:: -gen-intrinsic-impl +.. option:: -gen-x86-fold-tables + + Generate X86 fold tables. + +.. option:: -long-string-literals - Generate intrinsic implementation. + When emitting large string tables, prefer string literals over + comma-separated char literals. This can be a readability and + compile-time performance win, but upsets some compilers. -.. option:: -gen-tgt-intrinsic +.. option:: -print-enums - Generate target intrinsic information. + Print enumeration values for a class. -.. option:: -gen-enhanced-disassembly-info +.. option:: -class=classname - Generate enhanced disassembly info. + Make -print-enums print the enumeration list for the specified class. -.. option:: -gen-exegesis +.. option:: -print-sets - Generate llvm-exegesis tables. + Print expanded sets for testing DAG exprs. .. option:: -version - Show the version number of this program. + Show the version number of the program. + + +clang-tblgen Options +~~~~~~~~~~~~~~~~~~~~ + +.. option:: -gen-clang-attr-classes + + Generate Clang attribute clases. + +.. option:: -gen-clang-attr-parser-string-switches + + Generate all parser-related attribute string switches. + +.. option:: -gen-clang-attr-subject-match-rules-parser-string-switches + + Generate all parser-related attribute subject match rule string switches. + +.. option:: -gen-clang-attr-impl + + Generate Clang attribute implementations. + +.. option:: -gen-clang-attr-list" + + Generate a Clang attribute list. + +.. option:: -gen-clang-attr-subject-match-rule-list + + Generate a Clang attribute subject match rule list. + +.. option:: -gen-clang-attr-pch-read + + Generate Clang PCH attribute reader. + +.. option:: -gen-clang-attr-pch-write + + Generate Clang PCH attribute writer. + +.. option:: -gen-clang-attr-has-attribute-impl + + Generate a Clang attribute spelling list. + +.. option:: -gen-clang-attr-spelling-index + + Generate a Clang attribute spelling index. + +.. option:: -gen-clang-attr-ast-visitor + + Generate a recursive AST visitor for Clang attributes. + +.. option:: -gen-clang-attr-template-instantiate + + Generate a Clang template instantiate code. + +.. option:: -gen-clang-attr-parsed-attr-list + + Generate a Clang parsed attribute list. + +.. option:: -gen-clang-attr-parsed-attr-impl + + Generate the Clang parsed attribute helpers. + +.. option:: -gen-clang-attr-parsed-attr-kinds + + Generate a Clang parsed attribute kinds. + +.. option:: -gen-clang-attr-text-node-dump + + Generate Clang attribute text node dumper. + +.. option:: -gen-clang-attr-node-traverse + + Generate Clang attribute traverser. + +.. option:: -gen-clang-diags-defs + + Generate Clang diagnostics definitions. + +.. option:: -clang-component component + + Only use warnings from specified component. + +.. option:: -gen-clang-diag-groups + + Generate Clang diagnostic groups. + +.. option:: -gen-clang-diags-index-name + + Generate Clang diagnostic name index. + +.. option:: -gen-clang-basic-reader + + Generate Clang BasicReader classes. + +.. option:: -gen-clang-basic-writer + + Generate Clang BasicWriter classes. + +.. option:: -gen-clang-comment-nodes + + Generate Clang AST comment nodes. + +.. option:: -gen-clang-decl-nodes + + Generate Clang AST declaration nodes. + +.. option:: -gen-clang-stmt-nodes + + Generate Clang AST statement nodes. + +.. option:: -gen-clang-type-nodes + + Generate Clang AST type nodes. + +.. option:: -gen-clang-type-reader + + Generate Clang AbstractTypeReader class. + +.. option:: -gen-clang-type-writer + + Generate Clang AbstractTypeWriter class. + +.. option:: -gen-clang-opcodes + + Generate Clang constexpr interpreter opcodes. + +.. option:: -gen-clang-sa-checkers + + Generate Clang static analyzer checkers. + +.. option:: -gen-clang-comment-html-tags + + Generate efficient matchers for HTML tag names that are used in + documentation comments. + +.. option:: -gen-clang-comment-html-tags-properties + + Generate efficient matchers for HTML tag properties. + +.. option:: -gen-clang-comment-html-named-character-references + + Generate function to translate named character references to UTF-8 sequences. + +.. option:: -gen-clang-comment-command-info + + Generate command properties for commands that are used in documentation comments. + +.. option:: -gen-clang-comment-command-list + + Generate list of commands that are used in documentation comments. + +.. option:: -gen-clang-opencl-builtins + + Generate OpenCL builtin declaration handlers. + +.. option:: -gen-arm-neon + + Generate ``arm_neon.h`` for Clang. + +.. option:: -gen-arm-fp16 + + Generate ``arm_fp16.h`` for Clang. + +.. option:: -gen-arm-bf16 + + Generate ``arm_bf16.h`` for Clang. + +.. option:: -gen-arm-neon-sema + + Generate ARM NEON sema support for Clang. + +.. option:: -gen-arm-neon-test + + Generate ARM NEON tests for Clang. + +.. option:: -gen-arm-sve-header + + Generate ``arm_sve.h`` for Clang. + +.. option:: -gen-arm-sve-builtins + + Generate ``arm_sve_builtins.inc`` for Clang. + +.. option:: -gen-arm-sve-builtin-codegen + + Generate ``arm_sve_builtin_cg_map.inc`` for Clang. + +.. option:: -gen-arm-sve-typeflags + + Generate ``arm_sve_typeflags.inc`` for Clang. + +.. option:: -gen-arm-sve-sema-rangechecks + + Generate ``arm_sve_sema_rangechecks.inc`` for Clang. + +.. option:: -gen-arm-mve-header + + Generate ``arm_mve.h`` for Clang. + +.. option:: -gen-arm-mve-builtin-def + + Generate ARM MVE builtin definitions for Clang. + +.. option:: -gen-arm-mve-builtin-sema + + Generate ARM MVE builtin sema checks for Clang. + +.. option:: -gen-arm-mve-builtin-codegen + + Generate ARM MVE builtin code-generator for Clang. + +.. option:: -gen-arm-mve-builtin-aliases + + Generate list of valid ARM MVE builtin aliases for Clang. + +.. option:: -gen-arm-cde-header + + Generate ``arm_cde.h`` for Clang. + +.. option:: -gen-arm-cde-builtin-def + + Generate ARM CDE builtin definitions for Clang. + +.. option:: -gen-arm-cde-builtin-sema + + Generate ARM CDE builtin sema checks for Clang. + +.. option:: -gen-arm-cde-builtin-codegen + + Generate ARM CDE builtin code-generator for Clang. + +.. option:: -gen-arm-cde-builtin-aliases + + Generate list of valid ARM CDE builtin aliases for Clang. + +.. option:: -gen-attr-docs + + Generate attribute documentation. + +.. option:: -gen-diag-docs + + Generate diagnostic documentation. + +.. option:: -gen-opt-docs + + Generate option documentation. + +.. option:: -gen-clang-data-collectors + + Generate data collectors for AST nodes. + +.. option:: -gen-clang-test-pragma-attribute-supported-attributes + + Generate a list of attributes supported by ``#pragma`` Clang attribute for + testing purposes. + + + +mlir-tblgen Options +~~~~~~~~~~~~~~~~~~~ + +.. option:: -gen-avail-interface-decls + + Generate availability interface declarations. + +.. option:: -gen-avail-interface-defs + + Generate op interface definitions. + +.. option:: -gen-dialect-doc + + Generate dialect documentation. + +.. option:: -dialect + + The dialect to generate. + +.. option:: -gen-directive-decl + + Generate declarations for directives (OpenMP, etc.). + +.. option:: -gen-enum-decls + + Generate enum utility declarations. + +.. option:: -gen-enum-defs + + Generate enum utility definitions. + +.. option:: -gen-enum-from-llvmir-conversions + + Generate conversions of EnumAttrs from LLVM IR. + +.. option:: -gen-enum-to-llvmir-conversions + + Generate conversions of EnumAttrs to LLVM IR. + +.. option:: -gen-llvmir-conversions + + Generate LLVM IR conversions. + +.. option:: -gen-llvmir-intrinsics + + Generate LLVM IR intrinsics. + +.. option:: -llvmir-intrinsics-filter + + Only keep the intrinsics with the specified substring in their record name. + +.. option:: -dialect-opclass-base + + The base class for the ops in the dialect we are to emit. + +.. option:: -gen-op-decls + + Generate operation declarations. + +.. option:: -gen-op-defs + + Generate operation definitions. + +.. option:: -asmformat-error-is-fatal + + Emit a fatal error if format parsing fails. + +.. option:: -op-exclude-regex + + Regular expression of name of ops to exclude (no filter if empty). + +.. option:: -op-include-regex + + Regular expression of name of ops to include (no filter if empty). + +.. option:: -gen-op-doc + + Generate operation documentation. + +.. option:: -gen-pass-decls + + Generate operation documentation. + +.. option:: -name namestring + + The name of this group of passes. + +.. option:: -gen-pass-doc + + Generate pass documentation. + +.. option:: -gen-rewriters + + Generate pattern rewriters. + +.. option:: -gen-spirv-avail-impls + + Generate SPIR-V operation utility definitions. + +.. option:: -gen-spirv-capability-implication + + Generate utility function to return implied capabilities for a given capability. + +.. option:: -gen-spirv-enum-avail-decls + + Generate SPIR-V enum availability declarations. + +.. option:: -gen-spirv-enum-avail-defs + + Generate SPIR-V enum availability definitions. + +.. option:: -gen-spirv-op-utils + + Generate SPIR-V operation utility definitions. + +.. option:: -gen-spirv-serialization + + Generate SPIR-V (de)serialization utilities and functions. + +.. option:: -gen-struct-attr-decls + + Generate struct utility declarations. + +.. option:: -gen-struct-attr-defs + + Generate struct utility definitions. + +.. option:: -gen-typedef-decls + + Generate TypeDef declarations. + +.. option:: -gen-typedef-defs + + Generate TypeDef definitions. + +.. option:: -typedefs-dialect name + + Generate types for this dialect. EXIT STATUS ----------- -If :program:`tblgen` succeeds, it will exit with 0. Otherwise, if an error +If :program:`xxx-tblgen` succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non-zero value. diff --git a/llvm/docs/TableGen/Deficiencies.rst b/llvm/docs/TableGen/Deficiencies.rst deleted file mode 100644 --- a/llvm/docs/TableGen/Deficiencies.rst +++ /dev/null @@ -1,31 +0,0 @@ -===================== -TableGen Deficiencies -===================== - -.. contents:: - :local: - -Introduction -============ - -Despite being very generic, TableGen has some deficiencies that have been -pointed out numerous times. The common theme is that, while TableGen allows -you to build Domain-Specific-Languages, the final languages that you create -lack the power of other DSLs, which in turn increase considerably the size -and complexity of TableGen files. - -At the same time, TableGen allows you to create virtually any meaning of -the basic concepts via custom-made back-ends, which can pervert the original -design and make it very hard for newcomers to understand it. - -There are some in favour of extending the semantics even more, but making sure -back-ends adhere to strict rules. Others suggesting we should move to more -powerful DSLs designed with specific purposes, or even re-using existing -DSLs. - -Known Problems -============== - -TODO: Add here frequently asked questions about why TableGen doesn't do -what you want, how it might, and how we could extend/restrict it to -be more use friendly. diff --git a/llvm/docs/TableGen/ProgRef.rst b/llvm/docs/TableGen/ProgRef.rst --- a/llvm/docs/TableGen/ProgRef.rst +++ b/llvm/docs/TableGen/ProgRef.rst @@ -21,8 +21,11 @@ developer needs. This document describes the LLVM TableGen facility in detail. It is intended -for the programmer who is using TableGen to produce tables for a project. If -you are looking for a simple overview, check out :doc:`TableGen Overview <./index>`. +for the programmer who is using TableGen to produce code for a project. If +you are looking for a simple overview, check out the :doc:`TableGen Overview +<./index>`. The various ``xxx-tblgen`` commands used to invoke TableGen are +described in :doc:`xxx-tblgen: Target Description to C++ Code +<../CommandGuide/tblgen>`. An example of a backend is ``RegisterInfo``, which generates the register file information for a particular target machine, for use by the LLVM @@ -1662,9 +1665,10 @@ ``!subst(``\ *target*\ ``,`` *repl*\ ``,`` *value*\ ``)`` This operator replaces all occurrences of the *target* in the *value* with - the *repl* and produces the resulting value. For strings, this is straightforward. + the *repl* and produces the resulting value. The *value* can + be a string, in which case substring substitution is performed. - If the arguments are record names, the function produces the *repl* + The *value* can be a record name, in which case the operator produces the *repl* record if the *target* record name equals the *value* record name; otherwise it produces the *value*. diff --git a/llvm/docs/TableGen/index.rst b/llvm/docs/TableGen/index.rst --- a/llvm/docs/TableGen/index.rst +++ b/llvm/docs/TableGen/index.rst @@ -23,10 +23,12 @@ amount of duplication in the description, reduces the chance of error, and makes it easier to structure domain specific information. -The core part of TableGen parses a file, instantiates the declarations, and -hands the result off to a domain-specific `backend`_ for processing. -See the :doc:`TableGen Programmer's Reference <./ProgRef>` for an in-depth -description of TableGen. +The TableGen front end parses a file, instantiates the declarations, and +hands the result off to a domain-specific `backend`_ for processing. See +the :doc:`TableGen Programmer's Reference <./ProgRef>` for an in-depth +description of TableGen. See :doc:`xxx-tblgen: Target Description to C++ +Code <../CommandGuide/tblgen>` for details on the various +``xxx-tblgen`` commands that invoke TableGen. The current major users of TableGen are :doc:`The LLVM Target-Independent Code Generator <../CodeGenerator>` and the `Clang diagnostics and attributes @@ -286,7 +288,7 @@ Despite being very generic, TableGen has some deficiencies that have been pointed out numerous times. The common theme is that, while TableGen allows -you to build Domain-Specific-Languages, the final languages that you create +you to build domain specific languages, the final languages that you create lack the power of other DSLs, which in turn increase considerably the size and complexity of TableGen files. @@ -295,10 +297,7 @@ design and make it very hard for newcomers to understand the evil TableGen file. -There are some in favour of extending the semantics even more, but making sure +There are some in favor of extending the semantics even more, but making sure backends adhere to strict rules. Others are suggesting we should move to less, -more powerful DSLs designed with specific purposes, or even re-using existing +more powerful DSLs designed with specific purposes, or even reusing existing DSLs. - -Either way, this is a discussion that will likely span across several years, -if not decades. You can read more in :doc:`TableGen Deficiencies <./Deficiencies>`.